You are looking at the documentation of a prior release. To read the documentation of the latest release, please
visit here.
New to KubeDB? Please start here.
Redis QuickStart
This tutorial will show you how to use KubeDB to run a Redis server.
Before You Begin
At first, you need to have a Kubernetes cluster, and the
kubectl
command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using kind.Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps here.
StorageClass is required to run KubeDB. Check the available StorageClass in cluster.
$ kubectl get storageclasses NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE standard (default) rancher.io/local-path Delete WaitForFirstConsumer false 4h
To keep things isolated, this tutorial uses a separate namespace called
demo
throughout this tutorial. Run the following command to prepare your cluster for this tutorial:$ kubectl create namespace demo namespace/demo created $ kubectl get namespaces NAME STATUS AGE demo Active 10s
Note: The yaml files used in this tutorial are stored in docs/examples folder in GitHub repository kubedb/docs.
Find Available RedisVersion
When you have installed KubeDB, it has created RedisVersion
crd for all supported Redis versions. Check:
$ kubectl get redisversions
NAME VERSION DB_IMAGE DEPRECATED AGE
4.0.11 4.0.11 kubedb/redis:4.0.11 7h31m
4.0.6-v2 4.0.6 kubedb/redis:4.0.6-v2 7h31m
5.0.14 5.0.14 redis:5.0.14 7h31m
5.0.3-v1 5.0.3 kubedb/redis:5.0.3-v1 7h31m
6.0.6 6.0.6 kubedb/redis:6.0.6 7h31m
6.2.5 6.2.5 redis:6.2.5 7h31m
6.2.7 6.2.7 redis:6.2.7 7h31m
6.2.8 6.2.8 redis:6.2.8 7h31m
7.0.4 7.0.4 redis:7.0.4 7h31m
7.0.5 7.0.5 redis:7.0.5 7h31m
7.0.6 7.0.6 redis:7.0.6 7h31m
Create a Redis server
KubeDB implements a Redis
CRD to define the specification of a Redis server. Below is the Redis
object created in this tutorial.
apiVersion: kubedb.com/v1alpha2
kind: Redis
metadata:
name: redis-quickstart
namespace: demo
spec:
version: 6.2.5
storageType: Durable
storage:
storageClassName: "standard"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
terminationPolicy: DoNotTerminate
$ kubectl create -f https://github.com/kubedb/docs/raw/v2023.02.28/docs/examples/redis/quickstart/demo-1.yaml
redis.kubedb.com/redis-quickstart created
Here,
spec.version
is name of the RedisVersion crd where the docker images are specified. In this tutorial, a Redis 6.2.5 database is created.spec.storageType
specifies the type of storage that will be used for Redis server. It can beDurable
orEphemeral
. Default value of this field isDurable
. IfEphemeral
is used then KubeDB will create Redis server usingEmptyDir
volume. In this case, you don’t have to specifyspec.storage
field. This is useful for testing purposes.spec.storage
specifies PVC spec that will be dynamically allocated to store data for this database. This storage spec will be passed to the StatefulSet created by KubeDB operator to run database pods. You can specify any StorageClass available in your cluster with appropriate resource requests.spec.terminationPolicy
gives flexibility whether tonullify
(reject) the delete operation ofRedis
crd or which resources KubeDB should keep or delete when you deleteRedis
crd. If admission webhook is enabled, It prevents users from deleting the database as long as thespec.terminationPolicy
is set toDoNotTerminate
. Learn details of allTerminationPolicy
here
Note:
spec.storage
section is used to create PVC for database pod. It will create PVC with storage size specified in storage.resources.requests field. Don’t specify limits here. PVC does not get resized automatically.
KubeDB operator watches for Redis
objects using Kubernetes api. When a Redis
object is created, KubeDB operator will create a new StatefulSet and a Service with the matching Redis object name. KubeDB operator will also create a governing service for StatefulSets with the name kubedb
, if one is not already present.
$ kubectl get rd -n demo
NAME VERSION STATUS AGE
redis-quickstart 6.2.5 Running 1m
$ kubectl describe rd -n demo redis-quickstart
Name: redis-quickstart
Namespace: demo
CreationTimestamp: Tue, 31 May 2022 10:31:38 +0600
Labels: <none>
Annotations: <none>
Replicas: 1 total
Status: Ready
StorageType: Durable
Volume:
StorageClass: standard
Capacity: 1Gi
Access Modes: RWO
Paused: false
Halted: false
Termination Policy: DoNotTerminate
StatefulSet:
Name: redis-quickstart
CreationTimestamp: Tue, 31 May 2022 10:31:38 +0600
Labels: app.kubernetes.io/component=database
app.kubernetes.io/instance=redis-quickstart
app.kubernetes.io/managed-by=kubedb.com
app.kubernetes.io/name=redises.kubedb.com
Annotations: <none>
Replicas: 824644335612 desired | 1 total
Pods Status: 1 Running / 0 Waiting / 0 Succeeded / 0 Failed
Service:
Name: redis-quickstart
Labels: app.kubernetes.io/component=database
app.kubernetes.io/instance=redis-quickstart
app.kubernetes.io/managed-by=kubedb.com
app.kubernetes.io/name=redises.kubedb.com
Annotations: <none>
Type: ClusterIP
IP: 10.96.216.57
Port: primary 6379/TCP
TargetPort: db/TCP
Endpoints: 10.244.0.58:6379
Service:
Name: redis-quickstart-pods
Labels: app.kubernetes.io/component=database
app.kubernetes.io/instance=redis-quickstart
app.kubernetes.io/managed-by=kubedb.com
app.kubernetes.io/name=redises.kubedb.com
Annotations: <none>
Type: ClusterIP
IP: None
Port: db 6379/TCP
TargetPort: db/TCP
Endpoints: 10.244.0.58:6379
AppBinding:
Metadata:
Creation Timestamp: 2022-05-31T04:31:38Z
Labels:
app.kubernetes.io/component: database
app.kubernetes.io/instance: redis-quickstart
app.kubernetes.io/managed-by: kubedb.com
app.kubernetes.io/name: redises.kubedb.com
Name: redis-quickstart
Namespace: demo
Spec:
Client Config:
Service:
Name: redis-quickstart
Port: 6379
Scheme: redis
Parameters:
API Version: config.kubedb.com/v1alpha1
Kind: RedisConfiguration
Stash:
Addon:
Backup Task:
Name: redis-backup-6.2.5
Restore Task:
Name: redis-restore-6.2.5
Secret:
Name: redis-quickstart-auth
Type: kubedb.com/redis
Version: 6.2.5
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Successful 2m Redis Operator Successfully created governing service
Normal Successful 2m Redis Operator Successfully created Service
Normal Successful 2m Redis Operator Successfully created appbinding
$ kubectl get statefulset -n demo
NAME READY AGE
redis-quickstart 1/1 1m
$ kubectl get pvc -n demo
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
data-redis-quickstart-0 Bound pvc-6e457226-c53f-11e8-9ba7-0800274bef12 1Gi RWO standard 2m
$ kubectl get pv -n demo
NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE
pvc-6e457226-c53f-11e8-9ba7-0800274bef12 1Gi RWO Delete Bound demo/data-redis-quickstart-0 standard 2m
$ kubectl get service -n demo
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
redis-quickstart-pods ClusterIP None <none> <none> 2m
redis-quickstart ClusterIP 10.108.149.205 <none> 6379/TCP 2m
KubeDB operator sets the status.phase
to Running
once the database is successfully created. Run the following command to see the modified Redis object:
$ kubectl get rd -n demo redis-quickstart -o yaml
apiVersion: kubedb.com/v1alpha2
kind: Redis
metadata:
creationTimestamp: "2022-05-31T04:31:38Z"
finalizers:
- kubedb.com
generation: 2
name: redis-quickstart
namespace: demo
resourceVersion: "63624"
uid: 7ffc9d73-94df-4475-9656-a382f380c293
spec:
allowedSchemas:
namespaces:
from: Same
authSecret:
name: redis-quickstart-auth
coordinator:
resources: {}
mode: Standalone
podTemplate:
controller: {}
metadata: {}
spec:
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- podAffinityTerm:
labelSelector:
matchLabels:
app.kubernetes.io/instance: redis-quickstart
app.kubernetes.io/managed-by: kubedb.com
app.kubernetes.io/name: redises.kubedb.com
namespaces:
- demo
topologyKey: kubernetes.io/hostname
weight: 100
- podAffinityTerm:
labelSelector:
matchLabels:
app.kubernetes.io/instance: redis-quickstart
app.kubernetes.io/managed-by: kubedb.com
app.kubernetes.io/name: redises.kubedb.com
namespaces:
- demo
topologyKey: failure-domain.beta.kubernetes.io/zone
weight: 50
resources:
limits:
memory: 1Gi
requests:
cpu: 500m
memory: 1Gi
serviceAccountName: redis-quickstart
replicas: 1
storage:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
storageClassName: standard
storageType: Durable
terminationPolicy: Delete
version: 6.2.5
status:
conditions:
- lastTransitionTime: "2022-05-31T04:31:38Z"
message: 'The KubeDB operator has started the provisioning of Redis: demo/redis-quickstart'
reason: DatabaseProvisioningStartedSuccessfully
status: "True"
type: ProvisioningStarted
- lastTransitionTime: "2022-05-31T04:31:43Z"
message: All desired replicas are ready.
reason: AllReplicasReady
status: "True"
type: ReplicaReady
- lastTransitionTime: "2022-05-31T04:31:48Z"
message: 'The Redis: demo/redis-quickstart is accepting rdClient requests.'
observedGeneration: 2
reason: DatabaseAcceptingConnectionRequest
status: "True"
type: AcceptingConnection
- lastTransitionTime: "2022-05-31T04:31:48Z"
message: 'The Redis: demo/redis-quickstart is ready.'
observedGeneration: 2
reason: ReadinessCheckSucceeded
status: "True"
type: Ready
- lastTransitionTime: "2022-05-31T04:31:48Z"
message: 'The Redis: demo/redis-quickstart is successfully provisioned.'
observedGeneration: 2
reason: DatabaseSuccessfullyProvisioned
status: "True"
type: Provisioned
observedGeneration: 2
phase: Ready
Now, you can connect to this database through redis-cli. In this tutorial, we are connecting to the Redis server from inside of pod.
$ kubectl exec -it -n demo redis-quickstart-0 -- sh
/data > redis-cli
127.0.0.1:6379> ping
PONG
#save data
127.0.0.1:6379> SET mykey "Hello"
OK
# view data
127.0.0.1:6379> GET mykey
"Hello"
127.0.0.1:6379> exit
/data > exit
DoNotTerminate Property
When terminationPolicy
is DoNotTerminate
, KubeDB takes advantage of ValidationWebhook
feature in Kubernetes 1.9.0 or later clusters to implement DoNotTerminate
feature. If admission webhook is enabled, It prevents users from deleting the database as long as the spec.terminationPolicy
is set to DoNotTerminate
. You can see this below:
$ kubectl delete rd redis-quickstart -n demo
Error from server (BadRequest): admission webhook "redis.validators.kubedb.com" denied the request: redis "redis-quickstart" can't be halted. To delete, change spec.terminationPolicy
Now, run kubectl edit rd redis-quickstart -n demo
to set spec.terminationPolicy
to Halt
. Then you will be able to delete/halt the database.
Learn details of all TerminationPolicy
here
Halt Database
When TerminationPolicy is set to halt, and you delete the redis object, the KubeDB operator will delete the StatefulSet and its pods but leaves the PVCs, secrets and database backup (snapshots) intact. Learn details of all TerminationPolicy
here.
You can also keep the redis object and halt the database to resume it again later. If you halt the database, the KubeDB operator will delete the statefulsets and services but will keep the redis object, pvcs, secrets and backup (snapshots).
To halt the database, first you have to set the terminationPolicy to Halt
in existing database. You can use the below command to set the terminationPolicy to Halt
, if it is not already set.
$ kubectl patch -n demo rd/redis-quickstart -p '{"spec":{"terminationPolicy":"Halt"}}' --type="merge"
redis.kubedb.com/redis-quickstart patched
Then, you have to set the spec.halted
as true to set the database in a Halted
state. You can use the below command.
$ kubectl patch -n demo rd/redis-quickstart -p '{"spec":{"halted":true}}' --type="merge"
redis.kubedb.com/redis-quickstart patched
After that, kubedb will delete the statefulsets and services, and you can see the database Phase as Halted
.
Now, you can run the following command to get all redis resources in demo namespaces,
$ kubectl get redis,secret,pvc -n demo
NAME VERSION STATUS AGE
redis.kubedb.com/redis-quickstart 6.2.5 Halted 5m26s
NAME TYPE DATA AGE
secret/default-token-rs764 kubernetes.io/service-account-token 3 6h54m
secret/redis-quickstart-auth kubernetes.io/basic-auth 2 5m26s
secret/redis-quickstart-config Opaque 1 5m26s
secret/root-secret kubernetes.io/tls 3 6h19m
secret/sh.helm.release.v1.vault.v1 helm.sh/release.v1 1 176m
secret/vault-client-certs kubernetes.io/tls 3 22s
secret/vault-server-certs kubernetes.io/tls 3 22s
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
persistentvolumeclaim/data-redis-quickstart-0 Bound pvc-ee1c2fd3-4c0e-4dad-812b-8f83e20284f8 1Gi RWO standard 5m24s
Resume Halted Redis
Now, to resume the database, i.e. to get the same database setup back again, you have to set the spec.halted
as false. You can use the below command.
$ kubectl patch -n demo rd/redis-quickstart -p '{"spec":{"halted":false}}' --type="merge"
redis.kubedb.com/redis-quickstart patched
When the database is resumed successfully, you can see the database Status is set to Ready
.
$ kubectl get rd -n demo
NAME VERSION STATUS AGE
redis-quickstart 6.2.5 Ready 7m52s
Now, If you again exec into the pod
and look for previous data, you will see that, all the data persists.
$ kubectl exec -it -n demo redis-quickstart-0 -- sh
/data > redis-cli
127.0.0.1:6379> ping
PONG
# view data
127.0.0.1:6379> GET mykey
"Hello"
127.0.0.1:6379> exit
/data > exit
Cleaning up
To clean up the Kubernetes resources created by this tutorial, run:
$ kubectl patch -n demo rd/redis-quickstart -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge"
redis.kubedb.com/redis-quickstart patched
$ kubectl delete -n demo rd/redis-quickstart
redis.kubedb.com "redis-quickstart" deleted
$ kubectl delete ns demo
namespace "demo" deleted
Tips for Testing
If you are just testing some basic functionalities, you might want to avoid additional hassles due to some safety features that are great for production environment. You can follow these tips to avoid them.
- Use
storageType: Ephemeral
. Databases are precious. You might not want to lose your data in your production environment if database pod fail. So, we recommend to usespec.storageType: Durable
and provide storage spec inspec.storage
section. For testing purpose, you can just usespec.storageType: Ephemeral
. KubeDB will use emptyDir for storage. You will not require to providespec.storage
section. - Use
terminationPolicy: WipeOut
. It is nice to be able to resume database from previous one.So, we preserve all yourPVCs
, authSecrets
. If you don’t want to resume database, you can just usespec.terminationPolicy: WipeOut
. It will delete everything created by KubeDB for a particular Redis crd when you delete the crd. For more details about termination policy, please visit here.
Next Steps
- Monitor your Redis server with KubeDB using out-of-the-box Prometheus operator.
- Monitor your Redis server with KubeDB using out-of-the-box builtin-Prometheus.
- Use private Docker registry to deploy Redis with KubeDB.
- Detail concepts of Redis object.
- Detail concepts of RedisVersion object.
- Want to hack on KubeDB? Check our contribution guidelines.