Quick start

Create a local cluster on a single host

The local cluster setup on a single host is intended for development and learning. For production deployment, performance benchmarking, or deploying a true multi-node on multi-host setup, see Deploy YugabyteDB.

Install YugabyteDB

Installing YugabyteDB involves completing prerequisites, starting Kubernetes, and downloading Helm chart.

Prerequisites

Before installing YugabyteDB, ensure that you have the following installed:

  • Minikube on your localhost machine.

    The Kubernetes version used by Minikube should be 1.18.0 or later. The default Kubernetes version being used by Minikube displays when you run the minikube start command. To install Minikube, see Install Minikube in the Kubernetes documentation.

  • kubectl.

    To install kubectl, see Install kubectl in the Kubernetes documentation.

  • Helm 3.4 or later.

    To install helm, see Install helm in the Helm documentation.

Start Kubernetes

To start Kubernetes, perform the following:

  • Start Kubernetes using Minikube by running the following command. Note that minikube by default brings up a single-node Kubernetes environment with 2GB RAM, 2 CPUS, and a disk of 20GB. You should start minkube with at least 8GB RAM, 4 CPUs and 40GB disk, as follows:

    minikube start --memory=8192 --cpus=4 --disk-size=40g --vm-driver=virtualbox

    ...
Configuring environment for Kubernetes v1.14.2 on Docker 18.09.6
...

  • Review Kubernetes dashboard by running the following command:

    minikube dashboard

  • Confirm that your kubectl is configured correctly by running the following command:

    kubectl version

    Client Version: version.Info{Major:"1", Minor:"14+", GitVersion:"v1.14.10-dispatcher", ...}
Server Version: version.Info{Major:"1", Minor:"14", GitVersion:"v1.14.2", ...}

  • Confirm that your Helm is configured correctly by running the following command:

    helm version

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

Download YugabyteDB Helm chart

To start YugabyteDB Helm chart, perform the following:

  • Add the charts repository using the following command:

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

  • Fetch updates from the repository by running the following command:

    helm repo update

  • Validate the chart version, as follows:

    helm search repo yugabytedb/yugabyte --version 2.19.3

    NAME                 CHART VERSION  APP VERSION    DESCRIPTION
yugabytedb/yugabyte  2.19.3         2.19.3.0-b140  YugabyteDB is the high-performance distributed ...

Now you are ready to create a local YugabyteDB cluster.

Create a local cluster

Create a YugabyteDB cluster in Minikube using the following commands. Note that for Helm, you have to first create a namespace:

kubectl create namespace yb-demo
helm install yb-demo yugabytedb/yugabyte \
--version 2.19.3 \
--set resource.master.requests.cpu=0.5,resource.master.requests.memory=0.5Gi,\
resource.tserver.requests.cpu=0.5,resource.tserver.requests.memory=0.5Gi,\
replicas.master=1,replicas.tserver=1 --namespace yb-demo

Because load balancers are not available in a Minikube environment, the LoadBalancers for yb-master-ui and yb-tserver-service remain in pending state. To disable these services, you can pass the enableLoadBalancer=False flag, as follows:

helm install yb-demo yugabytedb/yugabyte \
--version 2.19.3 \
--set resource.master.requests.cpu=0.5,resource.master.requests.memory=0.5Gi,\
resource.tserver.requests.cpu=0.5,resource.tserver.requests.memory=0.5Gi,\
replicas.master=1,replicas.tserver=1,enableLoadBalancer=False --namespace yb-demo

Check cluster status with kubectl

Run the following command to verify that you have two services with one running pod in each: one YB-Master pod (yb-master-0) and one YB-Tserver pod (yb-tserver-0). For details on the roles of these pods in a YugabyteDB cluster (also known as universe), see Architecture.

kubectl --namespace yb-demo get pods

NAME           READY     STATUS              RESTARTS   AGE
yb-master-0    0/2       ContainerCreating   0          5s
yb-tserver-0   0/2       ContainerCreating   0          4s

Eventually, all the pods will have the Running state, as per the following output:

NAME           READY     STATUS    RESTARTS   AGE
yb-master-0    2/2       Running   0          13s
yb-tserver-0   2/2       Running   0          12s

To check the status of the three services, run the following command:

kubectl --namespace yb-demo get services

NAME                 TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)                                        AGE
yb-master-ui         LoadBalancer   10.98.66.255   <pending>     7000:31825/TCP                                 119s
yb-masters           ClusterIP      None           <none>        7100/TCP,7000/TCP                              119s
yb-tserver-service   LoadBalancer   10.106.5.69    <pending>     6379:31320/TCP,9042:30391/TCP,5433:30537/TCP   119s
yb-tservers          ClusterIP      None           <none>        7100/TCP,9000/TCP,6379/TCP,9042/TCP,5433/TCP   119s

Check cluster status with Admin UI

The cluster you have created consists of two processes: YB-Master that keeps track of various metadata (list of tables, users, roles, permissions, and so on) and YB-TServer that is responsible for the actual end-user requests for data updates and queries.

Each of the processes exposes its own Admin UI that can be used to check the status of the corresponding process and perform certain administrative operations.

To access the Admin UI, you first need to set up port forwarding for port 7000, as follows:

kubectl --namespace yb-demo port-forward svc/yb-master-ui 7000:7000

Now you can view the yb-master-0 Admin UI at http://localhost:7000.

Overview and YB-Master status

The following illustration shows the YB-Master home page with a cluster with a replication factor of 1, a single node, and no tables. The YugabyteDB version is also displayed.

master-home

The Masters section shows the 1 YB-Master along with its corresponding cloud, region, and zone placement.

YB-TServer status

Click See all nodes to open the Tablet Servers page that lists the YB-TServer along with the time since it last connected to the YB-Master using regular heartbeats, as per the following illustration:

tserver-list

Connect to the database

Using the YugabyteDB SQL shell, ysqlsh, you can connect to your cluster and interact with it using distributed SQL. ysqlsh is installed with YugabyteDB and is located in the bin directory of the YugabyteDB home directory.

To open the YSQL shell (ysqlsh), run the following.

$ kubectl --namespace yb-demo exec -it yb-tserver-0 -- sh -c "cd /home/yugabyte && ysqlsh -h yb-tserver-0 --echo-queries"

ysqlsh (11.2-YB-2.19.3.0-b0)
Type "help" for help.

yugabyte=#

To load sample data and explore an example using ysqlsh, refer to Retail Analytics.

YugabyteDB Kubernetes Operator

A preliminary version of the YugabyteDB Kubernetes Operator is available in Tech Preview (not recommended for production use). The operator automates the deployment, scaling, and management of YugabyteDB clusters in Kubernetes environments. It streamlines database operations, reducing manual effort for developers and operators.

For more information, refer to the YugabyteDB Kubernetes Operator GitHub project.