Kubernetes Deployment

RelataDB ships as a single binary, making it straightforward to deploy on Kubernetes.

Helm chart

helm repo add relata https://charts.relatadb.dev
helm install relata relata/relata-db \
  --set profile=server \
  --set tenancyMode=multi \
  --set persistence.enabled=true \
  --set persistence.size=100Gi

Basic deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: relata-db
spec:
  replicas: 1
  selector:
    matchLabels:
      app: relata-db
  template:
    metadata:
      labels:
        app: relata-db
    spec:
      containers:
        - name: relata-db
          image: ghcr.io/relatadb/relata:latest
          ports:
            - containerPort: 9090
              name: http
            - containerPort: 5433
              name: pgwire
            - containerPort: 50051
              name: grpc
          env:
            - name: RELATA_PROFILE
              value: server
            - name: RELATA_BEARER_TOKEN
              valueFrom:
                secretKeyRef:
                  name: relata-secrets
                  key: admin-token
            - name: RELATA_TENANCY_MODE
              value: multi
            - name: AWS_ENDPOINT_URL
              value: https://s3.amazonaws.com
            - name: AWS_S3_BUCKET
              value: my-bucket
          volumeMounts:
            - name: data
              mountPath: /data
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 9090
          livenessProbe:
            httpGet:
              path: /health/live
              port: 9090
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: relata-data

Persistent storage

For production, use a PersistentVolumeClaim or configure object storage (S3/GCS/Azure Blob):

AWS_ENDPOINT_URL=https://s3.amazonaws.com
AWS_S3_BUCKET=my-bucket

Credentials go via AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (see Environment Variables). For a native GCS/Azure backend instead of the S3-compatible path, use RELATA_OBJECT_STORE (gcs://bucket/prefix or azure://container/prefix).

When object storage is configured, the PVC is used only for WAL segments and local cache — the source of truth is the object store. This enables stateless compute nodes.

Cluster mode

For horizontal scaling, deploy multiple replicas with RELATA_PROFILE=cluster:

spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: relata-db
          env:
            - name: RELATA_PROFILE
              value: cluster
            - name: NODE_ID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name

All nodes share the same object store. Consistent hashing distributes segment ownership. Query fan-out merges results across nodes.

A single Deployment/StatefulSet template gives every replica the same CLUSTER_ROLE (defaults to coordinator if unset). To run dedicated reader/writer/indexer nodes instead, split them into separate specs — see Cluster Setup for the role breakdown and a worked multi-role example.

Health checks

ProbeEndpointPurpose
LivenessGET /health/liveProcess is alive
ReadinessGET /health/readyReady to serve (indexes loaded)
StartupGET /health/readyWait for boot before traffic

Protocol ports

PortProtocolUse
9090HTTPREST API, health, metrics
5433PostgreSQL wirepsql, psycopg2, pgvector
50051gRPCgRPC / Arrow Flight door
7687BoltNeo4j drivers, Cypher
27017Mongo wireMongoDB drivers

Monitoring

env:
  - name: RELATA_METRICS_PUBLIC
    value: "true"

Scrape /metrics for Prometheus metrics. See Observability for the full metrics reference.

See also

  • Deployment — profiles and configuration
  • Cluster Setup — the non-Kubernetes mechanics: every env var cluster profile needs and the gotchas behind a working (or silently broken) fan-out
  • Scaling — cluster sizing and capacity planning
  • Configuration — environment variables