# dopplerhq/kubernetes-operator architecture

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

- Interactive diagram: https://gitdiagram.com/dopplerhq/kubernetes-operator
- Repository: https://github.com/dopplerhq/kubernetes-operator

## Overview

##### Project Type and Purpose
- This is a Kubernetes Operator (a controller built with the Operator SDK in Go).
- Its purpose is to watch custom resources of kind DopplerSecret, fetch secrets from the external Doppler API, and sync those secrets into native Kubernetes Secret objects. It also optionally patches Deployments to trigger rolling updates when secrets change.

##### File Structure
Top-level directories and files:
- api/v1alpha1: CRD Go types (DopplerSecret) and code generation output.
- controllers: Reconciler logic for DopplerSecret resources.
- config:
– crd/bases: YAML for CRD installation.
– manager: Manager Deployment manifest and patches.
– rbac: ServiceAccount & Roles/RoleBindings for the operator.
– samples: Example DopplerSecret and Deployment specs.
– prometheus/scorecard: Monitoring and testing configs.
- hack/helm: Helm chart assets.
- main.go: Operator entrypoint.
- pkg: Shared libraries—Doppler API client, secret-processing logic, version info.
- tools: Utility scripts (log tailing, secret dumps).
- Dockerfile, Makefile, GitHub workflows: CI/CD, container build, release pipeline.

##### README for Architecture Clues
- Operator runs as a Deployment in the doppler-operator-system namespace.
- Installs a CRD DopplerSecret.
- Watches both the DopplerSecret custom resource and referenced native Secrets & Deployments.
- Fetches secrets from an external Doppler REST API.
- Updates/creates a managed Kubernetes Secret, and if enabled, patches a Deployment annotation to trigger pod restarts.

##### Main Components
– API Server & etcd (control plane)
– Operator Deployment (one or more Pods)
– CustomResourceDefinition (DopplerSecret)
– Native Kubernetes Secrets (Doppler Token Secret + Managed Secret)
– Target Deployments (annotated for auto-reload)
b. External Doppler API

##### Relationships and Data Flows
1. Operator Pod registers with APIServer using RBAC.
2. APIServer serves DopplerSecret CRDs and watches Events on Secrets and Deployments.
3. Reconciler loop:
- On DopplerSecret creation/update → read tokenSecret from native Secret
- Call External Doppler API → fetch secrets payload
- Write/patch Managed Secret in Kubernetes
- If `secrets.doppler.com/reload: "true"`, patch the target Deployment annotation
4. Kubernetes Deployment Controller sees annotation change → rolling update of Pods.

##### Architectural Patterns & Design Principles
- Controller-pattern (Reconciler loop)
- Custom Resource Definition to extend Kubernetes API
- Separation of concerns:
– api/ folder holds only type definitions
– controllers/ folder holds reconciliation logic
– pkg/ holds shared utility code (Doppler client, name transformers, processors)
- Configuration as code via kustomize (config/*) and Helm (hack/helm)
- Declarative GitOps–style deployment via kubectl or Helm chart

##### Technologies, Frameworks, Libraries
- Go + Operator SDK
- client-go / controller-runtime
- Kustomize (config/*.yaml)
- Helm (hack/helm)
- GitHub Actions & DockerHub for CI/CD
- Prometheus Operator (scorecard tests)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane
    subgraph "Control Plane"
        APIServer["API Server"]:::control
        ETCD["etcd"]:::control
        subgraph "Cluster Extensions"
            CRDManifest["DopplerSecret CRD"]:::k8s
        end
    end

    %% Data Plane
    subgraph "Data Plane"
        subgraph "Operator Namespace"
            OperatorPod["Operator Pod"]:::operator
            Reconciler["Reconciler Logic"]:::operator
            APIClient["Doppler API Client"]:::operator
            SecretProcessors["Secret Processing Utilities"]:::operator
            DataModels["Secret Data Models"]:::operator
            VersionInfo["Version Info"]:::operator
        end
        TokenSecret["Token Secret"]:::k8s
        ManagedSecret["Managed Kubernetes Secret"]:::k8s
        TargetDeployment["Target Deployment"]:::k8s
    end

    %% External System
    ExternalAPI["External Doppler API"]:::external

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GitHub["GitHub Actions"]:::ci
        DockerHub["DockerHub"]:::ci
    end

    %% Data Flows
    OperatorPod -->|"1 watches CRD & resources"| APIServer
    APIServer -->|serves CRD| CRDManifest
    OperatorPod -->|"2 reads Token Secret"| TokenSecret
    OperatorPod -->|"3 fetch secrets"| ExternalAPI
    ExternalAPI -->|"4 returns secrets payload"| OperatorPod
    OperatorPod -->|"5 create/update Managed Secret"| ManagedSecret
    OperatorPod -->|"6 patch Deployment annotation"| TargetDeployment
    TargetDeployment -->|"7 triggers rolling update"| APIServer

    %% CI/CD Flow
    GitHub -->|"build & push"| DockerHub
    DockerHub -->|"deploy image"| OperatorPod

    %% Click Events
    click CRDManifest "https://github.com/dopplerhq/kubernetes-operator/blob/main/config/crd/bases/secrets.doppler.com_dopplersecrets.yaml"
    click Reconciler "https://github.com/dopplerhq/kubernetes-operator/blob/main/controllers/dopplersecret_controller.go"
    click APIClient "https://github.com/dopplerhq/kubernetes-operator/blob/main/pkg/api/api.go"
    click SecretProcessors "https://github.com/dopplerhq/kubernetes-operator/blob/main/pkg/processors/processors.go"
    click DataModels "https://github.com/dopplerhq/kubernetes-operator/blob/main/pkg/models/secrets.go"
    click VersionInfo "https://github.com/dopplerhq/kubernetes-operator/blob/main/pkg/version/version.go"
    click OperatorPod "https://github.com/dopplerhq/kubernetes-operator/blob/main/main.go"
    click OperatorPod "https://github.com/dopplerhq/kubernetes-operator/blob/main/config/manager/manager.yaml"
    click CRDManifest "https://github.com/dopplerhq/kubernetes-operator/blob/main/api/v1alpha1/dopplersecret_types.go"
    click GitHub "https://github.com/dopplerhq/kubernetes-operator/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef control fill:#ddd,stroke:#333,color:#000
    classDef operator fill:#add8e6,stroke:#333,color:#000
    classDef k8s fill:#bfb,stroke:#333,color:#000
    classDef external fill:#fbb,stroke:#333,color:#000
    classDef ci fill:#ffc,stroke:#333,color:#000
```
