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 tutorial will show you how to use KubeDB to run a Elasticsearch database.
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.
To keep things isolated, this tutorial uses a separate namespace called demo
throughout this tutorial.
$ kubectl create ns demo
namespace "demo" created
$ kubectl get ns demo
NAME STATUS AGE
demo Active 5s
Note: Yaml files used in this tutorial are stored in docs/examples/elasticsearch folder in github repository kubedb/cli.
KubeDB implements a Elasticsearch CRD to define the specification of a Elasticsearch database.
Below is the Elasticsearch object created in this tutorial.
apiVersion: kubedb.com/v1alpha1
kind: Elasticsearch
metadata:
name: quick-elasticsearch
namespace: demo
spec:
version: 5.6
doNotPause: true
storage:
storageClassName: "standard"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 50Mi
Here,
spec.version
is the version of Elasticsearch database. In this tutorial, a Elasticsearch 5.6 database is created.
spec.doNotPause
prevents user from deleting this object if admission webhook is enabled.
spec.storage
specifies the StorageClass of PVC 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.
If no storage spec is given, an emptyDir
is used.
Create example above with following command
$ kubedb create -f https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/docs/examples/elasticsearch/quickstart/quick-elasticsearch.yaml
validating "https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/docs/examples/elasticsearch/quickstart/quick-elasticsearch.yaml"
elasticsearch "quick-elasticsearch" created
KubeDB operator watches for Elasticsearch objects using Kubernetes api. When an Elasticsearch object is created, KubeDB operator creates a new StatefulSet and two ClusterIP Service with the matching name.
KubeDB operator will also create a governing service for StatefulSet with the name kubedb
, if one is not already present.
KubeDB operator sets the status.phase
to Running
once the database is successfully created.
$ kubedb get es -n demo quick-elasticsearch -o wide
NAME VERSION STATUS AGE
quick-elasticsearch 5.6 Running 33m
Lets describe Elasticsearch object quick-elasticsearch
$ kubedb describe es -n demo quick-elasticsearch
Name: quick-elasticsearch
Namespace: demo
CreationTimestamp: Mon, 19 Feb 2018 16:10:45 +0600
Status: Running
Volume:
StorageClass: standard
Capacity: 50Mi
Access Modes: RWO
StatefulSet:
Name: quick-elasticsearch
Replicas: 1 current / 1 desired
CreationTimestamp: Mon, 19 Feb 2018 16:10:55 +0600
Pods Status: 1 Running / 0 Waiting / 0 Succeeded / 0 Failed
Service:
Name: quick-elasticsearch
Type: ClusterIP
IP: 10.11.255.214
Port: http 9200/TCP
Service:
Name: quick-elasticsearch-master
Type: ClusterIP
IP: 10.11.255.170
Port: transport 9300/TCP
Certificate Secret:
Name: quick-elasticsearch-cert
Type: Opaque
Data
====
key_pass: 6 bytes
node.jks: 3013 bytes
root.jks: 864 bytes
sgadmin.jks: 3009 bytes
Database Secret:
Name: quick-elasticsearch-auth
Type: Opaque
Data
====
ADMIN_PASSWORD: 8 bytes
READALL_PASSWORD: 8 bytes
sg_action_groups.yml: 430 bytes
sg_config.yml: 240 bytes
sg_internal_users.yml: 156 bytes
sg_roles.yml: 312 bytes
sg_roles_mapping.yml: 73 bytes
Topology:
Type Pod StartTime Phase
---- --- --------- -----
master|client|data quick-elasticsearch-0 2018-02-19 16:11:02 +0600 +06 Running
No Snapshots.
Events:
FirstSeen LastSeen Count From Type Reason Message
--------- -------- ----- ---- -------- ------ -------
10s 10s 1 Elasticsearch operator Normal Successful Successfully patched Elasticsearch
40s 40s 1 Elasticsearch operator Normal Successful Successfully patched StatefulSet
48s 48s 1 Elasticsearch operator Normal Successful Successfully created Elasticsearch
1m 1m 1 Elasticsearch operator Normal Successful Successfully created StatefulSet
1m 1m 1 Elasticsearch operator Normal Successful Successfully created Service
1m 1m 1 Elasticsearch operator Normal Successful Successfully created Service
$ kubectl get service -n demo --selector=kubedb.com/kind=Elasticsearch,kubedb.com/name=quick-elasticsearch
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
quick-elasticsearch ClusterIP 10.97.171.52 <none> 9200/TCP 22m
quick-elasticsearch-master ClusterIP 10.105.209.152 <none> 9300/TCP 22m
Two services for each Elasticsearch object.
Service quick-elasticsearch
targets all Pods which are acting as client node
Service quick-elasticsearch-master
targets all Pods which are acting as master node
KubeDB supports Elasticsearch clustering where Pod can be any of these three role: master, data or client.
If you see Topology
section in kubedb describe
result, you will know role(s) of each Pod.
Topology:
Type Pod StartTime Phase
---- --- --------- -----
data|master|client quick-elasticsearch-0 2018-02-12 11:56:47 +0600 +06 Running
Here, we create a Elasticsearch database with single node. This single node will act as master, data and client.
To learn how to configure Elasticsearch cluster, click here.
Please note that KubeDB operator has created two new Secrets for Elasticsearch object.
quick-elasticsearch-auth
for storing the passwords and search-guard configuration.quick-elasticsearch-cert
for storing certificates used for SSL connection.$ kubectl get secret -n demo quick-elasticsearch-auth -o yaml
apiVersion: v1
data:
ADMIN_PASSWORD: MmJpaGQ1NGc=
READALL_PASSWORD: YTJkcDZjamc=
sg_action_groups.yml: ClVOTElNSVRFRDoKICAtICIqIgoKUk...AiaW5kaWNlczphZG1pbi9nZXQiCg==
sg_config.yml: CnNlYXJjaGd1YXJkOgogIGR5bmFtaW...AgICAgICAgICB0eXBlOiBpbnRlcm4K
sg_internal_users.yml: CmFkbWluOgogIGhhc2g6ICQyYSQxMC...JEdkxVSzZrUE1xT1hJVTZYbnN0OWEK
sg_roles.yml: CnNnX2FsbF9hY2Nlc3M6CiAgY2x1c3...5ESUNFU19LVUJFREJfU05BUFNIT1QK
sg_roles_mapping.yml: CnNnX2FsbF9hY2Nlc3M6CiAgdXNlcn...VzZXJzOgogICAgLSByZWFkYWxsCg==
kind: Secret
metadata:
creationTimestamp: 2018-02-14T08:24:05Z
labels:
kubedb.com/kind: Elasticsearch
kubedb.com/name: quick-elasticsearch
name: quick-elasticsearch-auth
namespace: demo
resourceVersion: "4376"
selfLink: /api/v1/namespaces/demo/secrets/quick-elasticsearch-auth
uid: 6baf55bd-1160-11e8-a344-08002716e6a0
type: Opaque
Note: Auth Secret name format:
{elasticsearch-name}-auth
This Secret contains:
ADMIN_PASSWORD
password for admin
user used in search-guard configuration as internal user.READALL_PASSWORD
password for readall
user with read-only permission only.sg_action_groups.yml
sg_config.yml
sg_internal_users.yml
sg_roles.yml
sg_roles_mapping.yml
See details about search-guard configuration
$ kubectl get secret -n demo quick-elasticsearch-cert -o yaml
apiVersion: v1
data:
key_pass: b2xxeHN1
node.jks: /u3+7QAAAAIAAAABAAAA...A0+i8Kj9XQUo1V/Qg==
root.jks: /u3+7QAAAAIAAAABAAAA...tBkRsCa+uTUYjiatf7j
sgadmin.jks: /u3+7QAAAAIAAAABAAAA...e5h2S9Y3e429E/9P1qw
kind: Secret
metadata:
creationTimestamp: 2018-02-19T10:10:53Z
labels:
kubedb.com/kind: Elasticsearch
kubedb.com/name: quick-elasticsearch
name: quick-elasticsearch-cert
namespace: demo
resourceVersion: "1778"
selfLink: /api/v1/namespaces/demo/secrets/quick-elasticsearch-cert
uid: 2b5abae5-155d-11e8-a001-42010a8000d5
type: Opaque
Note: Cert Secret name format:
{elasticsearch-name}-cert
This Secret contains SSL certificates. See details about SSL certificates needed for Elasticsearch.
In this tutorial, we will expose ClusterIP Service quick-elasticsearch
to connect database from local.
$ kubectl expose svc -n demo quick-elasticsearch --name=quick-es-exposed --port=9200 --protocol=TCP --type=NodePort
service "quick-es-exposed" exposed
$ kubectl get svc -n demo quick-es-exposed
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
quick-es-exposed NodePort 10.110.247.179 <none> 9200:32403/TCP 1m
Following will provide URL for quick-es-exposed
Service to access Elasticsearch database.
$ minikube service quick-es-exposed -n demo --url
http://192.168.99.100:32403
Now, you can connect to this database using curl.
Connection information:
$ minikube service quick-es-exposed -n demo --url
Run following command to get admin
user password
$ kubectl get secrets -n demo quick-elasticsearch-auth -o jsonpath='{.data.\ADMIN_PASSWORD}' | base64 -d
ud7cagcu⏎
Check health of the elasticsearch database
export es_service=$(minikube service quick-es-exposed -n demo --url)
export es_admin_pass=$(kubectl get secrets -n demo quick-elasticsearch-auth -o jsonpath='{.data.\ADMIN_PASSWORD}' | base64 -d)
curl --user "admin:$es_admin_pass" "$es_service/_cluster/health?pretty"
{
"cluster_name" : "quick-elasticsearch",
"status" : "green",
"timed_out" : false,
"number_of_nodes" : 1,
"number_of_data_nodes" : 1,
"active_primary_shards" : 1,
"active_shards" : 1,
"relocating_shards" : 0,
"initializing_shards" : 0,
"unassigned_shards" : 0,
"delayed_unassigned_shards" : 0,
"number_of_pending_tasks" : 0,
"number_of_in_flight_fetch" : 0,
"task_max_waiting_in_queue_millis" : 0,
"active_shards_percent_as_number" : 100.0
}
KubeDB takes advantage of ValidationWebhook
feature in Kubernetes 1.9.0 or later clusters to implement doNotPause
feature. If admission webhook is enabled,
It prevents user from deleting the database as long as the spec.doNotPause
is set true
.
In this tutorial, Elasticsearch quick-elasticsearch
is created with spec.doNotPause: true
. So, if you delete this Elasticsearch object,
admission webhook will nullify the delete operation.
$ kubedb delete es -n demo quick-elasticsearch
error: Elasticsearch "quick-elasticsearch " can't be paused. To continue delete, unset spec.doNotPause and retry.
To continue with this tutorial, unset spec.doNotPause
by updating Elasticsearch object
$ kubedb edit es -n demo quick-elasticsearch
spec:
doNotPause: false
Now, if you delete the Elasticsearch object, KubeDB operator will create a matching DormantDatabase object. KubeDB operator watches for DormantDatabase objects and it will take necessary steps when a DormantDatabase object is created.
KubeDB operator will delete the StatefulSet and its Pods, but leaves the Secret, PVCs unchanged.
$ kubedb delete es -n demo quick-elasticsearch
elasticsearch "quick-elasticsearch" deleted
Check DormantDatabase entry
$ kubedb get drmn -n demo quick-elasticsearch
NAME STATUS AGE
quick-elasticsearch Paused 1m
In KubeDB parlance, we say that Elasticsearch quick-elasticsearch
has entered into dormant state.
Lets see, what we have in this DormantDatabase object
$ kubedb get drmn -n demo quick-elasticsearch -o yaml
apiVersion: kubedb.com/v1alpha1
kind: DormantDatabase
metadata:
clusterName: ""
creationTimestamp: 2018-02-13T05:41:49Z
finalizers:
- kubedb.com
generation: 0
labels:
kubedb.com/kind: Elasticsearch
name: quick-elasticsearch
namespace: demo
resourceVersion: "2072"
selfLink: /apis/kubedb.com/v1alpha1/namespaces/demo/dormantdatabases/quick-elasticsearch
uid: 9624f877-1080-11e8-9e42-0800271bdbb6
spec:
origin:
metadata:
creationTimestamp: null
name: quick-elasticsearch
namespace: demo
spec:
elasticsearch:
certificateSecret:
secretName: quick-elasticsearch-cert
databaseSecret:
secretName: quick-elasticsearch-auth
resources: {}
storage:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 50Mi
storageClassName: standard
version: "5.6"
status:
creationTime: 2018-02-13T05:41:49Z
pausingTime: 2018-02-13T05:42:12Z
phase: Paused
Here,
spec.origin
contains original Elasticsearch object.
status.phase
points to the current database state Paused
.
To resume the database from the dormant state, set spec.resume
to true
in the DormantDatabase object.
$ kubedb edit drmn -n demo quick-elasticsearch
spec:
resume: true
KubeDB operator will notice that spec.resume
is set to true
. It will delete the DormantDatabase object and create a new Elasticsearch using spec.origin
from DormantDatabase.
This will in turn start a new StatefulSet which will mount the originally created Persistent Volume Claim. Thus the original database is resumed.
Please note that the dormant database can also be resumed by creating same Elasticsearch object with same Spec.
In this tutorial, the DormantDatabase quick-elasticsearch
can be resumed by creating original Elasticsearch object.
The below command will resume the DormantDatabase quick-elasticsearch
$ kubedb create -f https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/docs/examples/elasticsearch/quickstart/quick-elasticsearch.yaml
validating "https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/docs/examples/elasticsearch/quickstart/quick-elasticsearch.yaml"
elasticsearch "quick-elasticsearch" created
You can also wipe out a DormantDatabase by setting spec.wipeOut
to true
.
KubeDB operator will delete the PVC(if available), delete any relevant Snapshot for this Elasticsearch and also delete snapshot data stored in the Cloud Storage buckets.
There is no way to resume a wiped out database. So, be sure before you wipe out a database.
$ kubedb edit drmn -n demo quick-elasticsearch
spec:
wipeOut: true
When database is completely wiped out, you will see status WipedOut
$ kubedb get drmn -n demo quick-elasticsearch
NAME STATUS AGE
quick-elasticsearch WipedOut 1m
You still have a record that there was a Elasticsearch object quick-elasticsearch
in the form of a DormantDatabase quick-elasticsearch
.
Since you have already wiped out the database, you can delete the DormantDatabase object.
$ kubedb delete drmn -n demo quick-elasticsearch
dormantdatabase "quick-elasticsearch" deleted
To cleanup the Kubernetes resources created by this tutorial, run:
$ kubedb delete es,drmn,snap -n demo --all --force
$ kubectl delete ns demo
out-of-the-box
builtin-Prometheus.out-of-the-box
CoreOS Prometheus Operator.