Kubernetes

This guide deploys SurrealDB to a local KIND cluster (Kubernetes in Docker) with SurrealKV on a persistent volume. That is a single-node topology: one SurrealDB pod owns the database directory. See Deployment models.

Before SurrealDB 4.0, RocksDB was the recommended engine: to use it on an earlier release, replace surrealkv:// with rocksdb:// in the path values below. SurrealDB 4.0 removed RocksDB; see Moving a RocksDB database to SurrealKV. When a pod that ran on RocksDB is upgraded to 4.0, its data is converted the first time the pod starts. The persistent volume needs room for about twice the data while that happens, and the pod does not answer its probes until the conversion finishes, so raise the probe timeouts for a large database.

For multi-node HA, use the managed Scale plan or SurrealDB Enterprise on managed Kubernetes - see Managed Kubernetes.

Requirements

• •

  kubectl

• •

  helm

• •

  KIND and Docker

• •

  Surreal CLI

Create a KIND cluster

kind create cluster -n surreal-demo
kubectl config current-context   # kind-surreal-demo
kubectl get ns

Deploy SurrealDB

Use the SurrealDB Helm chart with a ReadWriteOnce persistent volume. Keep replicaCount: 1 - multiple pods must not share one database directory.

1. Add the Helm repository

helm repo add surrealdb https://helm.surrealdb.com
helm repo update

2. Install with persistence

The chart mounts storage at /home/nonroot so the non-root container user can write to the volume:

cat <<'EOF' | helm install surrealdb surrealdb/surrealdb -f -
strategy:
  type: Recreate
replicaCount: 1
persistence:
  enabled: true
  mountPath: /home/nonroot
  size: 10Gi
surrealdb:
  path: surrealkv:///home/nonroot/data.db
  unauthenticated: true
EOF

3. Create initial credentials

Port-forward the service, define a root user, then re-enable authentication:

kubectl port-forward svc/surrealdb 8000:8000

In another shell:

surreal db sql -e http://localhost:8000
> DEFINE USER root ON ROOT PASSWORD 'StrongSecretPassword!' ROLES OWNER;

Upgrade the release without unauthenticated:

helm upgrade surrealdb surrealdb/surrealdb -f - <<'EOF'
strategy:
  type: Recreate
replicaCount: 1
persistence:
  enabled: true
  mountPath: /home/nonroot
  size: 10Gi
surrealdb:
  path: surrealkv:///home/nonroot/data.db
EOF

4. Verify persistence

surreal db sql -u root -p 'StrongSecretPassword!' -e http://localhost:8000
> USE NS ns DB db;
ns/db> CREATE record SET id = record:one;
ns/db> SELECT * FROM record;

Delete the SurrealDB pod and confirm data survives on the PVC:

kubectl get pod
kubectl delete pod <surrealdb-pod-name>
kubectl port-forward svc/surrealdb 8000:8000
surreal db sql -u root -p 'StrongSecretPassword!' -e http://localhost:8000
> USE NS ns DB db;
ns/db> SELECT * FROM record;

Next steps

• •

  Docker - a single node without Kubernetes

• •

  Run a single-node, on-disk server - CLI startup options for SurrealKV

• •

  Deployment models - managed, single-node, and highly available options