ClickHouse

Columnar OLAP database managed by the Altinity ClickHouse Operator, deployed as a sharded and replicated cluster via ClickHouseInstallation CR.

Architecture

                Altinity Operator - Manages ClickHouseInstallation CR lifecycle

                ClickHouse Server - Columnar OLAP database (:8123 HTTP, :9000 native)

                Shards - Horizontal data partitioning across nodes

                Replicas - Per-shard redundancy for high availability

                Metrics Exporter - Prometheus metrics on /metrics (:8123)

Attributes

Attribute	Example	Description
`namespace` REQ	`clickhouse`	Kubernetes namespace - used in all generated manifests and service DNS
`admin_password` REQ	`secretpass`	Admin user password - written to clickhouse-installation.yaml users section, sub_comp_database-job.yaml init commands, and secret/clickhouse.env
`image_version` REQ	`clickhouse/clickhouse-server:24.3`	Container image - used in clickhouse-installation.yaml pod template and sub_comp_database-job.yaml init container
`http_port`	`8123`	HTTP API port - clickhouse-installation.yaml container port, secret/clickhouse.env
`native_port`	`9000`	Native TCP protocol port - clickhouse-installation.yaml container port, secret/clickhouse.env
`shard`	`2`	Number of shards - clickhouse-installation.yaml cluster layout shardsCount
`replicas`	`2`	Replicas per shard - clickhouse-installation.yaml cluster layout replicasCount
`pvc_size`	`100Gi`	Data volume size per replica - clickhouse-installation.yaml volumeClaimTemplates
`storageclass`	`longhorn`	StorageClass name (optional) - clickhouse-installation.yaml volumeClaimTemplates, omitted if empty
`mem_request`	`4Gi`	Memory request - clickhouse-installation.yaml pod template resources
`mem_limit`	`16Gi`	Memory limit - clickhouse-installation.yaml pod template resources
`cpu_request`	`1000m`	CPU request - clickhouse-installation.yaml pod template resources
`cpu_limit`	`4000m`	CPU limit - clickhouse-installation.yaml pod template resources
`env`	`production`	Environment label - clickhouse-installation.yaml metadata labels

Sub-Components

clickhouse_db - ClickHouse Database

Each clickhouse_db generates: user entry in clickhouse-installation.yaml (password, network ACL, database access), a per-database initialization Job in sub_comp_database-job.yaml (CREATE DATABASE, CREATE USER, GRANT), and credentials in secret/clickhouse.env.

Attribute	Example	Impact
`database` REQ	`otel`	Database name created by init Job, referenced in user ACL
`username` REQ	`otel_user`	User created with GRANT ALL on the database, written to clickhouse-installation.yaml and secret/clickhouse.env
`password` REQ	`secret123`	User password, written to clickhouse-installation.yaml and secret/clickhouse.env

Links

Link	Direction	Generated Output
Prometheus -> ClickHouse	Inbound	Generates `service-monitor.yaml` - ServiceMonitor CR scraping /metrics on HTTP port at 30s interval
Istio -> ClickHouse	Inbound	Adds `istio-injection: enabled` label on namespace.yaml
ClickHouse -> MinIO bucket	Outbound	Detects MinIO bucket sub-component for backup storage (variable only, no template file output)
OTEL -> ClickHouse DB	Inbound	Adds OpenTelemetry query examples (traces, logs, metrics, HTTP latency) to `doc/README.md`

Sub-component level:
OTEL -> clickhouse_db: ClickHouse becomes the OTEL Collector storage backend for traces, logs, and metrics

Generated Files

File	Condition	Content
k8s/deploy/base/namespace.yaml	Always	Namespace definition (with istio-injection label if Istio linked)
k8s/deploy/base/kustomization.yaml	Always	Kustomize resources, secretGenerator for registry credentials, stacktic labels
k8s/deploy/base/clickhouse-installation.yaml	Always	ClickHouseInstallation CR - cluster layout, users, profiles, quotas, pod template, volume claims
k8s/deploy/base/service-monitor.yaml	Prometheus linked	Prometheus ServiceMonitor CR - scrapes /metrics on HTTP port every 30s
k8s/deploy/base/sub_comp_database-job.yaml	clickhouse_db sub-components exist	Per-database K8s Job - CREATE DATABASE, CREATE USER, GRANT ALL
k8s/deploy/base/secret/clickhouse.env	Always	Admin password, host, ports, per-database user/password (SOPS encrypted)
k8s/deploy/base/secret/registry.json	Always	Docker registry credentials (SOPS encrypted)
doc/README.md	Always	Connection details, user list, cluster layout, CLI examples (OTEL queries added if OTEL linked)

Ports

Port	Service	Protocol
8123	HTTP API	HTTP
9000	Native protocol	TCP
9009	Inter-server communication (clustering)	TCP

Internal Endpoints

                HTTP: clickhouse-{name}.{namespace}.svc.cluster.local:8123

                Native: clickhouse-{name}.{namespace}.svc.cluster.local:9000