Deploy on Kubernetes

In this guide, we will deploy SurrealDB to KIND (Kubernetes in Docker) using TiKV as the storage engine. TiKV is a cloud-native transactional key/value store that integrates well with Kubernetes thanks to their TiDB-operator tool.

At the end, we will run a few experiments using SurrealQL to verify that we can interact with the new cluster and then delete some Kubernetes pods to demonstrate that the data remains available.

Requirements

For this guide, we need to install:

• kubectl: To manage the Kubernetes cluster
• helm: To install SurrealDB server and TiKV
• KIND and Docker: To run a local Kubernetes cluster inside a Docker container
• Surreal CLI: To interact with the SurrealDB server

Create KIND Cluster

First, we need to create a KIND cluster. KIND is a tool for running local Kubernetes clusters using Docker container “nodes”. It’s a great tool for experimenting with Kubernetes without spending a lot of time creating a full-featured cluster.

1. Create a new cluster

Run the following command to create a cluster:

Create new cluster
kind create cluster -n surreal-demo

2. Verify interaction with cluster

Run the following command to verify that we can interact with the created cluster:

Verify cluster
kubectl config current-context

The output of this command should be:

kind-surreal-demo

3. Verify that nodes are running

Run the following command to verify that the nodes are running:

kubectl get ns

The output of this command should be:

NAME                 STATUS   AGE
default              Active   79s
kube-node-lease      Active   79s
kube-public          Active   79s
kube-system          Active   79s
local-path-storage   Active   75s

Deploy TiDB operator

Now that we have a Kubernetes cluster, we can deploy the TiDB operator. TiDB operator is a Kubernetes operator that manages the lifecycle of TiDB clusters deployed to Kubernetes.

You can deploy it following these steps:

1. Install CRDS:

CRDS installation
kubectl create -f https://raw.githubusercontent.com/pingcap/tidb-operator/v1.4.5/manifests/crd.yaml

2. Install TiDB Operator Helm chart:

Update HELM repositories
helm repo add pingcap https://charts.pingcap.org
helm repo update
helm install \
	-n tidb-operator \
  --create-namespace \
	tidb-operator \
	pingcap/tidb-operator \
	--version v1.4.5

3. Verify that the pods are running:

Get pod status
kubectl get pods --namespace tidb-operator -l app.kubernetes.io/instance=tidb-operator

The output of this command should look like this:

NAME                                       READY   STATUS    RESTARTS   AGE
tidb-controller-manager-56f49794d7-hnfz7   1/1     Running   0          20s
tidb-scheduler-8655bcbc86-66h2d            2/2     Running   0          20s

Create TiDB cluster

Now that we have the TiDB Operator running, it’s time to define a TiDB Cluster and let the Operator do the rest. One of the TiDB Cluster components is the TiKV, which we are interested in. Given this is a demo, we will use a basic example cluster, but there are several examples in the official GitHub repo in case you need a more production-grade deployment

Run the following commands to deploy the TiKV cluster:

1. Create TiDB cluster namespace

Run the following command to create a namespace for the TiDB cluster:

kubectl create ns tikv

2. Create TiDB cluster

Run the following command to create the TiDB cluster:

TiDB cluster creation
kubectl apply -n tikv -f https://raw.githubusercontent.com/pingcap/tidb-operator/v1.4.5/examples/basic/tidb-cluster.yaml

3. Check cluster status

Run the following command to check the cluster status and wait until it’s ready:

Verify TiDB cluster
kubectl get -n tikv tidbcluster

The output of this command should look like this:

NAME    READY   PD                  STORAGE   READY   DESIRE   TIKV   STORAGE   READY   DESIRE   TIDB   READY   DESIRE   AGE
basic   False   pingcap/pd:v6.5.0   1Gi       1       1               1Gi               1                       1        41s
$ kubectl get -n tikv tidbcluster
NAME    READY   PD                  STORAGE   READY   DESIRE   TIKV                  STORAGE   READY   DESIRE   TIDB                  READY   DESIRE   AGE
basic   True    pingcap/pd:v6.5.0   1Gi       1       1        pingcap/tikv:v6.5.0   1Gi       1       1        pingcap/tidb:v6.5.0   1       1        5m

Deploy SurrealDB

Now that we have a TiDB cluster running, we can deploy SurrealDB. For this guide, we will use the SurrealDB Helm chart. Run the following commands to deploy SurrealDB:

1. Add SurrealDB Charts repository

Run the following command to add the SurrealDB Charts repository:

Add Helm repository
helm repo add surrealdb https://helm.surrealdb.com
helm repo update

2. Get TiKV PD service URL

Run the following command to get the TiKV PD service URL:

Get TiKV URL
kubectl get -n tikv svc/basic-pd

The output of this command should look like this:

NAME       TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
basic-pd   ClusterIP   10.96.208.25   <none>        2379/TCP   10h

Then set the TIKV_URL variable to the PD service URL:

Set TIKV_URL var
export TIKV_URL=tikv://basic-pd.tikv:2379

3. Install SurrealDB Helm chart to create initial credentials

Now we can install the SurrealDB Helm chart with TIKV_URL defined above and auth disabled so that we can create the initial credentials:

Install SurrealDB HELM chart
helm install --set surrealdb.path=$TIKV_URL --set surrealdb.unauthenticated=true --set image.tag=latest surrealdb-tikv surrealdb/surrealdb

4. Connect to cluster and define initial credentials

We can then connect to the cluster and define the initial credentials (see the section below to connect):

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

Verify you can connect to the database with the new credentials:

surreal sql -u root -p 'StrongSecretPassword!' -e http://...
> INFO FOR ROOT
[{ accesses: {  }, namespaces: {  }, nodes: { "0e87c953-68d7-40e1-9090-3dfc404af25e": 'NODE 0e87c953-68d7-40e1-9090-3dfc404af25e SEEN 1742869518357 ACTIVE' }, system: { available_parallelism: 14, cpu_usage: 4.321133613586426f, load_average: [2.2265625f, 2.2138671875f, 2.044921875f], memory_allocated: 13428527, memory_usage: 154812416, physical_cores: 14, threads: 32 }, users: { root: "DEFINE USER root ON ROOT PASSHASH '...' ROLES OWNER DURATION FOR TOKEN 1h, FOR SESSION NONE" } }]

5. Enable authentication

Authentication can be enabled now that the initial credentials have been created:

Update SurrealDB Helm Chart
helm upgrade --set surrealdb.path=$TIKV_URL --set image.tag=latest surrealdb-tikv surrealdb/surrealdb

Run SurrealDB experiments

Now that we have SurrealDB running, we can run some experiments to verify that everything is working as expected. For this guide, we will use the Surreal CLI. Run the following commands to run some experiments:

1. Start port forwarding to the SurrealDB service

kubectl port-forward svc/surrealdb-tikv 8000

Output
Forwarding from 127.0.0.1:8000 -> 8000
Forwarding from [::1]:8000 -> 8000

2. Connect to the SurrealDB server

Use the following command to connect to the SurrealDB server using the CLI from another shell:

surreal sql --conn 'http://localhost:8000' --user root --pass surrealdb

3. Create a SurrealDB database

Use the following to create a SurrealDB database and try out a few queries:

surreal sql --conn 'http://localhost:8000' --user root --pass surrealdb
> USE NS ns DB db;

ns/db> CREATE record;
{ id: record:wbd69kmc81l4fbee7pit }
ns/db> CREATE record;
{ id: record:vnyfsr22ovhmmtcm5y1t }
ns/db> CREATE record;
{ id: record:se49petzb7c4bc7yge0z }
ns/db> SELECT * FROM record;
[{ id: record:se49petzb7c4bc7yge0z }, { id: record:vnyfsr22ovhmmtcm5y1t }, { id: record:wbd69kmc81l4fbee7pit }]
ns/db>

The data created above has been persisted to the TiKV cluster. Let’s verify it by deleting the SurrealDB server and let Kubernetes recreate it.

We will first use get pod to get the names of the existing pods:

Get pod
kubectl get pod

The output of this command should look like this:

NAME                              READY   STATUS    RESTARTS   AGE
surrealdb-tikv-7488f6f654-lsrwp   1/1     Running   0          13m

We can then grab the name and use delete pod to delete it.

kubectl delete pod surrealdb-tikv-7488f6f654-lsrwp

A get pod command shows us that the pod has been recreated under a different name.

kubectl get pod

Output
NAME                              READY   STATUS    RESTARTS   AGE
surrealdb-tikv-7488f6f654-bnkjz   1/1     Running   0          4s

We can now connect again and verify the data is still there (you may need to re-run the port-forwarding command):

surreal sql --conn 'http://localhost:8000' --user root --pass surrealdb
> USE NS ns DB db;

ns/db> SELECT * FROM record;
[{ id: record:se49petzb7c4bc7yge0z }, { id: record:vnyfsr22ovhmmtcm5y1t }, { id: record:wbd69kmc81l4fbee7pit }]
ns/db>

Note

Given we are using KIND, we use port-forwarding for demonstration purposes. In a full-featured Kubernetes cluster, you could set ingress.enabled=true when installing the SurrealDB Helm Chart and it would create a Load Balancer in front of the SurrealDB server pods.

Conclusion

This guide demonstrated how to deploy SurrealDB on Kubernetes using TiKV as a datastore. From here, you could try and deploy to EKS, GKE or AKS, and play with the different configurations for the TiKV cluster.