KubeBlocks
BlogsEnterprise
⌘K
​
Blogs
Open Source · OLAP · CNCF Landscape

KubeBlocks ClickHouse Operator for Kubernetes

Deploy production-grade ClickHouse clusters in minutes. Manage sharding, replication, ClickHouse Keeper HA, and full backup/restore via a single open-source operator.

Try Playground Free →Read the Docs

128

Max Shards

2

Deployment Topologies

100%

Open Source

Deploy ClickHouse in 4 steps

1

Install KubeBlocks

# Add Helm repo
helm repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update

# Install KubeBlocks
helm install kubeblocks kubeblocks/kubeblocks \
  --namespace kb-system --create-namespace
2

Install ClickHouse Addon

helm upgrade -i kb-addon-clickhouse kubeblocks/clickhouse \
  -n kb-system
3

Create a ClickHouse Cluster

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: ch-cluster
  namespace: demo
spec:
  clusterDef: clickhouse
  terminationPolicy: Delete
  topology: standalone  # or cluster
  shardings:
    - name: clickhouse
      shards: 1
      template:
        replicas: 1
4

Cluster is Ready

$ kubectl get cluster ch-cluster -n demo
NAME         CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS    AGE
ch-cluster   clickhouse          Delete               Running   3m

Trusted by Engineering Teams at Scale

BONC CloudBONC Cloud
China Mobile CloudChina Mobile Cloud
China Telecom CloudChina Telecom Cloud
TencentTencent
XiaomiXiaomi
Ping AnPing An
VIP.comVIP.com
KwaiKwai
Tiger BrokersTiger Brokers
CITIC SecuritiesCITIC Securities
SealOSSealOS
FastGPTFastGPT
KubeSphereKubeSphere
MomentaMomenta
360360
TilaaTilaa
OlaresOlares
Changan AutomobileChangan Automobile
State GridState Grid
BONC CloudBONC Cloud
China Mobile CloudChina Mobile Cloud
China Telecom CloudChina Telecom Cloud
TencentTencent
XiaomiXiaomi
Ping AnPing An
VIP.comVIP.com
KwaiKwai
Tiger BrokersTiger Brokers
CITIC SecuritiesCITIC Securities
SealOSSealOS
FastGPTFastGPT
KubeSphereKubeSphere
MomentaMomenta
360360
TilaaTilaa
OlaresOlares
Changan AutomobileChangan Automobile
State GridState Grid
Topologies

Choose the Right ClickHouse Architecture

From lightweight standalone analytics to production-grade replicated clusters with built-in Keeper coordination.

Standalone

No Coordinator
Simple Analytics
Dev / Test

One or more independent ClickHouse shards without a coordinator. MergeTree tables are fully supported; ReplicatedMergeTree is not available in standalone topology — use the cluster topology with built-in ClickHouse Keeper.

✓

Single or multi-shard deployment (up to 128 shards)

✓

MergeTree, SummingMergeTree, AggregatingMergeTree engines

✓

HTTP (8123) and native TCP (9000) client access

✓

MySQL and PostgreSQL wire protocol compatibility

✓

Prometheus metrics on port 8001

✓

Full and incremental backup via clickhouse-backup

Application / Client
HTTP  {cluster}-{shardComponentName}:8123
Native  {cluster}-{shardComponentName}:9000
HTTP / native TCP
Kubernetes Services (one per shard)
{cluster}-clickhouse-XXX
ClusterIP · :8123 HTTP · :9000 native TCP · :8001 metrics
Selects all replicas within the shard (no roleSelector)
All Replicas
→ all replicas (load balanced)
Independent Shards (standalone topology)
Shard 0
clickhouse-abc-0POD
🖱️
clickhouse
:8123 · :9000 · :9004 MySQL · :9005 PG · :8001
💾 PVC data · 10Gi
Shard 1 (optional)
clickhouse-xyz-0POD
🖱️
clickhouse
:8123 · :9000 · :9004 MySQL · :9005 PG · :8001
💾 PVC data · 10Gi
ℹEach shard is independent — no replication between shards. Use MergeTree (not ReplicatedMergeTree).
🔗Headless service per shard — stable pod DNS for operator probes; not a client endpoint
Client Traffic
Independent Shard Pod
Persistent Storage
Optional / additional shard
Comparison

How KubeBlocks Compares to Other ClickHouse Operators

FeatureKubeBlocksAltinity OperatorBitnami Helm
Kubernetes-native CRD API✓✓✗
Standalone topology✓✓~
Cluster + ClickHouse Keeper HA✓✓✓
Multi-shard deployment (1–128)✓✓✓
Horizontal shard scaling✓✓~
Replica scaling within shard✓✓~
Vertical scaling (CPU/memory)✓✓✓
PVC volume expansion✓~✗
Full backup & restore✓~✗
Incremental backup✓~✗
Dynamic parameter reconfiguration✓~✗
Rolling version upgrade✓✓✓
TLS encryption✓✓✓
Prometheus metrics✓✓✓
Stop / start cluster✓✓~
Open Source✓✓✓
Cluster management web UIEnterprise✗✗

✓ = Supported · ~ = Partial / Limited · ✗ = Not supported

Enterprise= Available in KubeBlocks Enterprise edition. Based on documentation and GitHub issues; features may vary by version.

How It Works

Day-2 Operations, Visualized

Full Backup

ClickHouse Pod
clickhouse-backup create
S3-Compatible Object Storage
Snapshot Consistent

Incremental Backup

Previous Full Backup
clickhouse-backup create --diff-from=<full-backup>
S3 (incremental parts only)
Storage Efficient

Restore

S3 Backup
New Cluster (kubectl apply)
clickhouse-backup restore
Consistent Snapshot
Day-2 Operations

Every Operation Declared as a Kubernetes Resource

No SSH into pods, no shell scripts. Submit an OpsRequest and KubeBlocks handles the rest.

Sharding & Availability

✓

Shard Scale-out

Add new shards to an existing ClickHouse cluster. After provisioning, run a post-scale-out OpsRequest to register the new shards in the cluster configuration.

✓

Replica Scaling

Add or remove replicas within a shard for read throughput or storage redundancy.

✓

Vertical Scaling

Resize CPU and memory for ClickHouse shards or Keeper nodes via rolling OpsRequest.

✓

Volume Expansion

Expand PVC storage on any shard without pod restarts on supported storage classes.

✓

Stop / Start

Suspend the entire cluster (shards + Keeper) to eliminate compute cost; resume with full state.

✓

Rolling Restart

Restart pods shard by shard with configurable batch size and health-check gates.

Configuration, Data & Observability

✓

Full Backup & Restore

Consistent full snapshots via clickhouse-backup, uploaded to S3-compatible object storage.

✓

Incremental Backup

Capture only changed parts since the last backup to minimize storage cost and backup duration.

✓

Parameter Reconfiguration

Update server and user XML configuration via ConfigMap; mutable parameters apply at runtime without restart.

✓

Version Upgrade

Rolling upgrade across supported ClickHouse versions (22.x → 25.x) with health checks.

✓

TLS Encryption

Enable mutual TLS for client-server and inter-shard communication on any running cluster.

✓

Prometheus Metrics

Built-in metrics endpoint on port 8001 for ClickHouse shards and Keeper nodes; works with Grafana.

From the Blog

Go Deeper on ClickHouse on Kubernetes

KubeBlocks × ClickHouse: Production-Ready Operator on Kubernetes

KubeBlocks × ClickHouse: Production-Ready Operator on Kubernetes

How to operatorize ClickHouse with KubeBlocks: cluster management, sharding, Keeper integration, HA, parameter control, and backup/recovery.

We Let an AI Agent Manage Our Databases. Here's Why Most Operators Failed It.

We Let an AI Agent Manage Our Databases. Here's Why Most Operators Failed It.

We tested AI agents against traditional Kubernetes database operators — and why a unified API like KubeBlocks changes everything.

Running Databases on Kubernetes — Insights from Leading Chinese Internet Companies

Running Databases on Kubernetes — Insights from Leading Chinese Internet Companies

Why leading internet companies are increasingly adopting the practice of running stateful databases on Kubernetes.

Get Started

Get Started with KubeBlocks ClickHouse Operator, Risk-Free.

Open source and production-ready. Enterprise customers get dedicated onboarding, migration support, and SLA guarantees.

Try Playground Free →Talk to the Team
✓Open Source
✓ClickHouse & 35+ other engines
✓Production-grade HA
✓No vendor lock-in

© 2026 KUBEBLOCKS INC