# etcd-io/etcd-operator architecture

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

- Interactive diagram: https://gitdiagram.com/etcd-io/etcd-operator
- Repository: https://github.com/etcd-io/etcd-operator

## Overview

##### Project Type & Purpose
- The project is a Kubernetes operator that handles the lifecycle and management of etcd clusters through CRDs.
- It is implemented in Go and uses Kubernetes operator patterns (specifically via Kubebuilder) to observe CR changes, reconcile state, and control etcd cluster deployments.
- The README and file structure reveal key aspects like CRDs (in the “config/crd” directory), controllers (in “internal/controller”), supporting utilities (in “internal/etcdutils”), and certificate management (in “pkg/certificate”).

##### Key Components
a. Kubernetes Cluster Environment:
- Cluster with its internal components such as the Kubernetes API Server and etcd (the backing store for Kubernetes, although separate from managed etcd clusters).
b. Custom Resource Definitions (CRDs):
- CRDs defined under “config/crd” (e.g., operator.etcd.io_etcdclusters.yaml). These define the custom resource “EtcdCluster” that the operator manages.
c. The Operator’s Controller:
- Reconciler logic housed in “internal/controller/etcdcluster_controller.go” which observes and reconciles the state of the etcd clusters.
- Components such as:
- Event Watcher & Reconciliation Loop – listening for changes to custom resources.
- Interaction with utilities from “internal/etcdutils” for etcd-specific operations.
d. API Schemas:
- API definitions and versioning found in the “api/v1alpha1” folder, which define the structures (CRDs) that the operator will handle.
e. Certificate Management:
- Model the certificate handling components within “pkg/certificate” (including the directory for auto and cert-manager integrations) as supporting secure communications.
f. Configuration & Deployment Manifests:
- Configuration folders (e.g., “config/manager”, “config/samples”) showing how Kustomize is used to deploy the manager and CRDs.
g. Build & Testing Tools:

##### Relationships and Data Flows
- From the Kubernetes API Server to the CRDs: New/updated EtcdCluster custom resources trigger events.
- From the API server to the operator’s controller: The controller (running as a manager in the cluster) receives events.
- From the controller to supporting utilities: The reconciler uses functions in “internal/etcdutils” and “pkg/certificate” to manage etcd clusters.
- Outbound interactions (if any) to external services, such as pulling container images via Docker.
- Reconciliation loop where the operator continuously ensures that the actual state matches the desired state as defined by the CR’s spec.

##### Architectural Patterns & Technologies
- Operator Pattern / Reconciliation Loop: This is central to Kubernetes operators.
- Use of Kubebuilder: Indicate that the project follows Kubebuilder’s conventions for project layout and controller scaffolding.
- Kustomize for Deployment: The config directories show use of Kustomize to manage deployment manifests for CRDs, RBAC, and the operator manager.
- Automated Testing: e2e tests (under “test/e2e”) and unit tests are incorporated to validate behavior.
- Containerization: Dockerfile (and accompanying scripts) are used for building container images for the operator.

##### Detailed Step-by-Step for the Principal Software Engineer
- “Kubernetes API Server” which also holds the CRD definitions (from config/crd).
- “Operator Manager” running the reconciliation loop (internal/controller).
- Outside or alongside, represent external systems:
- Additionally, denote the “Configuration & Deployment Layer” (using Kustomize manifests in config/manager and config/samples) linking these components.
- Optionally, include a section that shows the build/deployment pipeline (Makefile, Dockerfile, GitHub workflows) to illustrate how development integrates with deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        %% API Server Subgraph
        subgraph "Kubernetes API Server"
            A["Kubernetes API Server"]:::clusterInside
            CRD["Custom Resource Definitions (EtcdCluster)"]:::crd
        end

        %% Operator Manager Subgraph
        subgraph "Operator Manager"
            R["Reconciler (Controller)"]:::controller
            E["Etcd Utilities Module"]:::utils
            C["Certificate Manager"]:::certificate
            API["API Schemas (EtcdCluster Types)"]:::api
        end
    end

    %% External Systems Subgraph
    subgraph "External Systems"
        CRG["Container Registry"]:::external
        subgraph "Configuration & Deployment"
            KM["Kustomize Manager Manifests"]:::external
            KS["Kustomize Samples"]:::external
        end
        subgraph "Build & Deployment Pipeline"
            MF["Makefile"]:::pipeline
            DF["Dockerfile"]:::pipeline
            GH["GitHub Workflows"]:::pipeline
        end
    end

    %% Relationships
    A -->|"CREvent"| R
    API -->|"APIDefinitions"| R
    R -->|"ReconcileCall"| E
    R -->|"CertValidation"| C
    KM -->|"DeployManifests"| A
    KS -->|"DeployManifests"| A
    MF -->|"BuildPush"| CRG
    DF -->|"BuildPush"| CRG
    GH -->|"BuildPush"| CRG
    CRG -->|"PullImage"| R

    %% Styles
    classDef clusterInside fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef controller fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef crd fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef utils fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef certificate fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef api fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#D1F2EB,stroke:#117864,stroke-width:2px;
    classDef pipeline fill:#FDEBD0,stroke:#B9770E,stroke-width:2px;

    %% Click Events
    click CRD "https://github.com/etcd-io/etcd-operator/blob/main/config/crd/bases/operator.etcd.io_etcdclusters.yaml"
    click R "https://github.com/etcd-io/etcd-operator/blob/main/internal/controller/etcdcluster_controller.go"
    click E "https://github.com/etcd-io/etcd-operator/tree/main/internal/etcdutils/"
    click API "https://github.com/etcd-io/etcd-operator/tree/main/api/v1alpha1/"
    click C "https://github.com/etcd-io/etcd-operator/tree/main/pkg/certificate/"
    click KM "https://github.com/etcd-io/etcd-operator/tree/main/config/manager/"
    click KS "https://github.com/etcd-io/etcd-operator/tree/main/config/samples/"
    click MF "https://github.com/etcd-io/etcd-operator/tree/main/Makefile"
    click DF "https://github.com/etcd-io/etcd-operator/tree/main/Dockerfile"
    click GH "https://github.com/etcd-io/etcd-operator/tree/main/.github/workflows/"
```
