# containeroo/cloudflare-operator architecture

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

- Interactive diagram: https://gitdiagram.com/containeroo/cloudflare-operator
- Repository: https://github.com/containeroo/cloudflare-operator

## Overview

This project is a Kubernetes operator named cloudflare-operator, designed for managing Cloudflare DNS records through Kubernetes Custom Resource Definitions (CRDs). The operator lets users define desired DNS record states within Kubernetes, and its controllers reconcile these states with the actual DNS records in Cloudflare, including automatic IP address updates.

##### Main Components
- CRD/API Layer: Represent the custom resource definitions (within the "api/v1" folder) that define Cloudflare DNS records, IP addresses, accounts, and zones. These serve as the interface between the Kubernetes API and the operator.
- Controllers/Reconciler Logic: Highlight the controllers (found in "internal/controller/") such as the account, dnsrecord, ip, zone, and ingress controllers. Each controller is responsible for handling its corresponding CRD and ensuring the desired state is maintained on Cloudflare.
- Internal Business Logic: Include the internal packages such as "internal/conditions", "internal/metrics", and "internal/predicates" that facilitate conditions validation, metrics collection, and event filtering.
- Kubernetes Environment: Since the operator extends Kubernetes, include a Kubernetes cluster component that shows the relationship with the Kubernetes API server, CRD registration, and the reconciliation loop.

##### Relationships and Interactions
- The CRDs defined (API Layer) feed into the operator manager, which launches the appropriate controllers.
- Each controller constantly watches its custom resource objects, receives events from the Kubernetes API server, and triggers its reconciliation loop.
- During reconciliation, controllers interact with external or internal helper modules (e.g., conditions, metrics).
- Once a change is needed, controllers make API calls to Cloudflare.
- Bidirectional communication: Kubernetes events (via API server) flow into the operator, and changes involving Cloudflare APIs impact the state reflected back in Kubernetes.

##### Architectural Patterns and Design Principles
- Operator Pattern: This leverages Kubernetes API extensions to manage external resources (Cloudflare DNS records).
- Controller Pattern: Emphasize that each controller encapsulates its reconciliation logic to ensure the actual system state meets the declared desired state.
- Separation of Concerns: Each layer (CRD definitions in api, business logic in internal modules, operational control in cmd/main.go) is well-defined.
- Test and CI/CD Integration: The inclusion of e2e tests ("test/e2e") and CI workflows from the ".github/workflows" directory indicate a robust development pipeline.

- Since cloudflare-operator is a Kubernetes operator, focus on clearly delineating:
- The CRD registration flow (via "config/crd" and "config/samples"),
- The operator manager (main binary in "cmd"),
- Controllers’ reconciliation loops (with what they watch and how they trigger operations on external Cloudflare APIs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        API_Server["Kubernetes API Server"]:::kube
        subgraph "CRD Registration & Configuration"
            CRD_Def["CRD Definitions"]:::kube
            Sample_Res["Sample Resources"]:::kube
        end
    end

    %% Operator Components
    subgraph "Operator Components"
        OM["Operator Manager"]:::operator
        CRDLayer["CRD/API Layer"]:::operator
        Controllers["Controllers/Reconciler Logic"]:::controller
        subgraph "Internal Business Logic"
            Conditions["Conditions"]:::internal
            Metrics["Metrics"]:::internal
            Predicates["Predicates"]:::internal
        end
    end

    %% External Services
    subgraph "External Services"
        Cloudflare["Cloudflare API"]:::external
    end

    %% Relationships
    API_Server -->|"CRD_registration"| CRDLayer
    CRDLayer -->|"init_operator"| OM
    API_Server -->|"events"| OM
    OM -->|"launch_controllers"| Controllers
    Controllers -->|"use_conditions"| Conditions
    Controllers -->|"use_metrics"| Metrics
    Controllers -->|"use_predicates"| Predicates
    Controllers -->|"api_call"| Cloudflare
    Cloudflare -->|"state_update"| API_Server

    %% Click Events
    click CRDLayer "https://github.com/containeroo/cloudflare-operator/tree/master/api/v1"
    click OM "https://github.com/containeroo/cloudflare-operator/blob/master/cmd/main.go"
    click Controllers "https://github.com/containeroo/cloudflare-operator/tree/master/internal/controller"
    click Conditions "https://github.com/containeroo/cloudflare-operator/tree/master/internal/conditions"
    click Metrics "https://github.com/containeroo/cloudflare-operator/tree/master/internal/metrics"
    click Predicates "https://github.com/containeroo/cloudflare-operator/tree/master/internal/predicates"
    click CRD_Def "https://github.com/containeroo/cloudflare-operator/tree/master/config/crd"
    click Sample_Res "https://github.com/containeroo/cloudflare-operator/tree/master/config/samples"

    %% Styles
    classDef kube fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef operator fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef controller fill:#32CD32,stroke:#000,stroke-width:2px;
    classDef internal fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef external fill:#FF6347,stroke:#000,stroke-width:2px;
```
