---
title: "Kubernetes"
description: "Deploy SurrealDB to Kubernetes with SurrealKV on a persistent volume."
canonical_url: "https://surrealdb.com/docs/operate/self-hosted/kubernetes"
section: "Self-hosted"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:40:10Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Kubernetes

Deploy SurrealDB to Kubernetes with SurrealKV on a persistent volume.

This guide deploys SurrealDB to a local [KIND](https://kind.sigs.k8s.io/) 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](/docs/operate/self-hosted/deployment-models.md#single-node).

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](/docs/operate/self-hosted/deployment-models.md#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](https://surrealdb.com/pricing) or [SurrealDB Enterprise](https://surrealdb.com/enterprise) on managed Kubernetes - see [Managed Kubernetes](/docs/operate/self-hosted/managed-kubernetes.md).

## Requirements

- [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
- [`helm`](https://helm.sh/docs/intro/install/)
- [KIND](https://kind.sigs.k8s.io/) and [Docker](https://www.docker.com/)
- [Surreal CLI](/docs/reference/cli/db.md)

## Create a KIND cluster

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

## Deploy SurrealDB

Use the [SurrealDB Helm chart](https://github.com/surrealdb/helm-charts) with a **ReadWriteOnce** persistent volume. Keep **`replicaCount: 1`** - multiple pods must not share one database directory.

### 1. Add the Helm repository

```bash
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:

```bash
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:

```bash
kubectl port-forward svc/surrealdb 8000:8000
```

In another shell:

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

Upgrade the release without `unauthenticated`:

```bash
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

```bash
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:

```bash
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;
```

> [!NOTE]
> On a full Kubernetes cluster, set `ingress.enabled=true` when installing the chart to expose SurrealDB through a load balancer instead of port-forwarding.

## Next steps

- [Docker](/docs/running/docker.md) - a single node without Kubernetes
- [Run a single-node, on-disk server](/docs/running/file-backed.md) - CLI startup options for SurrealKV
- [Deployment models](/docs/operate/self-hosted/deployment-models.md) - managed, single-node, and highly available options
