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.
At the end, we will run a few experiments using SurrealQL to verify that we can interact with the new cluster and will destroy some Kubernetes pods to see that data is highly available.
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.
Run the following command to create a cluster:
Let’s create a new cluster:
$ kind create cluster -n surreal-demo
Verify we can interact with the created cluster
$ kubectl config current-context
kind-surreal-demo
$ kubectl get ns
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.
$ kubectl get pods --namespace tidb-operator -l app.kubernetes.io/instance=tidb-operato
r
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:
$ kubectl get -n tikv svc/basic-pd
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
basic-pd ClusterIP 10.96.208.25 <none>2379/TCP 10h
$ exportTIKV_URL=tikv://basic-pd.tikv:2379
Install the SurrealDB Helm chart with the TIKV_URL defined above and with auth disabled so we can create the initial credentials:
Connect to the cluster and define the initial credentials (see in the section below how 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
[{ namespaces: {}, users: { root: "DEFINE USER root ON ROOT PASSHASH '...' ROLES OWNER"}}]
Now that the initial credentials have been created, enable authentication:
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.
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
surrealdb-tikv-7488f6f654-lsrwp 1/1 Running 0 13m
$ kubectl delete pod surrealdb-tikv-7488f6f654-lsrwp
pod "surrealdb-tikv-7488f6f654-lsrwp" deleted
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
surrealdb-tikv-7488f6f654-bnkjz 1/1 Running 0 4s
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>
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.