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.

Manage KubeDB objects using CLIs

KubeDB CLI

KubeDB comes with its own cli. It is called kubedb cli. kubedb can be used to manage any KubeDB object. kubedb cli also performs various validations to improve ux. To install KubeDB cli on your workstation, follow the steps here.

How to Create objects

kubectl create creates a database CRD object in default namespace by default. Following command will create a MongoDB object as specified in mongodb.yaml.

$ kubectl create -f mongodb-demo.yaml
mongodb.kubedb.com/mongodb-demo created

You can provide namespace as a flag --namespace. Provided namespace should match with namespace specified in input file.

$ kubectl create -f mongodb-demo.yaml --namespace=kube-system
mongodb.kubedb.com/mongodb-demo

kubectl create command also considers stdin as input.

cat mongodb-demo.yaml | kubectl create -f -

How to List Objects

kubectl get command allows users to list or find any KubeDB object. To list all MongoDB objects in default namespace, run the following command:

$ kubectl get mongodb
NAME           VERSION   STATUS    AGE
mongodb-demo   3.4-v3    Running   13m
mongodb-dev    3.4-v3    Running   11m
mongodb-prod   3.4-v3    Running   11m
mongodb-qa     3.4-v3    Running   10m

To get YAML of an object, use --output=yaml flag.

$ kubectl get mongodb mongodb-demo --output=yaml
apiVersion: kubedb.com/v1alpha2
kind: MongoDB
metadata:
  creationTimestamp: "2019-02-06T10:31:04Z"
  finalizers:
  - kubedb.com
  generation: 2
  name: mongodb-demo
  namespace: default
  resourceVersion: "94703"
  selfLink: /apis/kubedb.com/v1alpha2/namespaces/default/mongodbs/mongodb-demo
  uid: 4eaaba0e-29fa-11e9-aebf-080027875192
spec:
  authSecret:
    name: mongodb-demo-auth
  podTemplate:
    controller: {}
    metadata: {}
    spec:
      livenessProbe:
        exec:
          command:
          - mongo
          - --eval
          - db.adminCommand('ping')
        failureThreshold: 3
        periodSeconds: 10
        successThreshold: 1
        timeoutSeconds: 5
      readinessProbe:
        exec:
          command:
          - mongo
          - --eval
          - db.adminCommand('ping')
        failureThreshold: 3
        periodSeconds: 10
        successThreshold: 1
        timeoutSeconds: 1
      resources: {}
  replicas: 1
  storage:
    accessModes:
    - ReadWriteOnce
    dataSource: null
    resources:
      requests:
        storage: 1Gi
    storageClassName: standard
  storageType: Durable
  terminationPolicy: Halt
  version: 3.4-v3
status:
  observedGeneration: 2$4213139756412538772
  phase: Running

To get JSON of an object, use --output=json flag.

kubectl get mongodb mongodb-demo --output=json

To list all KubeDB objects, use following command:

$ kubectl get kubedb -o wide
NAME                VERSION     STATUS  AGE
mg/mongodb-demo     3.4         Running 3h
mg/mongodb-dev      3.4         Running 3h
mg/mongodb-prod     3.4         Running 3h
mg/mongodb-qa       3.4         Running 3h

NAME                                DATABASE                BUCKET              STATUS      AGE
snap/mongodb-demo-20170605-073557   mg/mongodb-demo         gs:bucket-name      Succeeded   9m
snap/snapshot-20171212-114700       mg/mongodb-demo         gs:bucket-name      Succeeded   1h

Flag --output=wide is used to print additional information.

List command supports short names for each object types. You can use it like kubectl get <short-name>. Below are the short name for KubeDB objects:

  • MongoDB: mg
  • Snapshot: snap
  • DormantDatabase: drmn

You can print labels with objects. The following command will list all Snapshots with their corresponding labels.

$ kubectl get snap --show-labels
NAME                            DATABASE                STATUS      AGE       LABELS
mongodb-demo-20170605-073557    mg/mongodb-demo         Succeeded   11m       app.kubernetes.io/name=mongodbs.kubedb.com,app.kubernetes.io/instance=mongodb-demo
snapshot-20171212-114700        mg/mongodb-demo         Succeeded   1h        app.kubernetes.io/name=mongodbs.kubedb.com,app.kubernetes.io/instance=mongodb-demo

You can also filter list using --selector flag.

$ kubectl get snap --selector='app.kubernetes.io/name=mongodbs.kubedb.com' --show-labels
NAME                            DATABASE           STATUS      AGE       LABELS
mongodb-demo-20171212-073557    mg/mongodb-demo    Succeeded   14m       app.kubernetes.io/name=mongodbs.kubedb.com,app.kubernetes.io/instance=mongodb-demo
snapshot-20171212-114700        mg/mongodb-demo    Succeeded   2h        app.kubernetes.io/name=mongodbs.kubedb.com,app.kubernetes.io/instance=mongodb-demo

To print only object name, run the following command:

$ kubectl get all -o name
mongodb/mongodb-demo
mongodb/mongodb-dev
mongodb/mongodb-prod
mongodb/mongodb-qa
snapshot/mongodb-demo-20170605-073557
snapshot/snapshot-20170505-114700

How to Describe Objects

kubectl dba describe command allows users to describe any KubeDB object. The following command will describe MongoDB database mongodb-demo with relevant information.

$ kubectl dba describe mg mongodb-demo
Name:               mongodb-demo
Namespace:          default
CreationTimestamp:  Wed, 06 Feb 2019 16:31:04 +0600
Labels:             <none>
Annotations:        <none>
Replicas:           1  total
Status:             Running
  StorageType:      Durable
Volume:
  StorageClass:  standard
  Capacity:      1Gi
  Access Modes:  RWO

StatefulSet:
  Name:               mongodb-demo
  CreationTimestamp:  Wed, 06 Feb 2019 16:31:05 +0600
  Labels:               app.kubernetes.io/name=mongodbs.kubedb.com
                        app.kubernetes.io/instance=mongodb-demo
  Annotations:        <none>
  Replicas:           824639727120 desired | 1 total
  Pods Status:        1 Running / 0 Waiting / 0 Succeeded / 0 Failed

Service:
  Name:         mongodb-demo
  Labels:         app.kubernetes.io/name=mongodbs.kubedb.com
                  app.kubernetes.io/instance=mongodb-demo
  Annotations:  <none>
  Type:         ClusterIP
  IP:           10.96.245.200
  Port:         db  27017/TCP
  TargetPort:   db/TCP
  Endpoints:    172.17.0.8:27017

Service:
  Name:         mongodb-demo-gvr
  Labels:         app.kubernetes.io/name=mongodbs.kubedb.com
                  app.kubernetes.io/instance=mongodb-demo
  Annotations:    service.alpha.kubernetes.io/tolerate-unready-endpoints=true
  Type:         ClusterIP
  IP:           None
  Port:         db  27017/TCP
  TargetPort:   27017/TCP
  Endpoints:    172.17.0.8:27017

Database Secret:
  Name:         mongodb-demo-auth
  Labels:         app.kubernetes.io/name=mongodbs.kubedb.com
                  app.kubernetes.io/instance=mongodb-demo
  Annotations:  <none>

Type:  Opaque

Data
====
  password:  16 bytes
  username:  4 bytes

No Snapshots.

Events:
  Type    Reason      Age   From             Message
  ----    ------      ----  ----             -------
  Normal  Successful  2m    KubeDB operator  Successfully created Service
  Normal  Successful  2m    KubeDB operator  Successfully created StatefulSet
  Normal  Successful  2m    KubeDB operator  Successfully created MongoDB
  Normal  Successful  2m    KubeDB operator  Successfully created appbinding
  Normal  Successful  2m    KubeDB operator  Successfully patched StatefulSet
  Normal  Successful  2m    KubeDB operator  Successfully patched MongoDB

kubectl dba describe command provides following basic information about a MongoDB database.

  • StatefulSet
  • Storage (Persistent Volume)
  • Service
  • Secret (If available)
  • Snapshots (If any)
  • Monitoring system (If available)

To hide events on KubeDB object, use flag --show-events=false

To describe all MongoDB objects in default namespace, use following command

kubectl dba describe mg

To describe all MongoDB objects from every namespace, provide --all-namespaces flag.

kubectl dba describe mg --all-namespaces

To describe all KubeDB objects from every namespace, use the following command:

kubectl dba describe all --all-namespaces

You can also describe KubeDb objects with matching labels. The following command will describe all MongoDB objects with specified labels from every namespace.

kubectl dba describe mg --all-namespaces --selector='group=dev'

To learn about various options of describe command, please visit here.

Edit Restrictions

Various fields of a KubeDb object can’t be edited using edit command. The following fields are restricted from updates for all KubeDB objects:

  • apiVersion
  • kind
  • metadata.name
  • metadata.namespace

If StatefulSets exists for a MongoDB database, following fields can’t be modified as well.

  • spec.ReplicaSet
  • spec.authSecret
  • spec.init
  • spec.storageType
  • spec.storage
  • spec.podTemplate.spec.nodeSelector

For DormantDatabase, spec.origin can’t be edited using kubectl edit

How to Delete Objects

kubectl delete command will delete an object in default namespace by default unless namespace is provided. The following command will delete a MongoDB mongodb-dev in default namespace

$ kubectl delete mongodb mongodb-dev
mongodb.kubedb.com "mongodb-dev" deleted

You can also use YAML files to delete objects. The following command will delete a mongodb using the type and name specified in mongodb.yaml.

$ kubectl delete -f mongodb-demo.yaml
mongodb.kubedb.com "mongodb-dev" deleted

kubectl delete command also takes input from stdin.

cat mongodb-demo.yaml | kubectl delete -f -

To delete database with matching labels, use --selector flag. The following command will delete mongodb with label mongodb.app.kubernetes.io/instance=mongodb-demo.

kubectl delete mongodb -l mongodb.app.kubernetes.io/instance=mongodb-demo

Using Kubectl

You can use Kubectl with KubeDB objects like any other CRDs. Below are some common examples of using Kubectl with KubeDB objects.

# Create objects
$ kubectl create -f

# List objects
$ kubectl get mongodb
$ kubectl get mongodb.kubedb.com

# Delete objects
$ kubectl delete mongodb <name>

Next Steps