KubeBlocks
BlogsEnterprise
⌘K
​
Blogs

Overview
Quickstart
Architecture

Operations

Lifecycle Management
Vertical Scaling
Horizontal Scaling
Volume Expansion
Configuration
Minor Version Upgrade
Manage Services

Backup And Restore

Backup
Restore

Monitoring

Observability for ZooKeeper Clusters
FAQs
  1. Prerequisites
  2. Scale-out (Add Replicas)
    1. Verify Scale-Out
  3. Scale-in (Remove Replicas)
    1. Verify Scale-In
  4. Best Practices
  5. Cleanup

Horizontal Scaling for ZooKeeper Clusters with KubeBlocks

This guide explains how to perform horizontal scaling (scale-out and scale-in) on a ZooKeeper cluster managed by KubeBlocks.

NOTE

ZooKeeper Quorum Requirements

ZooKeeper uses a quorum-based consensus algorithm. For correct operation:

  • Always maintain an odd number of nodes (3, 5, 7, etc.)
  • A cluster of N nodes tolerates at most ⌊N/2⌋ failures
  • Minimum recommended ensemble size is 3 nodes

Prerequisites

    Before proceeding, verify your environment meets these requirements:

    • A functional Kubernetes cluster (v1.21+ recommended)
    • kubectl v1.21+ installed and configured with cluster access
    • Helm installed (installation guide)
    • KubeBlocks installed (installation guide)
    • ZooKeeper Add-on installed and a ZooKeeper cluster running (see Quickstart)

    Scale-out (Add Replicas)

    Expected Workflow:

    1. New pods are provisioned and join the ensemble
    2. Data is synchronized from existing members
    3. Cluster status changes from Updating to Running

    Scale out the ZooKeeper cluster by adding 2 replicas (from 3 to 5):

    apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: zk-scale-out
  namespace: demo
spec:
  clusterName: zookeeper-cluster
  type: HorizontalScaling
  horizontalScaling:
  - componentName: zookeeper
    scaleOut:
      replicaChanges: 2

    Apply it:

    kubectl apply -f https://raw.githubusercontent.com/apecloud/kubeblocks-addons/refs/heads/main/examples/zookeeper/scale-out.yaml

    Monitor the progress:

    kubectl get ops zk-scale-out -n demo -w
    Example Output
    NAME           TYPE                CLUSTER             STATUS    PROGRESS   AGE
zk-scale-out   HorizontalScaling   zookeeper-cluster   Running   0/2        8s
zk-scale-out   HorizontalScaling   zookeeper-cluster   Running   1/2        2m11s
zk-scale-out   HorizontalScaling   zookeeper-cluster   Running   2/2        4m9s
zk-scale-out   HorizontalScaling   zookeeper-cluster   Succeed   2/2        4m33s

    Update the replicas field in the Cluster resource:

    kubectl patch cluster zookeeper-cluster -n demo --type=json \
  -p='[{"op": "replace", "path": "/spec/componentSpecs/0/replicas", "value": 5}]'

    Verify Scale-Out

    kubectl get pods -n demo -l app.kubernetes.io/instance=zookeeper-cluster -L kubeblocks.io/role
    Example Output (5 Pods)
    NAME                            READY   STATUS    RESTARTS   AGE     ROLE
zookeeper-cluster-zookeeper-0   2/2     Running   0          6m12s   follower
zookeeper-cluster-zookeeper-1   2/2     Running   0          6m58s   follower
zookeeper-cluster-zookeeper-2   2/2     Running   0          7m41s   leader
zookeeper-cluster-zookeeper-3   2/2     Running   0          4m9s    follower
zookeeper-cluster-zookeeper-4   2/2     Running   0          4m33s   follower

    Scale-in (Remove Replicas)

    Expected Workflow:

    1. Pods with the largest ordinals are selected for removal
    2. Each pod is removed from the ensemble via the member_leave script
    3. Pods are terminated gracefully
    4. Cluster status changes from Updating to Running

    Scale in the ZooKeeper cluster by removing 2 replicas (from 5 to 3):

    apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: zk-scale-in
  namespace: demo
spec:
  clusterName: zookeeper-cluster
  type: HorizontalScaling
  horizontalScaling:
  - componentName: zookeeper
    scaleIn:
      replicaChanges: 2

    Apply it:

    kubectl apply -f https://raw.githubusercontent.com/apecloud/kubeblocks-addons/refs/heads/main/examples/zookeeper/scale-in.yaml

    Monitor progress:

    kubectl get ops zk-scale-in -n demo -w
    Example Output
    NAME          TYPE                CLUSTER             STATUS    PROGRESS   AGE
zk-scale-in   HorizontalScaling   zookeeper-cluster   Running   0/2        8s
zk-scale-in   HorizontalScaling   zookeeper-cluster   Running   1/2        47s
zk-scale-in   HorizontalScaling   zookeeper-cluster   Running   2/2        88s
zk-scale-in   HorizontalScaling   zookeeper-cluster   Succeed   2/2        2m4s

    kubectl patch cluster zookeeper-cluster -n demo --type=json \
  -p='[{"op": "replace", "path": "/spec/componentSpecs/0/replicas", "value": 3}]'

    Verify Scale-In

    kubectl get pods -n demo -l app.kubernetes.io/instance=zookeeper-cluster -L kubeblocks.io/role
    Example Output (3 Pods)
    NAME                            READY   STATUS    RESTARTS   AGE     ROLE
zookeeper-cluster-zookeeper-0   2/2     Running   0          8m21s   follower
zookeeper-cluster-zookeeper-1   2/2     Running   0          9m7s    follower
zookeeper-cluster-zookeeper-2   2/2     Running   0          9m50s   leader

    Best Practices

    • Always scale to an odd number of nodes to maintain quorum
    • Scale during low-traffic periods when possible
    • Monitor cluster health during scaling operations
    • Verify sufficient resources exist before scaling out

    Cleanup

    kubectl delete cluster zookeeper-cluster -n demo
kubectl delete ns demo

    © 2026 KUBEBLOCKS INC