This page describes how KubeBlocks deploys a ClickHouse cluster on Kubernetes — covering the resource hierarchy, pod internals, distributed coordination via ClickHouse Keeper, and traffic routing.
{cluster}-{shardComponentName}:8123{cluster}-{shardComponentName}:9000{cluster}-clickhouse-x7k-headless — stable pod DNS for inter-server replication (:9009) and operator probes; not a client endpointKubeBlocks models a ClickHouse cluster using two topologies defined in the ClusterDefinition:
Topology standalone — data shards only, no Keeper:
Cluster → Sharding (clickhouse) → Component (clickhouse-XXX) → InstanceSet → Pod × N
Topology cluster — data shards + ClickHouse Keeper:
Cluster → Component (ch-keeper) → InstanceSet → Pod × 3
→ Sharding (clickhouse) → Component (clickhouse-XXX) → InstanceSet → Pod × N
| Resource | Role |
|---|---|
| Cluster | User-facing declaration — specifies topology, shard count, replicas, storage, and resources |
| Sharding (clickhouse) | KubeBlocks Sharding resource; manages N shard Components in parallel; each shard becomes an independent Component |
| Component (clickhouse-XXX) | One Component per shard; the shard component name is {shardingName}-{3-char random ID} (e.g., clickhouse-x7k) assigned by KubeBlocks at creation time — not deterministic ordinals |
| Component (ch-keeper) | ClickHouse Keeper ensemble (topology: cluster only); ZooKeeper-compatible coordination for replica synchronization and DDL replication |
| InstanceSet | KubeBlocks custom workload (replaces StatefulSet); manages pods with stable identities |
| Pod | Actual running instance; each pod gets a unique ordinal and its own PVC |
Every ClickHouse data pod runs one main application container (plus a copy-tools init container that copies curl into a shared volume at startup):
| Container | Port | Purpose |
|---|---|---|
clickhouse | 8123 (HTTP), 8443 (HTTPS), 9000 (TCP native), 9004 (MySQL wire protocol), 9005 (PostgreSQL wire protocol), 9009 (inter-server HTTP), 9010 (inter-server HTTPS), 9440 (TCP secure), 8001 (metrics) | ClickHouse database engine handling queries and replication; exposes Prometheus metrics natively on port 8001 (http-metrics) |
Each pod mounts its own PVC for the ClickHouse data directory (/bitnami/clickhouse), providing independent persistent storage per replica.
topology: cluster only)Each Keeper pod runs one container (plus a copy-tools init container that copies nc — netcat — into a shared volume for health-check scripts):
| Container | Port | Purpose |
|---|---|---|
clickhouse | 9181 (ZooKeeper-compatible client), 9234 (Raft internal), 8123 (HTTP), 9000 (TCP), 8001 (metrics) | ClickHouse Keeper process — provides ZooKeeper-compatible coordination for replica sync and DDL replication; port 9181 is the client endpoint for data pods |
ClickHouse uses ClickHouse Keeper (ch-keeper) for distributed coordination across replicas and shards. ClickHouse Keeper is a built-in, ZooKeeper-compatible coordination service deployed as a separate KubeBlocks Component (ch-keeper) within the same Cluster:
| ClickHouse Keeper Role | Purpose |
|---|---|
| Replica synchronization | Coordinates data part replication between replicas of the same shard |
| DDL replication | Distributes schema changes (CREATE, DROP, ALTER) across the cluster |
| Distributed query coordination | Tracks which parts exist on which replicas for query planning |
| Leader state | Maintains metadata for ReplicatedMergeTree and other replicated table engines |
ClickHouse data pods connect to ClickHouse Keeper using the {cluster}-ch-keeper service. The Keeper ensemble follows a Raft-based majority-quorum protocol (typically 3 nodes) to remain available during single-node failures. This component is only present in topology: cluster; in topology: standalone, no Keeper is deployed within the cluster. Without configuring an external ZooKeeper or ClickHouse Keeper, it is not advisable to use ReplicatedMergeTree or other table engines that depend on ZooKeeper/Keeper coordination.
ClickHouse achieves horizontal scale-out through sharding and within-shard replication:
| Concept | Description |
|---|---|
| Shard | A subset of data; different shards hold different rows of the same table |
| Replica | A full copy of a shard's data stored on a separate pod; provides redundancy |
| Distributed table | A virtual table that fans queries out to all shards and aggregates results |
| ReplicatedMergeTree | Table engine used on each shard replica; ClickHouse Keeper tracks parts across replicas |
When a replica fails, ClickHouse Keeper (in topology: cluster) detects the absence of its heartbeat. When the replica recovers, it fetches missing parts from other replicas automatically — no manual intervention required.
KubeBlocks creates two services for each ClickHouse shard component. Because cmpd-ch defines no roles: block, the ClusterIP service has no roleSelector and forwards to all pods in the shard:
| Service | Type | Ports | Notes |
|---|---|---|---|
{cluster}-{shardComponentName} | ClusterIP | 8123 (HTTP), 9000 (TCP), 8001 (metrics) | All pods in the shard; no roleSelector — any replica can serve queries |
{cluster}-{shardComponentName}-headless | Headless | — | All pods; always created by the workload controller |
Each shard's component name is {shardingName}-{3-char random ID} (e.g., clickhouse-x7k, clickhouse-m2p), assigned by KubeBlocks at cluster creation time. The resulting service names follow the same pattern: {cluster}-clickhouse-x7k, {cluster}-clickhouse-x7k-headless. These names are stable after creation but are not predictable before creation unless the cluster CR uses explicit shard IDs via shardTemplates[].shardIDs.
For direct pod addressing (replication traffic, ClickHouse Keeper communication), pods use the headless service DNS:
{pod-name}.{cluster}-{shardComponentName}-headless.{namespace}.svc.cluster.local
ClickHouse does not use a primary/replica role distinction at the application level — all replicas within a shard are equivalent and can serve queries. Recovery after a pod failure does not involve a role switch:
topology: cluster only) — remaining replicas continue serving if at least one replica is healthy; Keeper tracks which data parts each replica holdsSteps 2 and 4 require topology: cluster (CH Keeper deployed). In topology: standalone, no Keeper is present — inter-replica part synchronization is not available unless an external ZooKeeper or Keeper is configured.
KubeBlocks automatically manages the following ClickHouse system account. Passwords are auto-generated and stored in a Secret named {cluster}-{component}-account-{name}.
| Account | Role | Purpose |
|---|---|---|
admin | Admin (superuser) | ClickHouse administrative account used for cluster setup, DDL operations, and inter-replica communication |