Qdrant

Deploy Qdrant on Kubernetes for semantic search, RAG, recommendations, and vector similarity workloads.

Overview

The HelmForge Qdrant chart uses the official docker.io/qdrant/qdrant:v1.18.2 image and deploys a StatefulSet. It exposes HTTP on 6333, gRPC on 6334, and the cluster peer port on 6335.

The default topology is a single persistent pod. Distributed mode is available, but it is guarded because Qdrant clustering requires per-pod storage, peer communication, and operator knowledge of collection replication and shard placement. When distributed mode is enabled, the chart derives stable StatefulSet peer DNS names and starts the first pod with --uri; later pods join that peer with --bootstrap.

Installation

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install qdrant helmforge/qdrant

OCI install:

helm install qdrant oci://ghcr.io/helmforgedev/helm/qdrant

Production Example

auth:
  existingSecret: qdrant-auth
  apiKeyKey: api-key
  readOnlyApiKeyKey: read-only-api-key

persistence:
  enabled: true
  size: 50Gi

resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: '2'
    memory: 4Gi

networkPolicy:
  enabled: true

Runtime Values

Core runtime:

image.repository, image.tag, image.pullPolicy: official pinned Qdrant image and pull behavior.
imagePullSecrets: optional registry pull secrets.
replicaCount: StatefulSet replica count. Keep 1 unless cluster.enabled=true is planned.
clusterDomain: Kubernetes DNS domain used for StatefulSet peer discovery, default cluster.local.
app.port, app.grpcPort: HTTP and gRPC container ports.
app.command, app.args: optional command and argument overrides. In cluster mode the chart owns command; use app.args.
app.env, app.extraEnv: extra Qdrant environment variables, including QDRANT__ nested config overrides.
config.localYaml: optional /qdrant/config/local.yaml content.

Storage and snapshots:

persistence.enabled, persistence.size, persistence.storageClass: generated per-pod storage.
persistence.accessModes: generated PVC access modes, default ReadWriteOnce.
persistence.existingClaim: existing PVC for single-replica deployments. It is rejected with cluster.enabled=true.
persistence.mountPath: Qdrant storage path, default /qdrant/storage.
snapshots.path: snapshot path, default /qdrant/storage/snapshots.

Security and exposure:

auth.apiKey, auth.readOnlyApiKey: inline lab keys.
auth.existingSecret, auth.apiKeyKey, auth.readOnlyApiKeyKey: production Secret wiring.
serviceAccount.create, serviceAccount.name, serviceAccount.annotations, serviceAccount.automountServiceAccountToken.
service.type, service.port, service.grpcPort, service.annotations, service.ipFamilyPolicy, service.ipFamilies.
ingress.enabled, ingress.ingressClassName, ingress.annotations, ingress.hosts, ingress.tls.
gateway.enabled, gateway.parentRefs, gateway.hostnames, gateway.path, gateway.pathType.
networkPolicy.enabled, networkPolicy.ingressFrom: client ingress peers. Cluster p2p traffic gets a separate self-peer rule.

Operations:

metrics.serviceMonitor.*: optional Prometheus Operator ServiceMonitor for /metrics.
pdb.enabled, pdb.minAvailable: disruption budget for multi-pod deployments.
probes.startup, probes.liveness, probes.readiness: enable flags and timing values.
resources, podSecurityContext, securityContext: resource and pod/container hardening knobs.
nodeSelector, tolerations, affinity, topologySpreadConstraints, priorityClassName.
terminationGracePeriodSeconds, podLabels, podAnnotations.
extraVolumes, extraVolumeMounts, extraManifests.

Distributed Mode

cluster:
  enabled: true
  p2pPort: 6335
replicaCount: 3
persistence:
  enabled: true

Distributed mode requires at least two replicas, persistence, and chart-managed PVCs. The chart blocks unsafe combinations at render time. The chart also owns the startup command in distributed mode so it can pass Qdrant the required peer bootstrap arguments; use app.args for additional Qdrant flags. Plan snapshots, restore procedures, and collection replication before enabling this in production.

Monitoring

Qdrant exposes Prometheus metrics at /metrics.

metrics:
  serviceMonitor:
    enabled: true
    interval: 30s

Enable metrics.serviceMonitor only when the Prometheus Operator CRDs exist in the cluster.

Backup

Back up the Qdrant PVC and snapshot directory. For distributed clusters, capture snapshots for all relevant shards and validate restore procedures before relying on the backup policy.