# strrl/cloudflare-tunnel-ingress-controller architecture

> Architecture diagram of the GitHub repository strrl/cloudflare-tunnel-ingress-controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strrl/cloudflare-tunnel-ingress-controller
- Repository: https://github.com/strrl/cloudflare-tunnel-ingress-controller

## Overview

##### Project type and purpose
- This is an open-source Kubernetes “Ingress Controller” / operator written in Go.
- It watches Kubernetes Ingress resources annotated with a special class (`cloudflare-tunnel`), automatically provisions or reuses a Cloudflare Tunnel, updates DNS, and runs “cloudflared” connector pods under the hood so that any Kubernetes Service can be exposed securely through Cloudflare’s network.

##### File structure
- cmd/cloudflare-tunnel-ingress-controller: the entry point (main.go) that sets up the controller loop.
- pkg/cloudflare-controller: logic for speaking to the Cloudflare API (tunnel creation, DNS record management, etc.).
- pkg/controller: Kubernetes controller logic (watching Ingress resources, creating connector pods, updating Ingress status, etc.).
- pkg/exposure: shared abstractions for constructing exposure configuration.
- helm/cloudflare-tunnel-ingress-controller: Helm Chart to package and deploy the controller as a Kubernetes Deployment, RBAC, ServiceAccount, etc.
- image/cloudflare-tunnel-ingress-controller/Dockerfile: container image for the controller and embedded “cloudflared” binary.
- hack/dev: example manifests for local development (namespaces, ingress-class, etc.).
- .github/workflows: CI pipelines for unit tests, integration tests, container image builds, Helm linting.

##### README for additional insights
- Describes how the controller bootstraps a Cloudflare Tunnel if it doesn’t exist, how users annotate a Kubernetes Ingress to route traffic, and how the Helm Chart parameters configure API tokens and account IDs.
- Emphasizes a feedback loop: user writes an Ingress → controller reconciles → calls Cloudflare API → deploys connector pods → updates DNS → traffic flows.

##### Final advice
- Be very detailed: break the controller into its two main subcomponents (K8s watcher vs. API client).
- Conditional logic (e.g., “if tunnel doesn’t exist → create”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Local
    subgraph "Developer Local" 
        direction TB
        User["User / DevOps CLI"]:::dev
        Helm["Helm / kubectl"]:::dev
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        direction TB
        APIServer["Kubernetes API Server"]:::cluster
        Ingress["Ingress Resource\n(annotation: cloudflare-tunnel)"]:::cluster
        ControllerPod["Controller Pod"]:::cluster
        subgraph "Controller Pod Components"
            direction TB
            K8sWatcher["K8s Watcher\n(pkg/controller)"]:::cluster
            APIClient["Cloudflare API Client\n(pkg/cloudflare-controller)"]:::cluster
        end
        ConnectorPods["Connector Pods\n(headless cloudflared)"]:::cluster
        Service["Kubernetes Service"]:::cluster
        RBAC["RBAC & ServiceAccount"]:::cluster
        subgraph "Helm Chart"
            direction TB
            Chart["Helm Chart Deployment\n(helm/cloudflare-tunnel-ingress-controller)"]:::dev
        end
    end

    %% Cloudflare Infrastructure
    subgraph "Cloudflare Infrastructure"
        direction TB
        CFAPI["Cloudflare API"]:::external
        DNSZone["DNS Zone (Cloudflare DNS)"]:::external
        TunnelNet["Cloudflare Tunnel Service"]:::external
    end

    %% Flows
    User -->|"run helm install/apply"| Helm
    Helm -->|deploys manifests| Chart
    Chart -->|creates| APIServer
    APIServer -->|stores resources| Ingress
    ControllerPod -->|watches| Ingress
    Ingress -->|event| K8sWatcher
    K8sWatcher -->|reconcile| APIClient
    APIClient -->|ensure tunnel| CFAPI
    CFAPI -->|manages| TunnelNet
    APIClient -->|update DNS record| DNSZone
    K8sWatcher -->|create/update pods| ConnectorPods
    TunnelNet -->|route traffic| ConnectorPods
    ConnectorPods -->|forward to| Service

    %% Click Events
    click User "https://github.com/strrl/cloudflare-tunnel-ingress-controller/tree/master/hack/dev/"
    click Helm "https://github.com/strrl/cloudflare-tunnel-ingress-controller/tree/master/helm/cloudflare-tunnel-ingress-controller/"
    click Chart "https://github.com/strrl/cloudflare-tunnel-ingress-controller/tree/master/helm/cloudflare-tunnel-ingress-controller/"
    click APIServer "https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/pkg/controller/ingress-controller.go"
    click Ingress "https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/pkg/controller/well_known_annotations.go"
    click ControllerPod "https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/cmd/cloudflare-tunnel-ingress-controller/main.go"
    click K8sWatcher "https://github.com/strrl/cloudflare-tunnel-ingress-controller/tree/master/pkg/controller/"
    click APIClient "https://github.com/strrl/cloudflare-tunnel-ingress-controller/tree/master/pkg/cloudflare-controller/"
    click ConnectorPods "https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/pkg/controller/controlled-cloudflared-connector.go"
    click Service "https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/pkg/exposure/exposure.go"
    click RBAC "https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/helm/cloudflare-tunnel-ingress-controller/templates/rbac.yaml"
    click CFAPI "https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/pkg/cloudflare-controller/bootstrap.go"
    click DNSZone "https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/pkg/cloudflare-controller/dns.go"
    click TunnelNet "https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/pkg/cloudflare-controller/tunnel-client.go"

    %% Classes
    classDef dev fill:#D6E9FF,stroke:#3399FF,color:#000;
    classDef cluster fill:#E8F5E9,stroke:#3C763D,color:#000;
    classDef external fill:#FFF3E0,stroke:#E65100,color:#000;
```
