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.

MongoDB QuickStart

This tutorial will show you how to use KubeDB to run a MongoDB database.

  lifecycle

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 Minikube.

  • 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                AGE
    standard (default)   k8s.io/minikube-hostpath   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 ns demo
    namespace "demo" created
    
    $ kubectl get ns
    NAME          STATUS    AGE
    demo          Active    10s
    

Note: The yaml files used in this tutorial are stored in docs/examples/mongodb folder in GitHub repository kubedb/cli.

Find Available MongoDBVersion

When you have installed KubeDB, it has created MongoDBVersion crd for all supported MongoDB versions. Check 0

$ kubectl get mongodbversions
NAME      VERSION   DB_IMAGE              DEPRECATED   AGE
3.4       3.4       kubedb/mongo:3.4      true         4h
3.4-v1    3.4       kubedb/mongo:3.4-v1                4h
3.6       3.6       kubedb/mongo:3.6      true         4h
3.6-v1    3.6       kubedb/mongo:3.6-v1                4h

Create a MongoDB database

KubeDB implements a MongoDB CRD to define the specification of a MongoDB database. Below is the MongoDB object created in this tutorial.

apiVersion: kubedb.com/v1alpha1
kind: MongoDB
metadata:
  name: mgo-quickstart
  namespace: demo
spec:
  version: "3.4-v1"
  storageType: Durable
  storage:
    storageClassName: "standard"
    accessModes:
    - ReadWriteOnce
    resources:
      requests:
        storage: 50Mi
  terminationPolicy: DoNotTerminate
$ kubedb create -f https://raw.githubusercontent.com/kubedb/cli/0.9.0-rc.2/docs/examples/mongodb/quickstart/demo-1.yaml
mongodb.kubedb.com/mgo-quickstart created

Here,

  • spec.version is name of the MongoDBVersion crd where the docker images are specified. In this tutorial, a MongoDB 3.4-v1 database is created.
  • spec.storageType specifies the type of storage that will be used for MongoDB database. It can be Durable or Ephemeral. Default value of this field is Durable. If Ephemeral is used then KubeDB will create MongoDB database using EmptyDir volume. In this case, you don’t have to specify spec.storage field. This is useful for testing purpose.
  • 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 to nullify(reject) the delete operation of MongoDB crd or which resources KubeDB should keep or delete when you delete MongoDB crd. If admission webhook is enabled, It prevents users from deleting the database as long as the spec.terminationPolicy is set to DoNotTerminate. Learn details of all TerminationPolicy [here]

Note: spec.storage section is used to create PVC for database pod. It will create PVC with storage size specified instorage.resources.requests field. Don’t specify limits here. PVC does not get resized automatically.

KubeDB operator watches for MongoDB objects using Kubernetes api. When a MongoDB object is created, KubeDB operator will create a new StatefulSet and a ClusterIP Service with the matching MongoDB object name. KubeDB operator will also create a governing service for StatefulSets with the name <mongodb-name>-gvr. No MongoDB specific RBAC permission is required in RBAC enabled clusters.

$ kubedb describe mg -n demo mgo-quickstart
Name:               mgo-quickstart
Namespace:          demo
CreationTimestamp:  Mon, 24 Sep 2018 15:20:04 +0600
Labels:             <none>
Annotations:        <none>
Replicas:           1  total
Status:             Running
  StorageType:      Durable
Volume:
  StorageClass:  standard
  Capacity:      50Mi
  Access Modes:  RWO

StatefulSet:
  Name:               mgo-quickstart
  CreationTimestamp:  Mon, 24 Sep 2018 15:20:08 +0600
  Labels:               kubedb.com/kind=MongoDB
                        kubedb.com/name=mgo-quickstart
  Annotations:        <none>
  Replicas:           824640156544 desired | 1 total
  Pods Status:        1 Running / 0 Waiting / 0 Succeeded / 0 Failed

Service:
  Name:         mgo-quickstart
  Labels:         kubedb.com/kind=MongoDB
                  kubedb.com/name=mgo-quickstart
  Annotations:  <none>
  Type:         ClusterIP
  IP:           10.111.19.55
  Port:         db  27017/TCP
  TargetPort:   db/TCP
  Endpoints:    172.17.0.9:27017

Service:
  Name:         mgo-quickstart-gvr
  Labels:         kubedb.com/kind=MongoDB
                  kubedb.com/name=mgo-quickstart
  Annotations:    service.alpha.kubernetes.io/tolerate-unready-endpoints=true
  Type:         ClusterIP
  IP:           None
  Port:         db  27017/TCP
  TargetPort:   27017/TCP
  Endpoints:    172.17.0.9:27017

Database Secret:
  Name:         mgo-quickstart-auth
  Labels:         kubedb.com/kind=MongoDB
                  kubedb.com/name=mgo-quickstart
  Annotations:  <none>
  
Type:  Opaque
  
Data
====
  password:  16 bytes
  user:      4 bytes

No Snapshots.

Events:
  Type    Reason      Age   From              Message
  ----    ------      ----  ----              -------
  Normal  Successful  19m   MongoDB operator  Successfully created Service
  Normal  Successful  16m   MongoDB operator  Successfully created StatefulSet
  Normal  Successful  16m   MongoDB operator  Successfully created MongoDB
  Normal  Successful  16m   MongoDB operator  Successfully patched StatefulSet
  Normal  Successful  16m   MongoDB operator  Successfully patched MongoDB
  Normal  Successful  16m   MongoDB operator  Successfully patched StatefulSet
  Normal  Successful  16m   MongoDB operator  Successfully patched MongoDB


$ kubectl get statefulset -n demo
NAME             DESIRED   CURRENT   AGE
mgo-quickstart   1         1         20m

$ kubectl get pvc -n demo
NAME                       STATUS    VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
datadir-mgo-quickstart-0   Bound     pvc-081fb321-bfdb-11e8-93d2-080027e2cfdd   50Mi       RWO            standard       23m

$ kubectl get pv -n demo
NAME                                       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS    CLAIM                           STORAGECLASS   REASON    AGE
pvc-081fb321-bfdb-11e8-93d2-080027e2cfdd   50Mi       RWO            Delete           Bound     demo/datadir-mgo-quickstart-0   standard                 23m

$ kubectl get service -n demo
NAME                 TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)     AGE
mgo-quickstart       ClusterIP   10.111.19.55   <none>        27017/TCP   24m
mgo-quickstart-gvr   ClusterIP   None           <none>        27017/TCP   24m

KubeDB operator sets the status.phase to Running once the database is successfully created. Run the following command to see the modified MongoDB object:

$ kubedb get mg -n demo mgo-quickstart -o yaml
apiVersion: kubedb.com/v1alpha1
kind: MongoDB
metadata:
  creationTimestamp: 2018-09-24T09:20:04Z
  finalizers:
  - kubedb.com
  generation: 2
  name: mgo-quickstart
  namespace: demo
  resourceVersion: "19607"
  selfLink: /apis/kubedb.com/v1alpha1/namespaces/demo/mongodbs/mgo-quickstart
  uid: 05926090-bfdb-11e8-93d2-080027e2cfdd
spec:
  databaseSecret:
    secretName: mgo-quickstart-auth
  replicas: 1
  storage:
    accessModes:
    - ReadWriteOnce
    resources:
      requests:
        storage: 50Mi
    storageClassName: standard
  storageType: Durable
  terminationPolicy: Pause
  updateStrategy:
    type: RollingUpdate
  version: 3.4-v1
status:
  observedGeneration: 2$4213139756412538772
  phase: Running

Please note that KubeDB operator has created a new Secret called mgo-quickstart-auth (format: {mongodb-object-name}-auth) for storing the password for mongodb superuser. This secret contains a user key which contains the username for MongoDB superuser and a password key which contains the password for MongoDB superuser.

If you want to use custom or existing secret please specify that when creating the MongoDB object using spec.databaseSecret.secretName. While creating this secret manually, make sure the secret contains these two keys containing data user and password. For more details, please see here.

Now, you can connect to this database through mongo-shell. In this tutorial, we are connecting to the MongoDB server from inside the pod.

$ kubectl get secrets -n demo mgo-quickstart-auth -o jsonpath='{.data.\user}' | base64 -d
root

$ kubectl get secrets -n demo mgo-quickstart-auth -o jsonpath='{.data.\password}' | base64 -d
aaqCftpLsaGDLVIo

$ kubectl exec -it mgo-quickstart-0 -n demo sh

> mongo admin

> db.auth("root","aaqCftpLsaGDLVIo")
1

> show dbs
admin  0.000GB
local  0.000GB
mydb   0.000GB

> show users
{
    "_id" : "admin.root",
    "user" : "root",
    "db" : "admin",
    "roles" : [
        {
            "role" : "root",
            "db" : "admin"
        }
    ]
}

> use newdb
switched to db newdb

> db.movie.insert({"name":"batman"});
WriteResult({ "nInserted" : 1 })

> db.movie.find().pretty()
{ "_id" : ObjectId("5a2e435d7ec14e7bda785f16"), "name" : "batman" }

> exit
bye

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:

$ kubedb delete my mgo-quickstart -n demo
Error from server (BadRequest): admission webhook "mongodb.validators.kubedb.com" denied the request: mongodb "mgo-quickstart" can't be paused. To delete, change spec.terminationPolicy

Now, run kubedb edit mg mgo-quickstart -n demo to set spec.terminationPolicy to Resume (which creates domantdatabase when mongodb is deleted and keeps PVC, snapshots, Secrets intact) or remove this field (which default to Resume). Then you will be able to delete/pause the database.

Learn details of all TerminationPolicy here

Pause Database

When TerminationPolicy is set to Pause, it will pause the MongoDB database instead of deleting it. Here, If you delete the MongoDB object, KubeDB operator will delete the StatefulSet and its pods but leaves the PVCs unchanged. In KubeDB parlance, we say that mgo-quickstart MongoDB database has entered into the dormant state. This is represented by KubeDB operator by creating a matching DormantDatabase object.

$ kubedb delete mg mgo-quickstart -n demo
mongodb "mgo-quickstart" deleted

$ kubedb get drmn -n demo mgo-quickstart
NAME             STATUS    AGE
mgo-quickstart   Pausing   39s

$ kubedb get drmn -n demo mgo-quickstart
NAME             STATUS    AGE
mgo-quickstart   Paused    21s
$ kubedb get drmn -n demo mgo-quickstart -o yaml
apiVersion: kubedb.com/v1alpha1
kind: DormantDatabase
metadata:
  creationTimestamp: 2018-09-24T10:13:57Z
  finalizers:
  - kubedb.com
  generation: 1
  labels:
    kubedb.com/kind: MongoDB
  name: mgo-quickstart
  namespace: demo
  resourceVersion: "23326"
  selfLink: /apis/kubedb.com/v1alpha1/namespaces/demo/dormantdatabases/mgo-quickstart
  uid: 8c39ddda-bfe2-11e8-93d2-080027e2cfdd
spec:
  origin:
    metadata:
      creationTimestamp: 2018-09-24T09:20:04Z
      name: mgo-quickstart
      namespace: demo
    spec:
      mongodb:
        databaseSecret:
          secretName: mgo-quickstart-auth
        podTemplate:
          controller: {}
          metadata: {}
          spec:
            resources: {}
        replicas: 1
        serviceTemplate:
          metadata: {}
          spec: {}
        storage:
          accessModes:
          - ReadWriteOnce
          resources:
            requests:
              storage: 50Mi
          storageClassName: standard
        storageType: Durable
        terminationPolicy: Pause
        updateStrategy:
          type: RollingUpdate
        version: 3.4-v1
status:
  observedGeneration: 1$16440556888999634490
  pausingTime: 2018-09-24T10:14:13Z
  phase: Paused

Here,

  • spec.origin is the spec of the original spec of the original MongoDB object.
  • status.phase points to the current database state Paused.

Resume Dormant Database

To resume the database from the dormant state, create same MongoDB object with same Spec.

In this tutorial, the dormant database can be resumed by creating original MongoDB object.

The below command will resume the DormantDatabase mgo-quickstart.

$ kubedb create -f https://raw.githubusercontent.com/kubedb/cli/0.9.0-rc.2/docs/examples/mongodb/quickstart/demo-1.yaml
mongodb.kubedb.com/mgo-quickstart created

Now, if you exec into the database, you can see that the datas are intact.

WipeOut DormantDatabase

You can wipe out a DormantDatabase while deleting the object by setting spec.wipeOut to true. KubeDB operator will delete any relevant resources of this MongoDB database (i.e, PVCs, Secrets, Snapshots). It will also delete snapshot data stored in the Cloud Storage buckets.

$ kubedb edit drmn -n demo mgo-quickstart
apiVersion: kubedb.com/v1alpha1
kind: DormantDatabase
metadata:
  name: mgo-quickstart
  namespace: demo
  ...
spec:
  wipeOut: true
  ...
status:
  phase: Paused
  ...

If spec.wipeOut is not set to true while deleting the dormantdatabase object, then only this object will be deleted and kubedb-operator won’t delete related Secrets, PVCs, and Snapshots. So, users still can access the stored data in the cloud storage buckets as well as PVCs.

Delete DormantDatabase

As it is already discussed above, DormantDatabase can be deleted with or without wiping out the resources. To delete the dormantdatabase,

$ kubectl delete drmn mgo-quickstart -n demo
dormantdatabase "mgo-quickstart" deleted

Cleaning up

To cleanup the Kubernetes resources created by this tutorial, run:

kubectl patch -n demo mg/mgo-quickstart -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge"
kubectl delete -n demo mg/mgo-quickstart

kubectl patch -n demo drmn/mgo-quickstart -p '{"spec":{"wipeOut":true}}' --type="merge"
kubectl delete -n demo drmn/mgo-quickstart

kubectl delete ns demo

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.

  1. 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 use spec.storageType: Durable and provide storage spec in spec.storage section. For testing purpose, you can just use spec.storageType: Ephemeral. KubeDB will use emptyDir for storage. You will not require to provide spec.storage section.
  2. Use terminationPolicy: WipeOut. It is nice to be able to resume database from previous one. So, we create DormantDatabase and preserve all your PVCs, Secrets, Snapshots etc. If you don’t want to resume database, you can just use spec.terminationPolicy: WipeOut. It will not create DormantDatabase and it will delete everything created by KubeDB for a particular MongoDB crd when you delete the crd. For more details about termination policy, please visit here.

Next Steps