kubeblocks-addon-qdrant

name	kubeblocks-addon-qdrant
metadata	{"version":"0.1.0"}
description	Legacy compatibility shim for Qdrant provisioning on KubeBlocks. The primary create-time entry is kubeblocks-engine-qdrant. Keep this skill callable for older references, but do not recommend it as the main path for cold-start agents.

Deploy Qdrant on KubeBlocks

Legacy compatibility shim. Primary entry: kubeblocks-engine-qdrant. Keep the preserved workflow below for detailed reference, but do not recommend this skill as the main path for cold-start agents.

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.