Getting Started with Vald: Deploy a Distributed Vector Search Engine on Kubernetes

Quick Start: Deploy Vald on Kubernetes

This guide walks you through deploying a Vald cluster on Kubernetes using Helm. By the end, you'll have a fully functional distributed vector search engine capable of handling millions of vectors with automated indexing, load balancing, and fault tolerance.

Prerequisites

• A Kubernetes cluster (v1.20+) — Minikube, Kind, or any cloud provider
• Helm v3 installed
• kubectl configured to communicate with your cluster

Step 1: Add the Vald Helm Repository

helm repo add vald https://vald.vdaas.org/charts
helm repo update

Step 2: Install Vald

Create a namespace and install Vald with default configuration:

kubectl create namespace vald-system

helm install vald-cluster \
  --namespace vald-system \
  vald/vald

This deploys the full Vald stack including agent pods (vald-agent-ngt), gateway services (lb-gateway, filter-gateway), and supporting components.

Step 3: Verify the Deployment

kubectl get pods -n vald-system

You should see agent pods, gateway pods, and sidecar containers all running and ready. A typical deployment creates:

• 2-3 vald-agent-ngt pods (the indexing and search engines)
• 1-2 vald-lb-gateway pods (load balancing gateway)
• 1 vald-filter-gateway pod (filter support)
• 1 vald-mirror-gateway pod (data mirroring for backup)

Step 4: Port Forward to the Gateway

kubectl port-forward \
  --namespace vald-system \
  svc/vald-cluster-vald-lb-gateway \
  8080:8080

Vald's gRPC and HTTP APIs are now accessible at localhost:8080.

Step 5: Insert and Search Vectors

Vald provides both gRPC and REST APIs. Here's how to insert vectors and perform search using the HTTP API:

Insert a Vector

curl -X POST http://localhost:8080/insert \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": {
      "id": "vec-001",
      "vector": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]
    },
    "config": {
      "skip_strict_exist_check": true
    }
  }'

Search for Similar Vectors

curl -X POST http://localhost:8080/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": {
      "id": "",
      "vector": [0.11, 0.21, 0.31, 0.41, 0.51, 0.61, 0.71, 0.81]
    },
    "config": {
      "num": 10,
      "radius": -1.0
    }
  }'

The search returns the top-k most similar vectors along with their distance scores.

Step 6: Monitor with Prometheus

Vald natively exposes Prometheus metrics at /metrics on each component. The Helm chart can be configured to include a ServiceMonitor for automatic Prometheus discovery:

helm upgrade vald-cluster \
  --namespace vald-system \
  vald/vald \
  --set prometheus.enabled=true \
  --set prometheus.serviceMonitor.enabled=true

Grafana dashboards are available in the Vald repository for visualizing search latency, indexing throughput, and cluster health.

Production Configuration Tips

Scaling Agent Pods

The number of agent pods determines your indexing and search capacity. For production, start with at least 3 agents and scale based on your vector count and query rate:

helm upgrade vald-cluster \
  --namespace vald-system \
  vald/vald \
  --set agent.replicaCount=5 \
  --set agent.resources.requests.memory=4Gi

Storage Configuration

Each agent pod stores its index on a persistent volume. For production, configure SSDs for optimal indexing performance:

--set agent.persistence.storageClass=ssd \
--set agent.persistence.size=100Gi

Ingress Configuration

For external access, configure an Ingress or LoadBalancer for the gateway service:

--set gateway.lb.service.type=LoadBalancer

Conclusion

Vald provides a powerful, Kubernetes-native vector search platform that scales with your data. Its automated index management, load-balanced gateway architecture, and cloud-native design make it an excellent choice for organizations needing production-grade similarity search. While the initial setup requires Kubernetes expertise, the operational benefits at scale — automatic failover, rolling updates, and declarative configuration — significantly reduce long-term operational overhead.