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 MySQL object as specified in mysql.yaml.
$ kubectl create -f https://github.com/kubedb/docs/raw/v2023.01.17/docs/guides/mysql/cli/yamls/mysql-demo.yaml
mysql.kubedb.com/mysql-demo created
You can provide namespace as a flag --namespace. Provided namespace should match with namespace specified in input file.
$ kubectl create -f https://github.com/kubedb/docs/raw/v2023.01.17/docs/guides/mysql/cli/yamls/mysql-demo.yaml --namespace=kube-system
mysql.kubedb.com/mysql-demo created
kubectl create command also considers stdin as input.
cat mysql-demo.yaml | kubectl create -f -
How to List Objects
kubectl get command allows users to list or find any KubeDB object. To list all MySQL objects in default namespace, run the following command:
$ kubectl get mysql
NAME VERSION STATUS AGE
mysql-demo 8.0.27 Running 5m1s
mysql-dev 5.7.36 Running 10m1s
To get YAML of an object, use --output=yaml flag.
$ kubectl get mysql mysql-demo -n demo --output=yaml
apiVersion: kubedb.com/v1alpha2
kind: MySQL
metadata:
name: mysql-demo
namespace: demo
spec:
authSecret:
name: mysql-demo-auth
podTemplate:
spec:
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- podAffinityTerm:
labelSelector:
matchLabels:
app.kubernetes.io/instance: mysql-demo
app.kubernetes.io/managed-by: kubedb.com
app.kubernetes.io/name: mysqls.kubedb.com
namespaces:
- demo
topologyKey: kubernetes.io/hostname
weight: 100
- podAffinityTerm:
labelSelector:
matchLabels:
app.kubernetes.io/instance: mysql-demo
app.kubernetes.io/managed-by: kubedb.com
app.kubernetes.io/name: mysqls.kubedb.com
namespaces:
- demo
topologyKey: failure-domain.beta.kubernetes.io/zone
weight: 50
resources:
limits:
cpu: 500m
memory: 1Gi
requests:
cpu: 500m
memory: 1Gi
serviceAccountName: mysql-demo
replicas: 1
storage:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
storageClassName: standard
storageType: Durable
terminationPolicy: Delete
version: 8.0.27
To get JSON of an object, use --output=json flag.
kubectl get mysql mysql-demo --output=json
To list all KubeDB objects, use following command:
$ kubectl get all -n demo -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
pod/mysql-demo-0 1/1 Running 0 2m17s 10.244.0.13 kind-control-plane <none> 1/1
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
service/mysql-demo ClusterIP 10.107.205.135 <none> 3306/TCP 2m17s app.kubernetes.io/instance=mysql-demo,app.kubernetes.io/managed-by=kubedb.com,app.kubernetes.io/name=mysqls.kubedb.com
service/mysql-demo-pods ClusterIP None <none> 3306/TCP 2m17s app.kubernetes.io/instance=mysql-demo,app.kubernetes.io/managed-by=kubedb.com,app.kubernetes.io/name=mysqls.kubedb.com
NAME READY AGE CONTAINERS IMAGES
statefulset.apps/mysql-demo 1/1 2m17s mysql kubedb/mysql:8.0.27
NAME TYPE VERSION AGE
appbinding.appcatalog.appscode.com/mysql-demo kubedb.com/mysql 8.0.27 2m17s
NAME VERSION STATUS AGE
mysql.kubedb.com/mysql-demo 8.0.27 Ready 2m17s
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:
- MySQL:
my
To print only object name, run the following command:
$ kubectl get all -o name
mysql/mysql-demo
mysql/mysql-dev
mysql/mysql-prod
mysql/mysql-qa
How to Describe Objects
kubectl dba describe command allows users to describe any KubeDB object. The following command will describe MySQL database mysql-demo with relevant information.
$ kubectl dba describe my -n demo
Name: mysql-demo
Namespace: demo
CreationTimestamp: Mon, 15 Mar 2021 17:53:48 +0600
Labels: <none>
Annotations: kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"kubedb.com/v1alpha2","kind":"MySQL","metadata":{"annotations":{},"name":"mysql-demo","namespace":"demo"},"spec":{"storage":{"accessModes...
Replicas: 1 total
Status: Ready
StorageType: Durable
Volume:
StorageClass: standard
Capacity: 1Gi
Access Modes: RWO
Paused: false
Halted: false
Termination Policy: Delete
StatefulSet:
Name: mysql-demo
CreationTimestamp: Mon, 15 Mar 2021 17:53:48 +0600
Labels: app.kubernetes.io/component=database
app.kubernetes.io/instance=mysql-demo
app.kubernetes.io/managed-by=kubedb.com
app.kubernetes.io/name=mysqls.kubedb.com
Annotations: <none>
Replicas: 824638230984 desired | 1 total
Pods Status: 1 Running / 0 Waiting / 0 Succeeded / 0 Failed
Service:
Name: mysql-demo
Labels: app.kubernetes.io/component=database
app.kubernetes.io/instance=mysql-demo
app.kubernetes.io/managed-by=kubedb.com
app.kubernetes.io/name=mysqls.kubedb.com
Annotations: <none>
Type: ClusterIP
IP: 10.107.205.135
Port: primary 3306/TCP
TargetPort: db/TCP
Endpoints: 10.244.0.13:3306
Service:
Name: mysql-demo-pods
Labels: app.kubernetes.io/component=database
app.kubernetes.io/instance=mysql-demo
app.kubernetes.io/managed-by=kubedb.com
app.kubernetes.io/name=mysqls.kubedb.com
Annotations: <none>
Type: ClusterIP
IP: None
Port: db 3306/TCP
TargetPort: db/TCP
Endpoints: 10.244.0.13:3306
Auth Secret:
Name: mysql-demo-auth
Labels: app.kubernetes.io/component=database
app.kubernetes.io/instance=mysql-demo
app.kubernetes.io/managed-by=kubedb.com
app.kubernetes.io/name=mysqls.kubedb.com
Annotations: <none>
Type: kubernetes.io/basic-auth
Data:
password: 16 bytes
username: 4 bytes
AppBinding:
Metadata:
Annotations:
kubectl.kubernetes.io/last-applied-configuration: {"apiVersion":"kubedb.com/v1alpha2","kind":"MySQL","metadata":{"annotations":{},"name":"mysql-demo","namespace":"demo"},"spec":{"storage":{"accessModes":["ReadWriteOnce"],"resources":{"requests":{"storage":"1Gi"}},"storageClassName":"standard"},"version":"8.0.27"}}
Creation Timestamp: 2021-03-15T11:53:48Z
Labels:
app.kubernetes.io/component: database
app.kubernetes.io/instance: mysql-demo
app.kubernetes.io/managed-by: kubedb.com
app.kubernetes.io/name: mysqls.kubedb.com
Name: mysql-demo
Namespace: demo
Spec:
Client Config:
Service:
Name: mysql-demo
Path: /
Port: 3306
Scheme: mysql
URL: tcp(mysql-demo:3306)/
Parameters:
API Version: appcatalog.appscode.com/v1alpha1
Kind: StashAddon
Stash:
Addon:
Backup Task:
Name: mysql-backup-8.0.27
Restore Task:
Name: mysql-restore-8.0.27
Secret:
Name: mysql-demo-auth
Type: kubedb.com/mysql
Version: 8.0.27
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Successful 5m KubeDB Operator Successfully created governing service
Normal Successful 5m KubeDB Operator Successfully created service for primary/standalone
Normal Successful 5m KubeDB Operator Successfully created database auth secret
Normal Successful 5m KubeDB Operator Successfully created StatefulSet
kubectl dba describe command provides following basic information about a MySQL database.
- StatefulSet
- Storage (Persistent Volume)
- Service
- Secret (If available)
- Monitoring system (If available)
To hide events on KubeDB object, use flag --show-events=false
To describe all MySQL objects in default namespace, use following command
kubectl dba describe my
To describe all MySQL objects from every namespace, provide --all-namespaces flag.
kubectl dba describe my --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 MySQL objects with specified labels from every namespace.
kubectl dba describe my --all-namespaces --selector='group=dev'
To learn about various options of describe command, please visit here.
How to Edit Objects
kubectl edit command allows users to directly edit any KubeDB object. It will open the editor defined by KUBEDB_EDITOR, or EDITOR environment variables, or fall back to nano.
Lets edit an existing running MySQL object to setup database Halted. The following command will open MySQL mysql-demo in editor.
$ kubectl edit my -n demo mysql-quickstart
spec:
....
authSecret:
name: mysql-quickstart-auth
# add database halted = true to delete StatefulSet services and database other resources
halted: true
....
mysql.kubedb.com/mysql-quickstart edited
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 MySQL database, following fields can’t be modified as well.
- 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 MySQL mysql-dev in default namespace
$ kubectl delete mysql mysql-dev
mysql.kubedb.com "mysql-dev" deleted
You can also use YAML files to delete objects. The following command will delete a mysql using the type and name specified in mysql.yaml.
$ kubectl delete -f mysql-demo.yaml
mysql.kubedb.com "mysql-dev" deleted
kubectl delete command also takes input from stdin.
cat mysql-demo.yaml | kubectl delete -f -
To delete database with matching labels, use --selector flag. The following command will delete mysql with label mysql.app.kubernetes.io/instance=mysql-demo.
kubectl delete mysql -l mysql.app.kubernetes.io/instance=mysql-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 mysql
$ kubectl get mysql.kubedb.com
# Delete objects
$ kubectl delete mysql <name>
Next Steps
- Learn how to use KubeDB to run a MySQL database here.
- Want to hack on KubeDB? Check our contribution guidelines.