KubeBlocks
BlogsEnterprise
⌘K
​
Blogs

Overview
Quickstart
Architecture

Operations

Stop / Start / Restart
Vertical Scaling
Horizontal Scaling
Volume Expansion
Reconfigure
Switchover
Manage Services

Observability

Prometheus Integration
  1. Prerequisites
  2. Scale Out Replicas
  3. Scale In Replicas
  4. Scale Out Shards
  5. Scale In Shards
  6. Scale ClickHouse Keeper Replicas
  7. Cleanup

Horizontal Scaling for ClickHouse

KubeBlocks supports two dimensions of ClickHouse horizontal scaling:

  1. Replica scaling — add/remove replicas within existing shards
  2. Shard scaling — add/remove entire shards
NOTE

After adding new shards, you must run the post-scale-out-shard-for-clickhouse OpsRequest to register the new shards in the cluster configuration. See Scale Out Shards below.

Prerequisites

    • A functional Kubernetes cluster (v1.21+ recommended)
    • kubectl v1.21+ installed and configured with cluster access
    • KubeBlocks installed (installation guide)
    • ClickHouse Add-on enabled
    • A demo namespace: kubectl create ns demo

    Scale Out Replicas

    Add one replica to all existing shards:

    kubectl apply -f - <<EOF
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: ch-scale-out
  namespace: demo
spec:
  clusterName: clickhouse-cluster
  type: HorizontalScaling
  horizontalScaling:
    - componentName: clickhouse
      scaleOut:
        replicaChanges: 1
EOF

    Monitor progress:

    kubectl get opsrequest ch-scale-out -n demo -w
    Example Output
    NAME          TYPE                CLUSTER              STATUS    PROGRESS   AGE
ch-scale-out  HorizontalScaling   clickhouse-cluster   Succeed   1/1        60s

    Scale In Replicas

    Remove one replica from all existing shards:

    kubectl apply -f - <<EOF
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: ch-scale-in
  namespace: demo
spec:
  clusterName: clickhouse-cluster
  type: HorizontalScaling
  horizontalScaling:
    - componentName: clickhouse
      scaleIn:
        replicaChanges: 1
EOF

    Scale Out Shards

    Increase the number of shards (e.g., from 1 to 2):

    kubectl apply -f - <<EOF
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: ch-scale-out-sharding
  namespace: demo
spec:
  clusterName: clickhouse-cluster
  type: HorizontalScaling
  horizontalScaling:
    - componentName: clickhouse
      shards: 2
EOF

    After the scale-out completes, run the post-processing operation to register the new shard:

    kubectl apply -f - <<EOF
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: ch-post-scale-out-shard
  namespace: demo
spec:
  clusterName: clickhouse-cluster
  type: Custom
  custom:
    opsDefinitionName: post-scale-out-shard-for-clickhouse
    components:
      - componentName: clickhouse
EOF

    Scale In Shards

    Decrease the number of shards (e.g., from 2 to 1):

    kubectl apply -f - <<EOF
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: ch-scale-in-sharding
  namespace: demo
spec:
  clusterName: clickhouse-cluster
  type: HorizontalScaling
  horizontalScaling:
    - componentName: clickhouse
      shards: 1
EOF

    Scale ClickHouse Keeper Replicas

    For clusters using the cluster topology, scale Keeper replicas (add 2 for a 3-node quorum):

    kubectl apply -f - <<EOF
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: ch-keeper-scale-out
  namespace: demo
spec:
  clusterName: clickhouse-cluster
  type: HorizontalScaling
  horizontalScaling:
    - componentName: ch-keeper
      scaleOut:
        replicaChanges: 2
EOF
    NOTE

    Keeper requires an odd number of replicas for quorum (1, 3, 5...). Adding 2 replicas to a 1-replica Keeper gives a 3-node quorum.

    Cleanup

    kubectl delete opsrequest ch-scale-out ch-scale-in ch-scale-out-sharding ch-scale-in-sharding ch-post-scale-out-shard ch-keeper-scale-out -n demo --ignore-not-found

    © 2026 KUBEBLOCKS INC