Open Source Kubernetes

Introduction

Helm is an open source packaging tool that helps install applications and services on Kubernetes. It uses a packaging format called charts. A Helm chart is a package containing all resource definitions necessary to create an instance of a Kubernetes application, tool, or service in a Kubernetes cluster.

Prerequisites

You must have a Kubernetes cluster that has Helm configured. If you have not installed the Helm client (helm), see Installing Helm.

The Helm chart for YugabyteDB (yugabyte-helm) has been tested with the following software versions:

  • Kubernetes 1.10+
  • Helm 2.8+ or 3.0+
  • YugabyteDB docker image (yugabytedb/yugabyte) 1.1.0+
  • Kubernetes nodes where a total of 12 CPU cores and 45 GB RAM can be allocated to YugabyteDB. This can be three nodes with 4 CPU core and 15 GB RAM allocated to YugabyteDB.
  • For optimal performance, ensure you’ve set the appropriate system limits using ulimit on each node in your Kubernetes cluster.

Confirm that helm is configured correctly.

  1. $ helm version

Output for Helm 2:

  1. Client: &version.Version{SemVer:"v2.10.0", GitCommit:"...", GitTreeState:"clean"}
  2. Server: &version.Version{SemVer:"v2.10.0", GitCommit:"...", GitTreeState:"clean"}

Output for Helm 3:

  1. version.BuildInfo{Version:"v3.0.3", GitCommit:"ac925eb7279f4a6955df663a0128044a8a6b7593", GitTreeState:"clean", GoVersion:"go1.13.6"}

Create cluster

For Helm 3, jump directly to Add charts repository section.

Create service account (Helm 2 only)

Before you can create the cluster, you need to have a service account that has been granted the cluster-admin role. Use the following command to create a yugabyte-helm service account granted with the ClusterRole of cluster-admin.

  1. $ kubectl create -f https://raw.githubusercontent.com/yugabyte/charts/master/stable/yugabyte/yugabyte-rbac.yaml
  1. serviceaccount/yugabyte-helm created
  2. clusterrolebinding.rbac.authorization.k8s.io/yugabyte-helm created

Initialize Helm (Helm 2 only)

Initialize helm with the service account, but use the —upgrade option to ensure that you can upgrade any previous initializations you may have made.

  1. $ helm init --service-account yugabyte-helm --upgrade --wait
  1. $HELM_HOME has been configured at `/Users/<user>/.helm`.
  3. Tiller (the Helm server-side component) has been upgraded to the current version.
  4. Happy Helming!

Add charts repository

To add the YugabyteDB charts repository, run the following command.

  1. $ helm repo add yugabytedb https://charts.yugabyte.com

Fetch updates from the repository

Make sure that you have the latest updates to the repository by running the following command.

  1. $ helm repo update

Validate the chart version

For Helm 2:

  1. $ helm search yugabytedb/yugabyte

For Helm 3:

  1. $ helm search repo yugabytedb/yugabyte

Output:

  1. NAME                CHART VERSION APP VERSION   DESCRIPTION                                       
  2. yugabytedb/yugabyte 2.0.12        2.0.12.0-b10  YugabyteDB is the high-performance distr...

Install YugabyteDB

Install YugabyteDB in the Kubernetes cluster using the commands below.

On multi-node Kubernetes

For Helm 2:

  1. $ helm install yugabytedb/yugabyte --namespace yb-demo --name yb-demo --wait

For Helm 3:

For Helm 3, you have to first create a namespace.

  1. $ kubectl create namespace yb-demo
  2. $ helm install yb-demo yugabytedb/yugabyte --namespace yb-demo --wait

On Minikube

If you are running in a resource-constrained environment or a local environment, such as Minikube, you will have to change the default resource requirements by using the command below. See next section for a detailed description of these resource requirements.

For Helm 2:

  1. $ helm install yugabytedb/yugabyte \
  2. --set resource.master.requests.cpu=0.5,resource.master.requests.memory=0.5Gi,\
  3. resource.tserver.requests.cpu=0.5,resource.tserver.requests.memory=0.5Gi --namespace yb_demo --name yb-demo

For Helm 3:

For Helm 3, you have to first create a namespace.

  1. $ kubectl create namespace yb-demo
  2. $ helm install yb-demo yugabytedb/yugabyte \
  3. --set resource.master.requests.cpu=0.5,resource.master.requests.memory=0.5Gi,\
  4. resource.tserver.requests.cpu=0.5,resource.tserver.requests.memory=0.5Gi --namespace yb-demo

Note that in minikube, the LoadBalancers for yb-master-ui and yb-tserver-service will remain in pending state since load balancers are not available in a minikube environment. If you would like to turn off these services simply pass the enableLoadBalancer=False flag as shown below.

  1. $ helm install yb-demo yugabytedb/yugabyte \
  2. --set resource.master.requests.cpu=0.5,resource.master.requests.memory=0.5Gi,\
  3. resource.tserver.requests.cpu=0.5,resource.tserver.requests.memory=0.5Gi,\
  4. enableLoadBalancer=False --namespace yb-demo

Check the cluster status

You can check the status of the cluster using various commands noted below.

For Helm 2:

  1. $ helm status yb-demo

For Helm 3:

  1. $ helm status yb-demo -n yb-demo

Output:

  1. NAME: yb-demo
  2. LAST DEPLOYED: Thu Feb 13 13:29:13 2020
  3. NAMESPACE: yb-demo
  4. STATUS: deployed
  5. REVISION: 1
  6. TEST SUITE: None
  7. NOTES:
  8. 1. Get YugabyteDB Pods by running this command:
  9.   kubectl --namespace yb-demo get pods
  11. 2. Get list of YugabyteDB services that are running:
  12.   kubectl --namespace yb-demo get services
  14. 3. Get information about the load balancer services:
  15.   kubectl get svc --namespace yb-demo
  17. 4. Connect to one of the tablet server:
  18.   kubectl exec --namespace yb-demo -it yb-tserver-0 bash
  20. 5. Run YSQL shell from inside of a tablet server:
  21.   kubectl exec --namespace yb-demo -it yb-tserver-0 /home/yugabyte/bin/ysqlsh -- -h yb-tserver-0.yb-tservers.yb-demo
  23. 6. Cleanup YugabyteDB Pods
  24.   helm delete yb-demo --purge
  25.   NOTE: You need to manually delete the persistent volume
  26.   kubectl delete pvc --namespace yb-demo -l app=yb-master
  27.   kubectl delete pvc --namespace yb-demo -l app=yb-tserver

Check the pods.

  1. $ kubectl get pods --namespace yb-demo
  1. NAME           READY     STATUS    RESTARTS   AGE
  2. yb-master-0    2/2       Running   0          4m
  3. yb-master-1    2/2       Running   0          4m
  4. yb-master-2    2/2       Running   0          4m
  5. yb-tserver-0   2/2       Running   0          4m
  6. yb-tserver-1   2/2       Running   0          4m
  7. yb-tserver-2   2/2       Running   0          4m

Check the services.

  1. $ kubectl get services --namespace yb-demo
  1. NAME                 TYPE           CLUSTER-IP      EXTERNAL-IP    PORT(S)                                        AGE
  2. yb-master-ui         LoadBalancer   10.109.39.242   35.225.153.213 7000:31920/TCP                                 10s
  3. yb-masters           ClusterIP      None            <none>         7100/TCP,7000/TCP                              10s
  4. yb-tserver-service   LoadBalancer   10.98.36.163    35.225.153.214 6379:30929/TCP,9042:30975/TCP,5433:30048/TCP   10s
  5. yb-tservers          ClusterIP      None            <none>         7100/TCP,9000/TCP,6379/TCP,9042/TCP,5433/TCP   10s

You can even check the history of the yb-demo deployment.

For Helm 2:

  1. $ helm history yb-demo

For Helm 3:

  1. $ helm history yb-demo -n yb-demo

Output:

  1. REVISION  UPDATED                   STATUS    CHART           APP VERSION   DESCRIPTION     
  2. 1         Thu Feb 13 13:29:13 2020  deployed  yugabyte-2.0.12 2.0.12.0-b10  Install complete

Connect using YugabyteDB Shells

To connect and use the YSQL Shell ysqlsh, run the following command.

  1. $ kubectl exec -n yb-demo -it yb-tserver-0 /home/yugabyte/bin/ysqlsh -- -h yb-tserver-0.yb-tservers.yb-demo

To connect and use the YCQL Shell cqlsh, run the following command.

  1. $ kubectl exec -n yb-demo -it yb-tserver-0 /home/yugabyte/bin/cqlsh yb-tserver-0.yb-tservers.yb-demo

Connect using external clients

To connect an external program, get the load balancer EXTERNAL-IP IP address of the yb-tserver-service service and connect to the 5433 / 9042 ports for YSQL / YCQL services respectively.

  1. $ kubectl get services --namespace yb-demo
  1. NAME                 TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                        AGE
  2. ...
  3. yb-tserver-service   LoadBalancer   10.98.36.163    35.225.153.214     6379:30929/TCP,9042:30975/TCP,5433:30048/TCP   10s
  4. ...

Configure cluster

Instead of using the default values in the Helm chart, you can also modify the configuration of the YugabyteDB cluster according to your requirements. The following section shows the commands and tags that can be modified to achieve the desired configuration.

CPU, memory, and replica count

The default values for the Helm chart are in the helm/yugabyte/values.yaml file. The most important ones are listed below. As noted in the Prerequisites section above, the defaults are set for a 3-node Kubernetes cluster, each node with 4 CPU cores and 15 GB RAM.

  1. persistentVolume:
  2.   count: 2
  3.   storage: 10Gi
  4.   storageClass: standard
  6. resource:
  7.   master:
  8.     requests:
  9.       cpu: 2
  10.       memory: 7.5Gi
  11.   tserver:
  12.     requests:
  13.       cpu: 2
  14.       memory: 7.5Gi
  16. replicas:
  17.   master: 3
  18.   tserver: 3
  20. partition:
  21.   master: 3
  22.   tserver: 3

If you want to change the defaults, you can use the command below. You can even do helm install instead of helm upgrade when you are installing on a Kubernetes cluster with configuration different than the defaults.

  1. $ helm upgrade --set resource.tserver.requests.cpu=8,resource.tserver.requests.memory=15Gi yb-demo ./yugabyte

Replica count can be changed using the command below. Note only the tservers need to be scaled in a Replication Factor 3 cluster which keeps the masters count at 3.

  1. $ helm upgrade --set replicas.tserver=5 yb-demo ./yugabyte

Independent LoadBalancers

By default, the YugabyteDB Helm chart will expose the client API endpoints as well as master UI endpoint using 2 LoadBalancers. If you want to expose the client APIs using independent LoadBalancers, you can do the following.

For Helm 2:

  1. helm install yugabytedb/yugabyte -f https://raw.githubusercontent.com/yugabyte/charts/master/stable/yugabyte/expose-all.yaml --namespace yb-demo --name yb-demo --wait

For Helm 3:

  1. helm install yb-demo yugabytedb/yugabyte -f https://raw.githubusercontent.com/yugabyte/charts/master/stable/yugabyte/expose-all.yaml --namespace yb-demo --wait

You can also bring up an internal LoadBalancer (for either YB-Master or YB-TServer services), if required. Just specify the annotation required for your cloud provider. See Amazon EKS and Google Kubernetes Engine for examples.

Storage class

In case you want to use a storage class other than the standard class for your deployment, provision the storage class and then pass in the name of the class while running the helm install command.

  1. $ helm install yugabyte --namespace yb-demo --name yb-demo --set persistentVolume.storageClass=<name of provisioned storage> --wait

Upgrade cluster

You can perform rolling upgrades on the YugabyteDB cluster with the following command. Change the Image.tag value to any valid tag from YugabyteDB’s listing on the Docker Hub registry. By default, the installation uses the latest Docker image. In the examples, the Docker image specified is 2.0.10.0-b4.

For Helm 2:

  1. $ helm upgrade yb-demo yugabytedb/yugabyte --set Image.tag=2.0.10.0-b4 --wait

For Helm 3:

  1. $ helm upgrade yb-demo yugabytedb/yugabyte --set Image.tag=2.0.10.0-b4 --wait -n yb-demo

Delete cluster

To delete the cluster, you need to purge the Helm chart, and then delete the PVCs.

For Helm 2:

  1. $ helm del --purge yb-demo

For Helm 3:

  1. $ helm uninstall yb-demo -n yb-demo
  1. $ kubectl delete pvc --namespace yb-demo --all