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. View Network Services
  5. Expose Qdrant Service
    1. Service Types Comparison
    2. Verify the Exposed Service
  6. Disable External Exposure
    1. Verify Service Removal
  7. Cleanup
  8. Summary

Manage Qdrant Services Using the Declarative Cluster API in KubeBlocks

This guide provides step-by-step instructions for exposing Qdrant services managed by KubeBlocks, both externally and internally. You'll learn to configure external access using cloud provider LoadBalancer services, manage internal services, and properly disable external exposure when no longer needed.

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.

        View Network Services

        List the Services created for the Qdrant cluster:

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

        Example Services:

        NAME                           TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)             AGE
qdrant-cluster-qdrant-qdrant   ClusterIP   10.96.111.81   <none>        6333/TCP,6334/TCP   28m

        Expose Qdrant Service

        External service addresses enable public internet access to Qdrant, while internal service addresses restrict access to the user's VPC.

        Service Types Comparison

        TypeUse CaseCloud CostSecurity
        ClusterIPInternal service communicationFreeHighest
        NodePortDevelopment/testingLowModerate
        LoadBalancerProduction external accessHighManaged via security groups

        Option 1: Using OpsRequest

        To expose the Qdrant service externally using a LoadBalancer, create an OpsRequest resource:

        apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: qdrant-cluster-expose-enable-ops
  namespace: demo
spec:
  type: Expose
  clusterName: qdrant-cluster
  expose:
  - componentName: qdrant
    services:
    - name: internet
      # Determines how the Service is exposed. Defaults to 'ClusterIP'.
      # Valid options are 'ClusterIP', 'NodePort', and 'LoadBalancer'.
      serviceType: LoadBalancer
      # Contains cloud provider related parameters if ServiceType is LoadBalancer.
      # Following is an example for AWS EKS
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-type: nlb
        service.beta.kubernetes.io/aws-load-balancer-internal: "false"  # or "true" for an internal VPC IP
    switch: Enable

        Wait for the OpsRequest to complete:

        kubectl get ops qdrant-cluster-expose-enable-ops -n demo

        Example Output:

        NAME                               TYPE     CLUSTER          STATUS    PROGRESS   AGE
qdrant-cluster-expose-enable-ops   Expose   qdrant-cluster   Succeed   1/1        31s

        Option 2: Using Cluster API

        Alternatively, update the spec.services section in the Cluster resource to include a LoadBalancer service:

        apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: qdrant-cluster
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: qdrant
  # expose a external service
  services:
    - annotations:
        service.beta.kubernetes.io/aws-load-balancer-type: nlb  # Use Network Load Balancer
        service.beta.kubernetes.io/aws-load-balancer-internal: "false"  # or "true" for an internal VPC IP
      componentSelector: qdrant
      name: qdrant-internet
      serviceName: qdrant-internet
      spec:
        ipFamilyPolicy: PreferDualStack
        ports:
          - name: tpc-qdrant
            port: 6333
            protocol: TCP
            targetPort: tcp-qdrant
        type: LoadBalancer
  componentSpecs:
  ...

        The YAML configuration above adds a new external service under the services section. This LoadBalancer service includes annotations for AWS Network Load Balancer (NLB).

        NOTE

        Cloud Provider Annotations

        When using a LoadBalancer service, you must include the appropriate annotations specific to your cloud provider. Below is a list of commonly used annotations for different cloud providers:

        • AWS
        service.beta.kubernetes.io/aws-load-balancer-type: nlb  # Use Network Load Balancer
service.beta.kubernetes.io/aws-load-balancer-internal: "true"  # Use "false" for internet-facing LoadBalancer
        • Azure
        service.beta.kubernetes.io/azure-load-balancer-internal: "true" # Use "false" for internet-facing LoadBalancer
        • GCP
        networking.gke.io/load-balancer-type: "Internal"  # Restricts the LoadBalancer to internal VPC access only. Defaults to internet-facing if not specified.
cloud.google.com/l4-rbs: "enabled" # Optimization for internet-facing LoadBalancer
        • Alibaba Cloud
        service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: "internet"  # Use "intranet" for internal-facing LoadBalancer
        NOTE

        The service.beta.kubernetes.io/aws-load-balancer-internal annotation controls whether the LoadBalancer is internal or internet-facing. Note that this annotation cannot be modified dynamically after service creation.

          service.beta.kubernetes.io/aws-load-balancer-internal: "false"  # Use "true" for internal VPC IPs

        If you change this annotation from "false" to "true" after the Service is created, the annotation may update in the Service object, but the LoadBalancer will still retain its public IP.

        To properly modify this behavior:

        • First, delete the existing LoadBalancer service.
        • Recreate the service with the updated annotation (service.beta.kubernetes.io/aws-load-balancer-internal: "true").
        • Wait for the new LoadBalancer to be provisioned with the correct internal or external IP.

        Wait for the Cluster status to transition to Running using the following command:

        kubectl get cluster qdrant-cluster -n demo -w

        NAME            CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS    AGE
qdrant-cluster   qdrant           Delete               Running   18m

        Verify the Exposed Service

        Check the service details to confirm the LoadBalancer service is created:

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

        Example Output:

        NAME                             TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)              AGE
qdrant-cluster-qdrant-internet   LoadBalancer   172.20.60.24   <EXTERNAL-IP> 6333:31243/TCP      1m

        Disable External Exposure

        Option 1: Using OpsRequest

        To disable external access, create an OpsRequest:

        apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: qdrant-cluster-expose-disable-ops
  namespace: demo
spec:
  clusterName: qdrant-cluster
  expose:
  - componentName: qdrant
    services:
    - name: internet
      serviceType: LoadBalancer
    switch: Disable
  preConditionDeadlineSeconds: 0
  type: Expose

        Wait for the OpsRequest to complete:

        kubectl get ops qdrant-cluster-expose-disable-ops -n demo

        Example Output:

        NAME                                TYPE     CLUSTER          STATUS    PROGRESS   AGE
qdrant-cluster-expose-disable-ops   Expose   qdrant-cluster   Succeed   1/1        24s

        Option 2: Using Cluster API

        Alternatively, remove the spec.services field from the Cluster resource:

        kubectl patch cluster qdrant-cluster -n demo --type=json -p='[
  {
    "op": "remove",
    "path": "/spec/services"
  }
]'

        Monitor the cluster status until it is Running:

        kubectl get cluster qdrant-cluster -n demo -w

        NAME             CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS    AGE
qdrant-cluster   qdrant              Delete               Running   24m

        Verify Service Removal

        Ensure that the 'qdrant-cluster-qdrant-internet' Service is removed:

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

        Expected Result: The 'qdrant-cluster-qdrant-internet' Service should be removed.

        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

        This guide demonstrated how to:

        • Expose a Qdrant service externally or internally using KubeBlocks.
        • Configure LoadBalancer services with cloud provider-specific annotations.
        • Manage external access by enabling or disabling services via OpsRequest or direct updates to the Cluster API.

        KubeBlocks provides flexibility and simplicity for managing MySQL services in Kubernetes environments. simplicity for managing Qdrant services in Kubernetes environments.

        © 2025 ApeCloud PTE. Ltd.