Quick start
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. -
To install
kubectl
, see Install kubectl in the Kubernetes documentation. -
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 Universe.
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.
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:
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.