# papanito/ansible-role-cloudflared architecture

> Architecture diagram of the GitHub repository papanito/ansible-role-cloudflared, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/papanito/ansible-role-cloudflared
- Repository: https://github.com/papanito/ansible-role-cloudflared

## Overview

##### Project Type and Purpose
- This is an Ansible Role (papanito.cloudflared) published on Ansible Galaxy.
- Purpose: automate the installation, configuration, and management of Cloudflare’s cloudflared daemon and optional SSH client proxy-through tunnels on remote Linux hosts.

##### File Structure Analysis
- Top-level: meta files for GitHub & Ansible (README.md, LICENSE, .github/, .gitignore, VERSION, CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md).
- Role directories:
- defaults/ – default variables (main.yml)
- vars/ – additional vars (main.yml)
- tasks/ – main.yml plus discrete task files (install, configure_initv, configure_systemd, create_routes_*, ssh_client_config, remove_*)
- handlers/ – service restart/stop handlers (main.yml)
- templates/ – Jinja2 templates for systemd units, initv scripts, cloudflared YAML, tunnel JSON
- tests/ – molecule-style test playbook, inventories
- meta/ – role metadata (main.yml)
- CI: .github/workflows/build.yml & release.yml
- Config: .ansible-lint, .ansible-lint-ignore, .config

##### Key Insights from README
- Two main features:
a. Server-side daemon installation & tunnel setup (download binary, auth, config files, systemd/initv, DNS/CIDR/LB routes)
b. SSH client config for proxying through tunnels
- Variables control all behavior (cf_download_baseurl, cf_tunnels, cf_init_system, cf_ssh_client_config, etc.)
- Role is idempotent, uses handlers to restart cloudflared on config change
- External dependencies: GitHub releases API for download, Cloudflare API for route creation, local system init

a. Main Components
- Control Plane (Ansible Master)
– Role source code (Git repo / Galaxy)
– CI/CD workflows (GitHub Actions)
– Ansible Engine orchestrating playbooks
- Target Hosts
– SSH connection from Ansible
– cloudflared binary & system service (systemd or initv)
– Configuration directory (/etc/cloudflared) & credentials directory (/root/.cloudflared)
– SSH client config (~/.ssh/config) if enabled
- External Services
– GitHub Releases (binary download endpoint)
– Cloudflare API (tunnel creation, DNS/CIDR/LB route management)
– Cloudflare Edge Network (actual tunnel traffic)

b. Relationships & Data Flow
1. Ansible Master → SSH → Target Host
- Tasks: install binary, copy cert, render templates, register handlers
2. Target Host → GitHub Releases
- HTTP(S) GET cloudflared binary
3. Target Host → Cloudflare API
- Tunnel route commands (cloudflared tunnel route ip/dns/lb) invoked locally
4. Target Host → Cloudflare Edge
- Persistent TLS-encrypted tunnel traffic from cloudflared daemon
5. (Optional) Control Plane → GitHub Actions → Build & release new role versions

c. Architectural Patterns & Design Principles
- Idempotent tasks broken into granular files (single responsibility)
- Handlers decoupled from tasks (only fire on change)
- Variable-driven templates for maximum flexibility
- Modular layout follows Ansible best practices (defaults, vars, tasks, handlers, templates, meta, tests)
- CI/CD for linting, testing, and automated releases

d. Key Technologies & Frameworks
- Ansible (roles, playbooks, modules)
- Jinja2 templates
- systemd or SysV-init (cloudflared@.service vs init scripts)
- cloudflared daemon (Go binary)
- GitHub Actions for CI/CD
- Cloudflare APIs

##### Essential Elements to Capture
- Role filesystem layout driving task execution
- Variable precedence and where configs originate
- Handler notifications triggering service restarts
- Dual init-system support (systemd vs initv)
- Route creation loops (DNS, CIDR, LB)
- CI/CD pipeline integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane" 
        direction TB
        GitRepo["Role Source Code"]:::controlPlane
        AnsibleEngine["Ansible Engine"]:::controlPlane
        CI_Build["CI Build Workflow"]:::controlPlane
        CI_Release["CI Release Workflow"]:::controlPlane
        LintConfig["Ansible-Lint Config"]:::controlPlane

        subgraph "Role Files"
            direction TB
            Defaults["defaults/main.yml"]:::controlPlane
            Vars["vars/main.yml"]:::controlPlane
            TasksMain["tasks/main.yml"]:::controlPlane
            Handlers["handlers/main.yml"]:::controlPlane
            Templates["templates/"]:::controlPlane
            Meta["meta/main.yml"]:::controlPlane
            Tests["tests/"]:::controlPlane
        end
    end

    %% Target Host
    subgraph "Target Host" 
        direction TB
        SSHConn["SSH Connection"]:::targetHost
        Binary["cloudflared Binary"]:::targetHost
        ServiceSysd["systemd Service"]:::targetHost
        ServiceInitv["SysV-Init Service"]:::targetHost
        ConfigDir["/etc/cloudflared"]:::targetHost
        CredDir["/root/.cloudflared"]:::targetHost
        SSHConfig["~/.ssh/config"]:::targetHost
        TunnelTraffic["TLS Tunnel Traffic"]:::targetHost
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GitHubReleases["GitHub Releases"]:::external
        CloudflareAPI["Cloudflare API"]:::external
        CloudflareEdge["Cloudflare Edge Network"]:::external
    end

    %% Connections
    GitRepo -->|push| CI_Build
    GitRepo -->|push| CI_Release
    CI_Build -->|lint & test| AnsibleEngine
    CI_Release -->|release role| GitRepo

    AnsibleEngine -->|ansible-playbook → SSH| SSHConn
    SSHConn -->|exec tasks| TasksMain

    TasksMain --> Defaults
    TasksMain --> Vars
    TasksMain --> InstallBinary["Install cloudflared Binary"]:::controlPlane
    TasksMain --> ConfigureInitv["Configure SysV-Init Service"]:::controlPlane
    TasksMain --> ConfigureSystemd["Configure systemd Service"]:::controlPlane
    TasksMain --> ConfigureSysctl["Apply Kernel Parameters"]:::controlPlane
    TasksMain --> ConfigureTunnels["Render Tunnel Definitions"]:::controlPlane
    TasksMain --> CreateRoutes["Create All Routes"]:::controlPlane
    TasksMain --> SSHClient["Configure SSH Client Proxy"]:::controlPlane
    TasksMain --> RemoveCert["Remove Installed Certificate"]:::controlPlane
    TasksMain --> RemoveTunnels["Remove Tunnels"]:::controlPlane
    TasksMain --> Handlers

    InstallBinary -->|downloads| Binary
    Binary -->|install| ServiceSysd
    Binary -->|install| ServiceInitv

    ConfigureSystemd --> ServiceSysd
    ConfigureInitv --> ServiceInitv
    ConfigureSysctl --> ServiceSysd
    ConfigureSysctl --> ServiceInitv

    ConfigureTunnels --> ConfigDir
    ConfigureTunnels --> CredDir

    CreateRoutes --> CIDRRoutes["Create CIDR-Based Routes"]:::controlPlane
    CreateRoutes --> DNSRoutes["Create DNS-Based Routes"]:::controlPlane
    CreateRoutes --> LBRoutes["Create Load-Balancer Routes"]:::controlPlane

    SSHClient --> SSHConfig

    Handlers --> ServiceSysd
    Handlers --> ServiceInitv

    Binary -->|GET binary| GitHubReleases
    CIDRRoutes -->|cloudflared tunnel route ip| CloudflareAPI
    DNSRoutes -->|cloudflared tunnel route dns| CloudflareAPI
    LBRoutes -->|cloudflared tunnel route lb| CloudflareAPI

    ServiceSysd -->|TLS tunnel| CloudflareEdge
    ServiceInitv -->|TLS tunnel| CloudflareEdge

    %% Click Events
    click Defaults "https://github.com/papanito/ansible-role-cloudflared/blob/main/defaults/main.yml"
    click Vars "https://github.com/papanito/ansible-role-cloudflared/blob/main/vars/main.yml"
    click TasksMain "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/main.yml"
    click InstallBinary "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/install.yml"
    click ConfigureInitv "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/configure_initv.yml"
    click ConfigureSystemd "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/configure_systemd.yml"
    click ConfigureSysctl "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/configure_sysctl.yml"
    click ConfigureTunnels "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/configure_tunnels.yml"
    click CreateRoutes "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/create_routes.yml"
    click CIDRRoutes "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/create_routes_cidr.yml"
    click DNSRoutes "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/create_routes_dns.yml"
    click LBRoutes "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/create_routes_lb.yml"
    click SSHClient "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/ssh_client_config.yml"
    click RemoveCert "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/remove_setup_certificate.yml"
    click RemoveTunnels "https://github.com/papanito/ansible-role-cloudflared/blob/main/tasks/remove_tunnels.yml"
    click Handlers "https://github.com/papanito/ansible-role-cloudflared/blob/main/handlers/main.yml"
    click Templates "https://github.com/papanito/ansible-role-cloudflared/tree/main/templates/"
    click Meta "https://github.com/papanito/ansible-role-cloudflared/blob/main/meta/main.yml"
    click Tests "https://github.com/papanito/ansible-role-cloudflared/blob/main/tests/test.yml"
    click CI_Build "https://github.com/papanito/ansible-role-cloudflared/blob/main/.github/workflows/build.yml"
    click CI_Release "https://github.com/papanito/ansible-role-cloudflared/blob/main/.github/workflows/release.yml"
    click LintConfig "https://github.com/papanito/ansible-role-cloudflared/blob/main/.ansible-lint"

    %% Styles
    classDef controlPlane fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef targetHost fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
```
