mdcms/sample-sites/neuraldb-docs/pages/install-kubernetes.md

title	sort	section-id	keywords	description	language
Kubernetes	110	installation	Kubernetes, Helm, StatefulSet, PVC, k8s, cluster, deployment	Deploying NeuralDB on Kubernetes using the official Helm chart and StatefulSets	en

Kubernetes

The recommended way to run NeuralDB on Kubernetes is via the official Helm chart. The chart deploys NeuralDB as a StatefulSet with persistent volume claims, and supports both standalone and high-availability configurations.

Prerequisites

• Kubernetes 1.27+
• Helm 3.x
• A storage class that supports ReadWriteOnce PVCs (most cloud providers support this)
• At least 4 CPU cores and 8 GB RAM per NeuralDB node

Installing the Helm Chart

# Add the NeuralDB Helm repository
helm repo add neuraldb https://charts.neuraldb.io
helm repo update

# Create a namespace
kubectl create namespace neuraldb

# Install the chart
helm install neuraldb neuraldb/neuraldb \
  --namespace neuraldb \
  --set auth.password=mysecretpassword \
  --set persistence.size=100Gi

Chart Configuration

Create a values.yaml file for production settings:

# values.yaml

image:
  repository: neuraldb/neuraldb
  tag: "1.0"
  pullPolicy: IfNotPresent

auth:
  # Set via --set auth.password=... or a pre-existing secret
  existingSecret: ""
  secretKey: "neuraldb-password"

replicaCount: 1          # primary nodes (use 1 for standalone)
readReplicaCount: 2      # read replicas

resources:
  requests:
    cpu: "2"
    memory: "8Gi"
  limits:
    cpu: "8"
    memory: "32Gi"

persistence:
  enabled: true
  storageClass: "fast-ssd"    # use a fast SSD storage class
  size: 500Gi
  walSize: 50Gi               # separate PVC for WAL

vectorBuffer: "16Gi"          # memory for HNSW index
sharedBuffers: "8Gi"          # row store page cache
maxConnections: 200

service:
  type: ClusterIP
  port: 5432

# High-availability configuration
ha:
  enabled: true
  replication:
    mode: synchronous          # 'synchronous' or 'asynchronous'
    synchronousCommit: "on"

backup:
  enabled: true
  schedule: "0 2 * * *"
  s3:
    bucket: my-neuraldb-backups
    region: us-east-1
    existingSecret: aws-credentials

monitoring:
  enabled: true
  serviceMonitor:
    enabled: true              # requires Prometheus Operator

Apply the values:

helm install neuraldb neuraldb/neuraldb \
  --namespace neuraldb \
  -f values.yaml \
  --set auth.password=$(openssl rand -base64 32)

StatefulSet Details

The chart deploys a StatefulSet with:

• One pod per replica (primary + read replicas)
• Two PVCs per pod: data volume and WAL volume
• An init container that configures replication on startup

# Example pod spec (simplified)
spec:
  containers:
  - name: neuraldb
    image: neuraldb/neuraldb:1.0
    ports:
    - containerPort: 5432
    resources:
      requests:
        memory: "8Gi"
        cpu: "2"
    volumeMounts:
    - name: data
      mountPath: /var/lib/neuraldb/data
    - name: wal
      mountPath: /var/lib/neuraldb/wal
    livenessProbe:
      exec:
        command: ["pg_isready", "-U", "neuraldb"]
      initialDelaySeconds: 30
      periodSeconds: 10
    readinessProbe:
      exec:
        command: ["pg_isready", "-U", "neuraldb"]
      initialDelaySeconds: 5
      periodSeconds: 5

Services

The chart creates three Kubernetes services:

Service	Type	Port	Description
neuraldb-primary	ClusterIP	5432	Primary — reads + writes
neuraldb-replica	ClusterIP	5432	Read replicas — reads only
neuraldb-headless	Headless	5432	For StatefulSet pod discovery

Connect to the primary:

kubectl port-forward svc/neuraldb-primary 5432:5432 -n neuraldb
psql -h localhost -U neuraldb

Persistent Volume Claims

Each pod gets two PVCs:

volumeClaimTemplates:
- metadata:
    name: data
  spec:
    accessModes: ["ReadWriteOnce"]
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 500Gi
- metadata:
    name: wal
  spec:
    accessModes: ["ReadWriteOnce"]
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 50Gi

Use a fast-ssd storage class (AWS gp3, GCP pd-ssd, Azure Premium_LRS) for the data and WAL volumes. Spinning disks are not supported in production.

Secrets Management

Store the NeuralDB password in a Kubernetes secret:

kubectl create secret generic neuraldb-credentials \
  --namespace neuraldb \
  --from-literal=password=$(openssl rand -base64 32)

Reference it in values.yaml:

auth:
  existingSecret: neuraldb-credentials
  secretKey: password

For larger installations, use an external secrets manager (HashiCorp Vault, AWS Secrets Manager) with the External Secrets Operator.

Scaling Read Replicas

Scale the number of read replicas without downtime:

helm upgrade neuraldb neuraldb/neuraldb \
  --namespace neuraldb \
  --set readReplicaCount=4

The new replica pods will join the replication stream automatically.

Upgrading

helm repo update
helm upgrade neuraldb neuraldb/neuraldb \
  --namespace neuraldb \
  -f values.yaml \
  --set auth.existingSecret=neuraldb-credentials

The upgrade performs a rolling update — replicas are updated first, then the primary.