How altinity/clickhouse-operator works
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.