Qdrant Setup

Overview

Qdrant is the vector database used by Cobi to store and search document embeddings. The qdrant dependency chart deploys it as a StatefulSet with persistent storage. Default ports:

6333 — HTTP REST API (used by the backend)
6334 — gRPC API

The backend connects to Qdrant at http://<release-name>-qdrant:6333 via the QDRANT_URL environment variable.

Configuration in values.yaml

qdrant:
  enabled: true

  image:
    repository: qdrant/qdrant
    tag: "v1.16.2"          # pin to a specific version — "latest" can break on upgrades
    pullPolicy: IfNotPresent

  service:
    httpPort: 6333
    grpcPort: 6334

  persistence:
    enabled: true
    storageClass: ""        # use cluster default; set to "local-path" or "nfs-csi" for on-prem
    accessModes:
      - ReadWriteOnce
    size: 10Gi              # increase for large document collections

Sizing the PVC

Qdrant stores vectors on disk. The required space depends on:

Factor	Impact
Number of documents	Each document generates one or more vectors
Embedding dimension	Typical embedding models use 384–1536 dimensions
Index type	HNSW graph adds ~1.5× overhead over raw vectors

A rough estimate: ~1 Gi per 500 000 vectors at 768 dimensions with HNSW indexing. Start with 10Gi and expand the PVC when utilization reaches 70%.

On-Premises StorageClass

For clusters without a cloud storage provisioner, set a local or NFS-backed StorageClass:

qdrant:
  persistence:
    storageClass: "local-path"   # rancher local-path-provisioner
    size: 20Gi

Exposing Qdrant (optional)

Qdrant is a ClusterIP service by default (internal only). To expose it for external tooling (e.g., Qdrant Web UI or admin scripts), add an Ingress:

qdrant:
  ingress:
    enabled: true
    ingressClassName: nginx
    annotations: {}
    hosts:
      - host: qdrant.example.com
        paths:
          - path: /
            pathType: Prefix
            servicePort: 6333
    tls: []

Do not expose Qdrant publicly without authentication. The Qdrant HTTP API has no built-in auth by default — restrict access to internal networks or use an ingress that enforces authentication.

Verify Qdrant

# Port-forward the Qdrant HTTP API
kubectl port-forward -n cobi svc/cobi-dashboard-qdrant 6333:6333

# Check cluster health
curl http://localhost:6333/healthz

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

A healthy response from /healthz returns {"title":"qdrant - vector search engine","version":"..."}.

Connecting the Backend

Set the following variables in the backend Secret. The service name follows the pattern <release-name>-qdrant — if your release is named cobi-dashboard, the service is cobi-dashboard-qdrant.

In-cluster Qdrant (deployed via this chart)

kubectl create secret generic cobi-backend-secrets \
  --namespace cobi \
  --from-literal=QDRANT_URL="http://cobi-dashboard-qdrant:6333" \
  --from-literal=QDRANT_LOCAL_ONLY="true" \
  --from-literal=QDRANT_API_KEY="" \
  --from-literal=QDRANT_CLUSTER_KEY="" \
  --from-literal=QDRANT_COLLECTION_PREFIX="prod_" \
  # ... other keys

External / standalone on-prem Qdrant

If Qdrant is running on a separate server or another cluster:

kubectl create secret generic cobi-backend-secrets \
  --namespace cobi \
  --from-literal=QDRANT_URL="http://qdrant.internal.example.com:6333" \
  --from-literal=QDRANT_LOCAL_ONLY="true" \
  --from-literal=QDRANT_API_KEY="" \
  --from-literal=QDRANT_CLUSTER_KEY="" \
  --from-literal=QDRANT_COLLECTION_PREFIX="prod_" \
  # ... other keys

Keep QDRANT_LOCAL_ONLY="true" for any self-hosted Qdrant regardless of where it runs. Set it to "false" only when using Qdrant Cloud.

Qdrant Cloud

kubectl create secret generic cobi-backend-secrets \
  --namespace cobi \
  --from-literal=QDRANT_URL="https://<cluster-id>.us-east4-0.gcp.cloud.qdrant.io:6333" \
  --from-literal=QDRANT_LOCAL_ONLY="false" \
  --from-literal=QDRANT_API_KEY="<qdrant-cloud-api-key>" \
  --from-literal=QDRANT_CLUSTER_KEY="<qdrant-cluster-key>" \
  --from-literal=QDRANT_COLLECTION_PREFIX="prod_" \
  # ... other keys

Backend environment variable reference

Variable	Required	Description
`QDRANT_URL`	Yes	Full HTTP(S) URL of the Qdrant REST API, including port
`QDRANT_LOCAL_ONLY`	Yes	`"true"` for self-hosted (in-cluster or on-prem); `"false"` for Qdrant Cloud
`QDRANT_API_KEY`	Cloud only	API key from the Qdrant Cloud console. Leave empty for local
`QDRANT_CLUSTER_KEY`	Cloud only	Cluster key from the Qdrant Cloud console. Leave empty for local
`QDRANT_COLLECTION_PREFIX`	No	Prefix prepended to all collection names. Use to namespace multiple environments (e.g. `"prod_"`, `"staging_"`) sharing one Qdrant instance

Backup

Qdrant supports snapshot-based backups via its REST API:

# Create a snapshot of a collection
curl -X POST http://localhost:6333/collections/<collection-name>/snapshots

# List snapshots
curl http://localhost:6333/collections/<collection-name>/snapshots

Snapshots are written to the Qdrant PVC. Copy them to external storage using a CronJob or kubectl cp.

Getting Started

Self-Hosted Deployment

Data Sources

Channels

API

Overview

Configuration in values.yaml

Sizing the PVC

On-Premises StorageClass

Exposing Qdrant (optional)

Verify Qdrant

Connecting the Backend

In-cluster Qdrant (deployed via this chart)

External / standalone on-prem Qdrant

Qdrant Cloud

Backend environment variable reference

Backup

​Overview

​Configuration in values.yaml

​Sizing the PVC

​On-Premises StorageClass

​Exposing Qdrant (optional)

​Verify Qdrant

​Connecting the Backend

​In-cluster Qdrant (deployed via this chart)

​External / standalone on-prem Qdrant

​Qdrant Cloud

​Backend environment variable reference

​Backup

Overview

Configuration in values.yaml

Sizing the PVC

On-Premises StorageClass

Exposing Qdrant (optional)

Verify Qdrant

Connecting the Backend

In-cluster Qdrant (deployed via this chart)

External / standalone on-prem Qdrant

Qdrant Cloud

Backend environment variable reference

Backup