ClickHouse Keeper Switchover

ClickHouse Keeper uses a Raft-based consensus protocol with a leader/follower model. KubeBlocks supports triggering a leader switchover for planned maintenance.

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

Check Keeper Leader

Before switchover, identify the current leader:

kubectl get pods -n demo -l app.kubernetes.io/instance=clickhouse-cluster \
  -l apps.kubeblocks.io/component-name=ch-keeper \
  -L kubeblocks.io/role

NAME                               READY   STATUS    RESTARTS   AGE   ROLE
clickhouse-cluster-ch-keeper-0     2/2     Running   0          10m   leader
clickhouse-cluster-ch-keeper-1     2/2     Running   0          10m   follower
clickhouse-cluster-ch-keeper-2     2/2     Running   0          10m   follower

Trigger a Switchover

Transfer the leader role away from clickhouse-cluster-ch-keeper-0:

kubectl apply -f - <<EOF
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: keeper-switchover
  namespace: demo
spec:
  clusterName: clickhouse-cluster
  type: Switchover
  switchover:
    - componentName: ch-keeper
      instanceName: "clickhouse-cluster-ch-keeper-0"
EOF

Monitor progress:

kubectl get opsrequest keeper-switchover -n demo -w

NAME               TYPE         CLUSTER              STATUS    PROGRESS   AGE
keeper-switchover  Switchover   clickhouse-cluster   Succeed   1/1        15s

Verify the new leader:

kubectl get pods -n demo -l app.kubernetes.io/instance=clickhouse-cluster \
  -l apps.kubeblocks.io/component-name=ch-keeper \
  -L kubeblocks.io/role

Cleanup

kubectl delete opsrequest keeper-switchover -n demo --ignore-not-found