What You Need Before You Start

• A running Kubernetes cluster — local (minikube, kind, k3s) or cloud-managed (EKS, GKE, AKS)
• kubectl — configured and pointing at your cluster
• Helm 3 — the Kubernetes package manager; install with brew install helm or the official script
• A StorageClass that provisions PVCs — most managed clusters include one by default
• Node resources — minimum 2 CPU cores and 4 GB RAM available per database node

How Kubernetes Handles a Vector Database

A vector database on Kubernetes runs as a StatefulSet — a workload type built for applications that need stable network identities and per-pod persistent storage. Unlike a Deployment, each StatefulSet pod gets a predictable hostname and its own PersistentVolumeClaim, ensuring the database index survives restarts and rescheduling.

Most production-ready open-source vector databases ship an official Helm chart that handles the StatefulSet definition, Services, ConfigMaps, and optional ingress configuration — so you do not need to write the Kubernetes manifests by hand.

Prerequisites: What to Confirm Before Deploying

• Your cluster has a default StorageClass — run kubectl get storageclass to check
• You have enough allocatable memory on at least one node — kubectl describe nodes | grep -A5 Allocatable
• Helm is installed — helm version

Example: Deploying a Free Vector Database with Helm

The following example uses an open-source vector database that publishes an official Helm chart. The same pattern applies to any vector database that ships a Helm chart — add the repo, inspect the values, customize, and install.

Step 1 — Add the Helm Repository

helm repo add weaviate https://weaviate.github.io/weaviate-helm
helm repo update

Step 2 — Export the Default Configuration

helm show values weaviate/weaviate > values.yaml

This exports all configurable options to a file you can edit before installing. This is the standard Helm workflow for any chart.

Step 3 — Minimal values.yaml for a Single-Node Deployment

replicas: 1

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

storage:
  size: 32Gi

env:
  QUERY_DEFAULTS_LIMIT: "25"
  AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: "true"
  PERSISTENCE_DATA_PATH: "/var/lib/weaviate"
  CLUSTER_HOSTNAME: "node1"

Step 4 — Install into a Dedicated Namespace

kubectl create namespace vector-db

helm install vector-db weaviate/weaviate \
  --namespace vector-db \
  --values values.yaml

Step 5 — Verify the Deployment

kubectl get pods -n vector-db -w

# Once running, test the API
kubectl port-forward svc/weaviate 8080:80 -n vector-db
curl http://localhost:8080/v1/meta

Persistent Storage on Kubernetes

A vector database index must be persisted to disk or it is lost when the pod restarts. The Helm chart provisions a PVC per replica automatically. You can specify the StorageClass and size in values.yaml:

storage:
  size: 50Gi
  storageClassName: "standard"  # replace with your cluster's StorageClass name

For production, use an SSD-backed StorageClass. Vector indexes rely on random I/O, and disk speed directly affects query latency.

Scaling to Multiple Nodes

Open-source vector databases that support clustering can be scaled horizontally on Kubernetes by increasing the replica count and setting the cluster discovery variables. The example below shows a 3-node setup:

replicas: 3

env:
  CLUSTER_HOSTNAME: "node1"
  CLUSTER_GOSSIP_BIND_PORT: "7100"
  CLUSTER_DATA_BIND_PORT: "7101"
  RAFT_JOIN: "node1,node2,node3"
  RAFT_BOOTSTRAP_EXPECT: "3"

The Helm chart uses the StatefulSet’s stable DNS names for inter-node discovery — no manual service registration needed.

Exposing the Database via Ingress

To access the vector database over a domain, configure the Helm chart’s ingress section. Most free vector databases expose two ports: one for HTTP (REST/GraphQL) and one for gRPC:

ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: vectordb.yourdomain.com
      paths:
        - path: /
          pathType: Prefix
  grpc:
    enabled: true
    host: grpc-vectordb.yourdomain.com

Common Helm Commands

# Apply updated values without reinstalling
helm upgrade vector-db weaviate/weaviate --namespace vector-db --values values.yaml

# Remove the deployment (PVCs are kept by default)
helm uninstall vector-db --namespace vector-db

# Check release status
helm list -n vector-db

Frequently Asked Questions

Can I run a free vector database on a local Kubernetes cluster?

Yes. Tools like minikube, kind, and k3s let you run a full Kubernetes environment locally. Start minikube with enough resources (minikube start --cpus 4 --memory 8192) and follow the same Helm steps above. Use kubectl port-forward to access the service from your machine.

Which StorageClass should I use?

Start with your cluster’s default StorageClass. For production, choose an SSD-backed class — vector database index structures (particularly HNSW) perform significantly better on fast random I/O.

How do I upgrade the database version?

Update the image tag in values.yaml and run helm upgrade. On a multi-node cluster with a rolling update strategy configured, this can be done with minimal downtime.