# Kubeblocks Addon Qdrant

> 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.

- Skill: `apecloud/kubeblocks-addon-qdrant` (Agent Skill)
- Install (CLI): `npx skillmds@latest add apecloud/kubeblocks-addon-qdrant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/apecloud/kubeblocks-addon-qdrant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: apecloud (https://skillmd.com/u/apecloud)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/apecloud/kubeblocks-addon-qdrant

---


# Deploy Qdrant on KubeBlocks

> Legacy compatibility shim. Primary entry: [kubeblocks-engine-qdrant](../kubeblocks-engine-qdrant/SKILL.md). 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](../kubeblocks-install/SKILL.md))
- The Qdrant addon must be enabled:

```bash
# 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

```bash
helm list -n kb-system | grep qdrant
```

If not found:

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

## Step 2: Create Namespace

```bash
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.

```yaml
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:**

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

If dry-run succeeds:

```bash
kubectl apply -f cluster.yaml
```

## Step 4: Wait for Cluster Ready

```bash
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:

```bash
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:

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

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

```bash
# 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:**
```bash
kubectl -n demo describe cluster qdrant-cluster
kubectl -n demo get events --sort-by='.lastTimestamp'
```

**Pod not starting:**
```bash
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](../kubeblocks-cluster-lifecycle/SKILL.md) | [Docs](https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/04-operations/01-stop-start-restart) |
| Scale CPU / Memory | [vertical-scaling](../kubeblocks-vertical-scaling/SKILL.md) | [Docs](https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/04-operations/) |
| Add / Remove replicas | [horizontal-scaling](../kubeblocks-horizontal-scaling/SKILL.md) | [Docs](https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/04-operations/) |
| Expand storage | [volume-expansion](../kubeblocks-volume-expansion/SKILL.md) | [Docs](https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/04-operations/) |
| Upgrade engine version | [minor-version-upgrade](../kubeblocks-minor-version-upgrade/SKILL.md) | [Docs](https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/04-operations/) |
| Expose externally | [expose-service](../kubeblocks-expose-service/SKILL.md) | [Docs](https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/04-operations/) |
| Backup | [backup](../kubeblocks-backup/SKILL.md) | [Docs](https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/05-backup-restore/02-create-full-backup) |
| Restore | [restore](../kubeblocks-restore/SKILL.md) | [Docs](https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/05-backup-restore/) |

## Safety Patterns

Follow [safety-patterns](../../references/safety-patterns.md): dry-run before apply, confirm success condition after watch, pre-deletion checklist before delete.