# altinity/clickhouse-operator architecture

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

- Interactive diagram: https://gitdiagram.com/altinity/clickhouse-operator
- Repository: https://github.com/altinity/clickhouse-operator

## Overview

##### Main components
- Kubernetes API Server – external component with which the operator interacts.
- ClickHouse Operator – the core application that contains:
○ Controllers/Reconciliation loops (visible in pkg/controller/chi for ClickHouse installations and pkg/controller/chk for ClickHouse Keeper).
○ Custom Resource Definitions (in pkg/apis/...) implementing resources like ClickHouseInstallation, ClickHouseOperatorConfiguration, etc.
○ Client libraries, informers, and listers (located in pkg/client) that monitor Kubernetes events and facilitate reconciliation.
○ Sub-components for configuration, templating, and resource management defined in pkg/model, pkg/chop, pkg/util.
- Metrics Exporter – a secondary component (see cmd/metrics_exporter) that likely gathers and exposes metrics, integrating with external monitoring tools.
- User-managed ClickHouse Clusters – the clusters created, configured, and upgraded by the operator.
- External Tools and Integrations:
○ Prometheus – for gathering metrics (exported via the metrics exporter).
○ Grafana – dashboards and visualization as provided by deployment configurations.
○ External storages and services (persistent volumes, OpenEBS, Minio, etc.) as configured via custom templates and installation manifests.

##### Relationships and interactions
- Operator issuing commands that result in changes to fundamental Kubernetes objects (Pods, Services, Deployments, ConfigMaps, Secrets, StatefulSets, etc.) that run one or more ClickHouse clusters.
- How the Metrics Exporter gathers metrics from these managed clusters and then exports them (using REST endpoints or Prometheus exporters) to Prometheus.

##### Architectural patterns and design principles
- Operator Pattern with a controller-based design where custom controllers (in separate packages for “chi” and “chk”) reconcile the desired state defined in custom resources.
- Modular structure, with clear separations between API definitions, business/application logic, and client library implementations.
- CI/CD pipelines (visible in/.github/workflows) and deployment procedures (Helm charts in deploy/helm, and scripts under deploy/) as remembered external support elements.
- Mention key design principles such as extensibility (with templating and configurations in the “config” and “deploy/builder” folders) and observability (enabled by metrics exporting and integrated monitoring).

##### Relevant technologies, frameworks, or libraries
- Go language (with modules listed in go.mod and go.sum).
- Kubernetes client-go libraries (used in pkg/client/*).
- CRD, Informer, and Lister patterns.
- Helm and YAML deployment manifests.
- CI/CD workflows defined in the GitHub actions directory.
- Monitoring integrations with Prometheus and Grafana.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    A["Kubernetes API Server"]:::external

    %% ClickHouse Operator Subgraph
    subgraph "ClickHouse Operator"
        B["Operator Core"]:::operator
        C["Custom Controller: CHI"]:::operator
        D["Custom Controller: CHK"]:::operator
        E["Custom Resource Definitions (CRDs)"]:::operator
        F["Client Libraries & Informers"]:::operator
        G["Configuration & Templating Engine"]:::operator
    end

    %% Managed Cluster and Metrics
    H["Managed ClickHouse Clusters"]:::operator
    I["Metrics Exporter"]:::metrics
    J["Prometheus"]:::metrics
    K["Grafana"]:::metrics

    %% Deployment & CI/CD Subgraph
    subgraph "Deployment & CI/CD"
        L["CI/CD Pipelines"]:::deployment
        M["Helm Chart Deployment"]:::deployment
    end

    %% Connections between core components
    A -->|"events"| B
    B -->|"triggers"| C
    B -->|"triggers"| D
    B -->|"utilizes"| E
    B -->|"utilizes"| F
    B -->|"reads/configures"| G
    B -->|"manages"| H

    %% Metrics flow
    H -->|"collected_metrics"| I
    I -->|"exported_to"| J
    J -->|"dashboards_for"| K

    %% Deployment and CI/CD flows
    L -->|"builds/deploys"| B
    M -->|"installs"| B

    %% Click Events for Component Mapping
    click B "https://github.com/altinity/clickhouse-operator/blob/master/cmd/operator/app/main.go"
    click B "https://github.com/altinity/clickhouse-operator/blob/master/cmd/operator/main.go"
    click C "https://github.com/altinity/clickhouse-operator/tree/master/pkg/controller/chi"
    click D "https://github.com/altinity/clickhouse-operator/tree/master/pkg/controller/chk"
    click E "https://github.com/altinity/clickhouse-operator/tree/master/pkg/apis/"
    click F "https://github.com/altinity/clickhouse-operator/tree/master/pkg/client"
    click G "https://github.com/altinity/clickhouse-operator/tree/master/pkg/model"
    click G "https://github.com/altinity/clickhouse-operator/tree/master/deploy/builder/templates-config"
    click I "https://github.com/altinity/clickhouse-operator/tree/master/cmd/metrics_exporter"
    click L "https://github.com/altinity/clickhouse-operator/tree/master/.github/workflows"
    click M "https://github.com/altinity/clickhouse-operator/tree/master/deploy/helm"

    %% Styles
    classDef external fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef operator fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef metrics fill:#FFE082,stroke:#F57F17,stroke-width:2px;
    classDef deployment fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
```
