apecloud/kubeblocks-addon-qdrant

Deploy Qdrant on KubeBlocks

Overview

Deploy Qdrant vector database clusters on Kubernetes using KubeBlocks. Qdrant is a high-performance vector similarity search engine optimized for AI-driven applications such as semantic search, RAG, and recommendation systems. Multiple replicas form a distributed cluster with data sharding.

Official docs: https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/01-overview Quickstart: https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/02-quickstart

Prerequisites

• A running Kubernetes cluster with KubeBlocks installed (see install-kubeblocks)
• The Qdrant addon must be enabled:

# Check if qdrant addon is installed
helm list -n kb-system | grep qdrant

# Install if missing
helm install kb-addon-qdrant kubeblocks/qdrant --namespace kb-system --version 1.0.0

Topology

| Topology | Value | Component | Use Case | |---|---|---|---| | Cluster | cluster | qdrant | Single topology, distributed with data sharding |

Supported Versions

| Version | serviceVersion | |---|---| | 1.5 | 1.5.0 | | 1.7 | 1.7.3 | | 1.8 | 1.8.1, 1.8.4 | | 1.10 | 1.10.0 | | 1.13 | 1.13.4 | | 1.15 | 1.15.4 |

List available versions: kubectl get cmpv qdrant

Workflow

- [ ] Step 1: Ensure addon is installed
- [ ] Step 2: Create namespace
- [ ] Step 3: Create cluster (dry-run then apply)
- [ ] Step 4: Wait for cluster to be ready
- [ ] Step 5: Connect via REST API

Step 1: Ensure Addon Is Installed

helm list -n kb-system | grep qdrant

If not found:

helm install kb-addon-qdrant kubeblocks/qdrant --namespace kb-system --version 1.0.0

Step 2: Create Namespace

kubectl create namespace demo --dry-run=client -o yaml | kubectl apply -f -

Step 3: Create Cluster

Default ports: 6333 (HTTP REST API), 6334 (gRPC). Recommended replicas: 3, 5, or 7.

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: qdrant-cluster
  namespace: demo
spec:
  clusterDef: qdrant
  topology: cluster
  terminationPolicy: Delete
  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:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}

Dry-run before apply:

kubectl apply -f cluster.yaml --dry-run=server

If dry-run succeeds:

kubectl apply -f cluster.yaml

Step 4: Wait for Cluster Ready

kubectl -n demo get cluster qdrant-cluster -w

Success condition: STATUS shows Running. Typical duration: 1–2 minutes. Investigate after 10 min if still Creating.

Check pods:

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

Step 5: Connect via REST API

Port 6333 exposes the HTTP REST API. Use port-forward or the headless service:

# Port-forward to a pod
kubectl -n demo port-forward qdrant-cluster-qdrant-0 6333:6333

# Health check
curl http://localhost:6333/health

# List collections
curl http://localhost:6333/collections

Internal service: qdrant-cluster-qdrant-qdrant.demo.svc.cluster.local:6333 (REST), :6334 (gRPC).

Backup

KubeBlocks supports full backup via HTTP API snapshot for all collections. See: https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/05-backup-restore/02-create-full-backup

Troubleshooting

Cluster stuck in Creating:

kubectl -n demo describe cluster qdrant-cluster
kubectl -n demo get events --sort-by='.lastTimestamp'

Pod not starting:

kubectl -n demo logs qdrant-cluster-qdrant-0
kubectl -n demo describe pod qdrant-cluster-qdrant-0

Connection refused: Ensure port-forward is running or use the internal service from within the cluster.

Day-2 Operations

| Operation | Skill | External Docs | |---|---|---| | Stop / Start / Restart | cluster-lifecycle | Docs | | Scale CPU / Memory | vertical-scaling | Docs | | Add / Remove replicas | horizontal-scaling | Docs | | Expand storage | volume-expansion | Docs | | Upgrade engine version | minor-version-upgrade | Docs | | Expose externally | expose-service | Docs | | Backup | backup | Docs | | Restore | restore | Docs |

Safety Patterns

Follow safety-patterns: dry-run before apply, confirm success condition after watch, pre-deletion checklist before delete.