KubeBlocks
BlogsKubeBlocks Cloud
⌘K
​
Overview
Quickstart

Operations

Lifecycle Management
Vertical Scaling
Horizontal Scaling
Volume Expansion
Manage Qdrant Services
Minor Version Upgrade
Decommission Qdrant Replica

Backup And Restores

Create BackupRepo
Create Full Backup
Scheduled Backups
Restore Qdrant Cluster

Monitoring

Observability for Qdrant Clusters

tpl

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

Horizontal Scaling for Qdrant Clusters with KubeBlocks

This guide explains how to perform horizontal scaling (scale-out and scale-in) on a Qdrant 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 Qdrant Cluster

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

      Apply the following YAML configuration to deploy the cluster:

      apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: qdrant-cluster
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: qdrant
  topology: cluster
  componentSpecs:
    - name: qdrant
      serviceVersion: 1.10.0
      replicas: 3
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            storageClassName: ""
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 20Gi

      Verifying the Deployment

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

        kubectl get cluster qdrant-cluster -n demo -w

        Expected Output:

        kubectl get cluster qdrant-cluster -n demo
NAME             CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS     AGE
qdrant-cluster   qdrant              Delete               Creating   49s
qdrant-cluster   qdrant              Delete               Running    62s

        Check the pod status and roles:

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

        Expected Output:

        NAME                      READY   STATUS    RESTARTS   AGE
qdrant-cluster-qdrant-0   2/2     Running   0          1m43s
qdrant-cluster-qdrant-1   2/2     Running   0          1m28s
qdrant-cluster-qdrant-2   2/2     Running   0          1m14s

        Once the cluster status becomes Running, your Qdrant 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
        NOTE

        Qdrant uses the Raft consensus protocol to maintain consistency regarding the cluster topology and the collections structure. Better to have an odd number of replicas, such as 3, 5, 7, to avoid split-brain scenarios, after scaling out/in the cluster.

        Option 1: Using Horizontal Scaling OpsRequest

        Scale out the Qdrant cluster by adding 1 replica to qdrant component:

        apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: qdrant-cluster-scale-out-ops
  namespace: demo
spec:
  clusterName: qdrant-cluster
  type: HorizontalScaling
  horizontalScaling:
  - componentName: qdrant
    # 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 qdrant-cluster-scale-out-ops -n demo -w

        Expected Result:

        NAME                           TYPE                CLUSTER          STATUS    PROGRESS   AGE
qdrant-cluster-scale-out-ops   HorizontalScaling   qdrant-cluster   Running   0/1        9s
qdrant-cluster-scale-out-ops   HorizontalScaling   qdrant-cluster   Running   1/1        16s
qdrant-cluster-scale-out-ops   HorizontalScaling   qdrant-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: qdrant
      replicas: 4 # increase replicas to scale-out
...

        Or you can patch the cluster CR with command:

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

        Verify Scale-Out

        After applying the operation, you will see a new pod created and the Qdrant 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=qdrant-cluster

        Example Output:

        NAME                      READY   STATUS    RESTARTS   AGE
qdrant-cluster-qdrant-0   2/2     Running   0          6m24s
qdrant-cluster-qdrant-1   2/2     Running   0          7m19s
qdrant-cluster-qdrant-2   2/2     Running   0          5m57s
qdrant-cluster-qdrant-3   2/2     Running   0          3m54s

        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
        NOTE

        On Qdrant scale-in, data will be redistributed among the remaining replicas. Make sure the cluster have enough capacity to accommodate the data. The data redistribution process may take some time depending on the amount of data. It is handled by Qdrant MemberLeave operation, and Pods won't be deleted until the data redistribution, i.e. the MemberLeave actions completed successfully.

        Option 1: Using Horizontal Scaling OpsRequest

        Scale in the Qdrant cluster by removing ONE replica:

        apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: qdrant-cluster-scale-in-ops
  namespace: demo
spec:
  clusterName: qdrant-cluster
  type: HorizontalScaling
  horizontalScaling:
  - componentName: qdrant
    # 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 qdrant-cluster-scale-in-ops -n demo -w

        Expected Result:

        NAME                         TYPE                 CLUSTER          STATUS    PROGRESS   AGE
qdrant-cluster-scale-in-ops   HorizontalScaling   qdrant-cluster   Running   0/1        8s
qdrant-cluster-scale-in-ops   HorizontalScaling   qdrant-cluster   Running   1/1        24s
qdrant-cluster-scale-in-ops   HorizontalScaling   qdrant-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: qdrant
      replicas: 1 # decrease replicas to scale-out

        Or you can patch the cluster CR with command:

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

        Verify Scale-In

        Example Output (ONE Pod):

        kubectl get pods -n demo -l app.kubernetes.io/instance=qdrant-cluster
NAME                        READY   STATUS   RESTARTS   AGE
qdrant-cluster-qdrant-0     2/2     Running  0          18m

        Troubleshooting

        On scale-in, KubeBlocks Qdrant will redistribute data in following steps:

        1. Cluster Information Gathering:
        • Identifies the leaving member
        • Retrieves cluster state including peer IDs and leader information
        1. Data Migration:
        • Discovers all collections on the leaving member
        • For each collection, finds all local shards
        • Moves each shard to the cluster leader
        • Verifies successful shard transfer before proceeding
        1. Cluster Membership Update:
        • Removes the leaving peer from the cluster membership
        • Uses file locking to prevent concurrent removal operations

        If the scale-in operation gets stuck for quite a long time, please check these resources:

        # Check agent logs
kubectl logs -n demo <pod-name> -c kbagent

# Check cluster events for errors
kubectl get events -n demo --field-selector involvedObject.name=pg-cluster

# Check kubeblocks logs
kubectl -n kb-system logs deploy/kubeblocks

        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 Qdrant cluster along with its namespace:

        kubectl delete cluster qdrant-cluster -n demo
kubectl delete ns demo

        Summary

        In this guide you learned how to:

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

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

        © 2025 ApeCloud PTE. Ltd.