KubeBlocks
BlogsKubeBlocks Cloud
⌘K
​
Overview
Quickstart

Operations

Lifecycle Management
Vertical Scaling
Horizontal Scaling
Volume Expansion
Manage Kafka Services
Decommission Kafka Replica

Monitoring

Observability for Kafka Clusters

tpl

  1. Prerequisites
  2. Deploy a Kafka Cluster
  3. Verifying the Deployment
  4. Scale-out (Add Replicas)
    1. Verify Scale-Out
  5. Scale-in (Remove Replicas)
    1. Verify Scale-In
  6. Best Practices
  7. Cleanup
  8. Summary

Horizontal Scaling for Kafka Clusters with KubeBlocks

This guide explains how to perform horizontal scaling (scale-out and scale-in) on a Kafka cluster managed by KubeBlocks. You'll learn how to use both OpsRequest and direct Cluster API updates to achieve this.

Prerequisites

    Before proceeding, ensure the following:

    • Environment Setup:
      • A Kubernetes cluster is up and running.
      • The kubectl CLI tool is configured to communicate with your cluster.
      • KubeBlocks CLI and KubeBlocks Operator are installed. Follow the installation instructions here.
    • Namespace Preparation: To keep resources isolated, create a dedicated namespace for this tutorial:
    kubectl create ns demo
namespace/demo created

    Deploy a Kafka Cluster

      KubeBlocks uses a declarative approach for managing Kafka Clusters. Below is an example configuration for deploying a Kafka Cluster with 3 components

      Apply the following YAML configuration to deploy the cluster:

      apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: kafka-separated-cluster
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: kafka
  topology: separated_monitor
  componentSpecs:
    - name: kafka-broker
      replicas: 1
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      env:
        - name: KB_KAFKA_BROKER_HEAP
          value: "-XshowSettings:vm -XX:MaxRAMPercentage=100 -Ddepth=64"
        - name: KB_KAFKA_CONTROLLER_HEAP
          value: "-XshowSettings:vm -XX:MaxRAMPercentage=100 -Ddepth=64"
        - name: KB_BROKER_DIRECT_POD_ACCESS
          value: "true"
      volumeClaimTemplates:
        - name: data
          spec:
            storageClassName: ""
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 20Gi
        - name: metadata
          spec:
            storageClassName: ""
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 1Gi
    - name: kafka-controller
      replicas: 1
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
        - name: metadata
          spec:
            storageClassName: ""
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 1Gi
    - name: kafka-exporter
      replicas: 1
      resources:
        limits:
          cpu: "0.5"
          memory: "1Gi"
        requests:
          cpu: "0.1"
          memory: "0.2Gi"
      NOTE

      These three components will be created strictly in controller->broker->exporter order as defined in ClusterDefinition.

      Verifying the Deployment

        Monitor the cluster status until it transitions to the Running state:

        kubectl get cluster kafka-separated-cluster -n demo -w

        Expected Output:

        kubectl get cluster kafka-separated-cluster -n demo
NAME                      CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS     AGE
kafka-separated-cluster   kafka                Delete               Creating   13s
kafka-separated-cluster   kafka                Delete               Running    63s

        Check the pod status and roles:

        kubectl get pods -l app.kubernetes.io/instance=kafka-separated-cluster -n demo

        Expected Output:

        NAME                                         READY   STATUS    RESTARTS   AGE
kafka-separated-cluster-kafka-broker-0       2/2     Running   0          13m
kafka-separated-cluster-kafka-controller-0   2/2     Running   0          13m
kafka-separated-cluster-kafka-exporter-0     1/1     Running   0          12m

        Once the cluster status becomes Running, your Kafka cluster is ready for use.

        TIP

        If you are creating the cluster for the very first time, it may take some time to pull images before running.

        Scale-out (Add Replicas)

        Expected Workflow:

        1. New pod is provisioned, and transitions from Pending to Running.
        2. Cluster status changes from Updating to Running

        Option 1: Using Horizontal Scaling OpsRequest

        Scale out the Kafka cluster by adding 1 replica to kafka component:

        apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: kafka-separated-cluster-scale-out-ops
  namespace: demo
spec:
  clusterName: kafka-separated-cluster
  type: HorizontalScaling
  horizontalScaling:
  - componentName: kafka-broker
    # Specifies the replica changes for scaling in components
    scaleOut:
      # Specifies the replica changes for the component.
      # add one more replica to current component
      replicaChanges: 1

        Monitor the progress of the scaling operation:

        kubectl get ops kafka-separated-cluster-scale-out-ops -n demo -w

        Expected Result:

        NAME                                    TYPE                CLUSTER                   STATUS    PROGRESS   AGE
kafka-separated-cluster-scale-out-ops   HorizontalScaling   kafka-separated-cluster   Running   0/1        9s
kafka-separated-cluster-scale-out-ops   HorizontalScaling   kafka-separated-cluster   Running   1/1        16s
kafka-separated-cluster-scale-out-ops   HorizontalScaling   kafka-separated-cluster   Succeed   1/1        16s

        Option 2: Direct Cluster API Update

        Alternatively, you can perform a direct update to the replicas field in the Cluster resource:

        apiVersion: apps.kubeblocks.io/v1
kind: Cluster
spec:
  componentSpecs:
    - name: kafka-broker
      replicas: 2 # increase replicas to scale-out
...

        Or you can patch the cluster CR with command:

        kubectl patch cluster kafka-separated-cluster -n demo --type=json -p='[{"op": "replace", "path": "/spec/componentSpecs/1/replicas", "value": 2}]'

        Verify Scale-Out

        After applying the operation, you will see a new pod created and the Kafka cluster status goes from Updating to Running, and the newly created pod has a new role secondary.

        kubectl get pods -n demo -l app.kubernetes.io/instance=kafka-separated-cluster,apps.kubeblocks.io/component-name=kafka-broker

        Example Output:

        NAME                                     READY   STATUS    RESTARTS   AGE
kafka-separated-cluster-kafka-broker-0   2/2     Running   0          3m7s
kafka-separated-cluster-kafka-broker-1   2/2     Running   0          28s

        Scale-in (Remove Replicas)

        Expected Workflow:

        1. Selected replica (the one with the largest ordinal) is removed
        2. Pod is terminated gracefully
        3. Cluster status changes from Updating to Running

        Option 1: Using Horizontal Scaling OpsRequest

        Scale in the Kafka cluster by removing ONE replica:

        apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: kafka-separated-cluster-scale-in-ops
  namespace: demo
spec:
  clusterName: kafka-separated-cluster
  type: HorizontalScaling
  horizontalScaling:
  - componentName: kafka-broker
    # Specifies the replica changes for scaling in components
    scaleIn:
      # Specifies the replica changes for the component.
      # remove one replica from current component
      replicaChanges: 1

        Monitor progress:

        kubectl get ops kafka-separated-cluster-scale-in-ops -n demo -w

        Expected Result:

        NAME                                   TYPE                 CLUSTER          STATUS    PROGRESS   AGE
kafka-separated-cluster-scale-in-ops   HorizontalScaling   kafka-separated-cluster   Running   0/1        8s
kafka-separated-cluster-scale-in-ops   HorizontalScaling   kafka-separated-cluster   Running   1/1        24s
kafka-separated-cluster-scale-in-ops   HorizontalScaling   kafka-separated-cluster   Succeed   1/1        24s

        Option 2: Direct Cluster API Update

        Alternatively, you can perform a direct update to the replicas field in the Cluster resource:

        apiVersion: apps.kubeblocks.io/v1
kind: Cluster
spec:
  componentSpecs:
    - name: kafka-broker
      replicas: 1 # decrease replicas to scale-in

        Or you can patch the cluster CR with command:

        kubectl patch cluster kafka-separated-cluster -n demo --type=json -p='[{"op": "replace", "path": "/spec/componentSpecs/1/replicas", "value": 1}]'

        Verify Scale-In

        Example Output (ONE Pod):

        kubectl get pods -n demo -l app.kubernetes.io/instance=kafka-separated-cluster,apps.kubeblocks.io/component-name=kafka-broker
NAME                                     READY   STATUS    RESTARTS   AGE
kafka-separated-cluster-kafka-broker-0   2/2     Running   0          5m7s

        Best Practices

        When performing horizontal scaling:

        • Scale during low-traffic periods when possible
        • Monitor cluster health during scaling operations
        • Verify sufficient resources exist before scaling out
        • Consider storage requirements for new replicas

        Cleanup

        To remove all created resources, delete the Kafka cluster along with its namespace:

        kubectl delete cluster kafka-separated-cluster -n demo
kubectl delete ns demo

        Summary

        In this guide you learned how to:

        • Perform scale-out operations to add replicas to a Kafka cluster.
        • Perform scale-in operations to remove replicas from a Kafka cluster.
        • Use both OpsRequest and direct Cluster API updates for horizontal scaling.

        KubeBlocks ensures seamless scaling with minimal disruption to your database operations.

        © 2025 ApeCloud PTE. Ltd.