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.
This is an Enterprise-only feature. Please install KubeDB Enterprise Edition to try this feature.
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 pgbouncer CRD object in default namespace by default. Following command will create a PgBouncer object as specified in pgbouncer.yaml.
$ kubectl create -f pgbouncer-demo.yaml
pgbouncer "pgbouncer-demo" created
You can provide namespace as a flag --namespace. Provided namespace should match with namespace specified in input file.
$ kubectl create -f pgbouncer-demo.yaml --namespace=kube-system
pgbouncer "pgbouncer-demo" created
kubectl create command also considers stdin as input.
cat pgbouncer-demo.yaml | kubectl create -f -
How to List Objects
kubectl get command allows users to list or find any KubeDB object. To list all PgBouncer objects in default namespace, run the following command:
$ kubectl get pgbouncer
NAME VERSION STATUS AGE
pgbouncer-demo 1.17.0 Running 13m
pgbouncer-dev 1.17.0 Running 11m
pgbouncer-prod 1.17.0 Running 11m
pgbouncer-qa 1.17.0 Running 10m
To get YAML of an object, use --output=yaml flag.
$ kubectl get pgbouncer pgbouncer-demo --output=yaml
apiVersion: kubedb.com/v1alpha2
kind: PgBouncer
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"kubedb.com/v1alpha2","kind":"PgBouncer","metadata":{"annotations":{},"name":"pgbouncer-demo","namespace":"demo"},"spec":{"connectionPool":{"adminUsers":["admin","admin1"],"maxClientConnections":20,"reservePoolSize":5},"databases":[{"alias":"postgres","databaseName":"postgres","databaseRef":{"name":"quick-postgres"}},{"alias":"tmpdb","databaseName":"mydb","databaseRef":{"name":"quick-postgres"}}],"monitor":{"agent":"prometheus.io/builtin"},"replicas":1,"userListSecretRef":{"name":"db-user-pass"},"version":"1.17.0"}}
creationTimestamp: "2019-10-31T10:34:04Z"
finalizers:
- kubedb.com
generation: 1
name: pgbouncer-demo
namespace: demo
resourceVersion: "4733"
selfLink: /apis/kubedb.com/v1alpha2/namespaces/demo/pgbouncers/pgbouncer-demo
uid: 158b7c58-ecb2-4a77-bceb-081489b4921a
spec:
connectionPool:
adminUsers:
- admin
- admin1
poolMode: session
port: 5432
reservePoolSize: 5
databases:
- alias: postgres
databaseName: postgres
databaseRef:
name: quick-postgres
nnamespace: demo
- alias: tmpdb
databaseName: mydb
databaseRef:
name: quick-postgres
namespace: demo
monitor:
agent: prometheus.io/builtin
prometheus:
exporter:
port: 56790
resources: {}
podTemplate:
controller: {}
metadata: {}
spec:
resources: {}
replicas: 1
userListSecretRef:
name: db-user-pass
version: 1.17.0
status:
observedGeneration: 1$6208915667192219204
phase: Running
To get JSON of an object, use --output=json flag.
kubectl get pgbouncer pgbouncer-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/pgbouncer-demo-0 2/2 Running 0 5m53s 10.244.1.3 kind-worker <none> <none>
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
service/kubedb ClusterIP None <none> <none> 5m54s <none>
service/pgbouncer-demo ClusterIP 10.98.95.4 <none> 5432/TCP 5m54s app.kubernetes.io/name=pgbouncers.kubedb.com,app.kubernetes.io/instance=pgbouncer-demo
service/pgbouncer-demo-stats ClusterIP 10.107.214.97 <none> 56790/TCP 5m38s app.kubernetes.io/name=pgbouncers.kubedb.com,app.kubernetes.io/instance=pgbouncer-demo
NAME READY AGE CONTAINERS IMAGES
statefulset.apps/pgbouncer-demo 1/1 5m53s pgbouncer,exporter kubedb/pgbouncer:1.17.0,kubedb/pgbouncer_exporter:v0.1.1
NAME VERSION STATUS AGE
pgbouncer.kubedb.com/pgbouncer-demo 1.17.0 Running 5m54s
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:
- Postgres:
pg - PgBouncer:
pb - Snapshot:
snap - DormantDatabase:
drmn
You can print labels with objects. The following command will list all Snapshots with their corresponding labels.
$ kubectl get pb -n demo --show-labels
NAME DATABASE STATUS AGE LABELS
pgbouncer-demo pb/pgbouncer-demo Succeeded 11m app.kubernetes.io/name=pgbouncers.kubedb.com,app.kubernetes.io/instance=pgbouncer-demo
pgbouncer-tmp pb/postgres-demo Succeeded 1h app.kubernetes.io/name=pgbouncers.kubedb.com,app.kubernetes.io/instance=pgbouncer-tmp
You can also filter list using --selector flag.
$ kubectl get pb --selector='app.kubernetes.io/name=pgbouncers.kubedb.com' --show-labels
NAME DATABASE STATUS AGE LABELS
pgbouncer-demo pb/pgbouncer-demo Succeeded 11m app.kubernetes.io/name=pgbouncers.kubedb.com,app.kubernetes.io/instance=pgbouncer-demo
pgbouncer-dev pb/postgres-demo Succeeded 1h app.kubernetes.io/name=pgbouncers.kubedb.com,app.kubernetes.io/instance=pgbouncer-dev
To print only object name, run the following command:
$ kubectl get all -n demo -o name
pod/pgbouncer-demo-0
service/kubedb
service/pgbouncer-demo
service/pgbouncer-demo-stats
statefulset.apps/pgbouncer-demo
pgbouncer.kubedb.com/pgbouncer-demo
How to Describe Objects
kubectl dba describe command allows users to describe any KubeDB object. The following command will describe PgBouncer pgbouncer-demo with relevant information.
Name: pgbouncer-demo
Namespace: default
API Version: kubedb.com/v1alpha2
Kind: PgBouncer
Metadata:
Creation Timestamp: 2019-09-09T09:27:48Z
Finalizers:
kubedb.com
Generation: 1
Resource Version: 303596
Self Link: /apis/kubedb.com/v1alpha2/namespaces/demo/pgbouncers/pgbouncer-demo
UID: f59c58da-ae21-403d-a4ce-affc8e10345c
Spec:
Connection Pool:
Admin Users:
admin
Listen Address: *
Listen Port: 5432
Max Client Conn: 20
Pool Mode: session
Reserve Pool Size: 5
Databases:
Alias: postgres
App Binding Name: postgres-demo
App Binding Namespace: demo
Database Name: postgres
Replicas: 1
Service Template:
Metadata:
Spec:
User List:
Secret Name: db-userlist
Secret Namespace: demo
Version: 1.17.0
Status:
Observed Generation: 1$6208915667192219204
Phase: Running
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Successful 13m PgBouncer operator Successfully created Service
Normal Successful 13m PgBouncer operator Successfully created PgBouncer configMap
Normal Successful 13m PgBouncer operator Successfully created StatefulSet
Normal Successful 13m PgBouncer operator Successfully created PgBouncer statefulset
Normal Successful 13m PgBouncer operator Successfully patched StatefulSet
Normal Successful 13m PgBouncer operator Successfully patched PgBouncer statefulset
kubectl dba describe command provides following basic information about a database.
- StatefulSet
- Storage (Persistent Volume)
- Service
- Secret (If available)
- Topology (If available)
- Snapshots (If any)
- Monitoring system (If available)
To hide events on KubeDB object, use flag --show-events=false
To describe all PgBouncer objects in default namespace, use following command
kubectl dba describe pb
To describe all PgBouncer objects from every namespace, provide --all-namespaces flag.
kubectl dba describe pb --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 Elasticsearch & PgBouncer objects with specified labels from every namespace.
kubectl dba describe pg,es --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.
Let’s edit an existing running PgBouncer object to setup Monitoring. The following command will open PgBouncer pgbouncer-demo in editor.
$ kubectl edit pb pgbouncer-demo
# Add following to Spec to configure monitoring:
monitor:
agent: prometheus.io/operator
prometheus:
serviceMonitor:
labels:
k8s-app: prometheus
interval: 10s
pgbouncer "pgbouncer-demo" 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
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 PgBouncer pgbouncer-dev in default namespace
$ kubectl delete pgbouncer pgbouncer-dev
pgbouncer "pgbouncer-dev" deleted
You can also use YAML files to delete objects. The following command will delete a PgBouncer using the type and name specified in pgbouncer.yaml.
$ kubectl delete -f pgbouncer.yaml
PgBouncer "pgbouncer-dev" deleted
kubectl delete command also takes input from stdin.
cat pgbouncer.yaml | kubectl delete -f -
To delete objects with matching labels, use --selector flag. The following command will delete PgBouncers with label pgbouncer.app.kubernetes.io/instance=pgbouncer-demo.
kubectl delete pgbouncer -l pgbouncer.app.kubernetes.io/instance=pgbouncer-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 pgbouncer
$ kubectl get pgbouncer.kubedb.com
# Delete objects
$ kubectl delete pgbouncer <name>
Next Steps
- Learn how to use KubeDB to run a PgBouncer here.
- Want to hack on KubeDB? Check our contribution guidelines.