Create Local Cluster
After installing YugaByte DB, follow the instructions below to create a local cluster.
Note
We do not recommend a local cluster setup on a single host for production deployments or performance benchmarking. Deploy a true multi-node on multi-host setup using the manual or orchestrated deployment steps for such needs.1. Create a local cluster
We will use the yb-ctl utility located in the bin directory of the YugaByte DB package to create and administer a local cluster. The default data directory used is $HOME/yugabyte-data. You can change this directory with the --data_dir option. Detailed output for the create command is available in yb-ctl Reference.
$ ./bin/yb-ctl create
By default, the above command will create a 1 node cluster with Replication Factor (RF) 1. The initial cluster creation may take a minute or so without any output on the prompt.
You can create a 3 node cluster with RF 3 by using the command below.
$ ./bin/yb-ctl --rf 3 create
You can now check $HOME/yugabyte-data to see node-i directories created where i represents the node_id of the node. Inside each such directory, there will be 2 disks disk1 and disk2 to highlight the fact that YugaByte DB can work with multiple disks at the same time. Note that the IP address of node-i is by default set to 127.0.0.i.
Clients can now connect to the YSQL and YCQL APIs at localhost:5433 and localhost:9042 respectively.
2. Check cluster status with yb-ctl
Run the command below to see that we now have 1 yb-master process and 1 yb-tserver process running on this localhost. Roles played by these processes in a YugaByte cluster (aka Universe) is explained in detail here.
$ ./bin/yb-ctl status
----------------------------------------------------------------------------------------------------
| Node Count: 1 | Replication Factor: 1 |
----------------------------------------------------------------------------------------------------
| JDBC : postgresql://[email protected]:5433 |
| YSQL Shell : ./bin/ysqlsh |
| YCQL Shell : ./bin/cqlsh 127.0.0.1 9042 |
| YEDIS Shell : ./bin/redis-cli -h 127.0.0.1 -p 6379 |
| Web UI : http://127.0.0.1:7000/ |
| Cluster Data : /Users/schoudhury/yugabyte-data |
----------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------
| Node 1: yb-tserver (pid 68412), yb-master (pid 68409) |
----------------------------------------------------------------------------------------------------
| JDBC : postgresql://[email protected]:5433 |
| YSQL Shell : ./bin/ysqlsh |
| YCQL Shell : ./bin/cqlsh 127.0.0.1 9042 |
| YEDIS Shell : ./bin/redis-cli -h 127.0.0.1 -p 6379 |
| data-dir[0] : /Users/schoudhury/yugabyte-data/node-1/disk-1/yb-data |
| yb-tserver Logs : /Users/schoudhury/yugabyte-data/node-1/disk-1/yb-data/tserver/logs |
| yb-master Logs : /Users/schoudhury/yugabyte-data/node-1/disk-1/yb-data/master/logs |
----------------------------------------------------------------------------------------------------
3. Check cluster status with Admin UI
Node 1’s master Admin UI is available at http://127.0.0.1:7000 and the tserver Admin UI is available at http://127.0.0.1:9000. If you created a multi-node cluster, you can visit the other nodes’ Admin UIs by using their corresponding IP addresses.
3.1 Overview and Master status
Node 1’s master Admin UI home page shows that we have a cluster (aka a Universe) with Replication Factor of 1 and Num Nodes (TServers) as 1. The Num User Tables is 0 since there are no user tables created yet. YugaByte DB version number is also shown for your reference.
The Masters section highlights the 1 yb-master along with its corresponding cloud, region and zone placement.
3.2 TServer status
Clicking on the See all nodes takes us to the Tablet Servers page where we can observe the 1 tserver along with the time since it last connected to this master via regular heartbeats. Since there are no user tables created yet, we can see that the Load (Num Tablets) is 0. As new tables get added, new tablets (aka shards) will get automatically created and distributed evenly across all the available tablet servers.
1. Create a local cluster
We will use the yb-ctl utility located in the bin directory of the YugaByte DB package to create and administer a local cluster. The default data directory used is $HOME/yugabyte-data. You can change this directory with the --data_dir option. Detailed output for the create command is available in yb-ctl Reference.
$ ./bin/yb-ctl create
By default, the above command will create a 1 node cluster with Replication Factor (RF) 1. The initial cluster creation may take a minute or so without any output on the prompt.
You can create a 3 node cluster with RF 3 by using the command below.
$ ./bin/yb-ctl --rf 3 create
You can now check $HOME/yugabyte-data to see node-i directories created where i represents the node_id of the node. Inside each such directory, there will be 2 disks disk1 and disk2 to highlight the fact that YugaByte DB can work with multiple disks at the same time. Note that the IP address of node-i is by default set to 127.0.0.i.
Clients can now connect to the YSQL and YCQL APIs at localhost:5433 and localhost:9042 respectively.
2. Check cluster status with yb-ctl
Run the command below to see that we now have 1 yb-master process and 1 yb-tserver process running on this localhost. Roles played by these processes in a YugaByte cluster (aka Universe) is explained in detail here.
$ ./bin/yb-ctl status
----------------------------------------------------------------------------------------------------
| Node Count: 1 | Replication Factor: 1 |
----------------------------------------------------------------------------------------------------
| JDBC : postgresql://[email protected]:5433 |
| YSQL Shell : ./bin/ysqlsh |
| YCQL Shell : ./bin/cqlsh 127.0.0.1 9042 |
| YEDIS Shell : ./bin/redis-cli -h 127.0.0.1 -p 6379 |
| Web UI : http://127.0.0.1:7000/ |
| Cluster Data : /Users/schoudhury/yugabyte-data |
----------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------
| Node 1: yb-tserver (pid 68412), yb-master (pid 68409) |
----------------------------------------------------------------------------------------------------
| JDBC : postgresql://[email protected]:5433 |
| YSQL Shell : ./bin/ysqlsh |
| YCQL Shell : ./bin/cqlsh 127.0.0.1 9042 |
| YEDIS Shell : ./bin/redis-cli -h 127.0.0.1 -p 6379 |
| data-dir[0] : /Users/schoudhury/yugabyte-data/node-1/disk-1/yb-data |
| yb-tserver Logs : /Users/schoudhury/yugabyte-data/node-1/disk-1/yb-data/tserver/logs |
| yb-master Logs : /Users/schoudhury/yugabyte-data/node-1/disk-1/yb-data/master/logs |
----------------------------------------------------------------------------------------------------
3. Check cluster status with Admin UI
Node 1’s master Admin UI is available at http://127.0.0.1:7000 and the tserver Admin UI is available at http://127.0.0.1:9000. If you created a multi-node cluster, you can visit the other nodes’ Admin UIs by using their corresponding IP addresses.
3.1 Overview and Master status
Node 1’s master Admin UI home page shows that we have a cluster (aka a Universe) with Replication Factor of 1 and Num Nodes (TServers) as 1. The Num User Tables is 0 since there are no user tables created yet. YugaByte DB version number is also shown for your reference.
The Masters section highlights the 1 yb-master along with its corresponding cloud, region and zone placement.
3.2 TServer status
Clicking on the See all nodes takes us to the Tablet Servers page where we can observe the 1 tserver along with the time since it last connected to this master via regular heartbeats. Since there are no user tables created yet, we can see that the Load (Num Tablets) is 0. As new tables get added, new tablets (aka shards) will get automatically created and distributed evenly across all the available tablet servers.
1. Create a local cluster
We will use the yb-docker-ctl utility downloaded in the previous step to create and administer a containerized local cluster. Detailed output for the create command is available in yb-docker-ctl Reference.
$ ./yb-docker-ctl create
By default, the above command will create a 1 node cluster with Replication Factor (RF) 1. You can create run a 3 node cluster with RF 3 by using the command below.
$ ./yb-docker-ctl create --rf 3
Clients can now connect to the YSQL and YCQL APIs at localhost:5433 and localhost:9042 respectively.
2. Check cluster status with yb-docker-ctl
Run the command below to see that we now have 1 yb-master (yb-master-n1) and 1 yb-tserver (yb-tserver-n1) containers running on this localhost. Roles played by these containers in a YugaByte DB cluster are explained in detail here.
$ ./yb-docker-ctl status
ID PID Type Node URL Status Started At
921494a8058d 5547 tserver yb-tserver-n1 http://192.168.64.5:9000 Running 2018-10-18T22:02:50.187976253Z
feea0823209a 5039 master yb-master-n1 http://192.168.64.2:7000 Running 2018-10-18T22:02:47.163244578Z
3. Check cluster status with Admin UI
The yb-master-n1 Admin UI is available at http://localhost:7000 and the yb-tserver-n1 Admin UI is available at http://localhost:9000. Other masters and tservers do not have their admin ports mapped to localhost to avoid port conflicts.
NOTE: Clients connecting to the cluster will connect to only yb-tserver-n1 even if you used yb-docker-ctl to create a multi-node local cluster. In case of Docker for Mac, routing traffic directly to containers is not even possible today. Since only 1 node will receive the incoming client traffic, throughput expected for Docker-based local clusters can be significantly lower than binary-based local clusters.
3.1 Overview and Master status
The yb-master-n1 home page shows that we have a cluster (aka a Universe) with Replication Factor of 1 and Num Nodes (TServers) as 1. The Num User Tables is 0 since there are no user tables created yet. YugaByte DB version number is also shown for your reference.
The Masters section highlights the 3 masters along with their corresponding cloud, region and zone placement.
3.2 TServer status
Clicking on the See all nodes takes us to the Tablet Servers page where we can observe the 1 tservers along with the time since it last connected to this master via regular heartbeats. Additionally, we can see that the Load (Num Tablets) is balanced across all available tservers. These tablets are the shards of the user tables currently managed by the cluster (which in this case is the system_redis.redis table). As new tables get added, new tablets will get automatically created and distributed evenly across all the available tservers.
1. Create a 1 node cluster with replication factor 1
$ kubectl apply -f yugabyte-statefulset-rf-1.yaml
service/yb-masters created
service/yb-master-ui created
statefulset.apps/yb-master created
service/yb-tservers created
statefulset.apps/yb-tserver created
By default, the above command will create a 1 node cluster with Replication Factor (RF) 1. This cluster has 1 pod of yb-master and yb-tserver each. If you want to create a 3 node local cluster with RF 3, then simply change the replica count of yb-master and yb-tserver in the yaml file to 3.
2. Check cluster status
Run the command below to see that we now have two services with 1 pods each - 1 yb-master pod (yb-master-1) and 1 yb-tserver pods (yb-tserver-1) running. Roles played by these pods in a YugaByte DB cluster (aka Universe) is explained in detail here.
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
yb-master-0 0/1 ContainerCreating 0 5s
yb-tserver-0 0/1 ContainerCreating 0 4s
Eventually all the pods will have the Running state.
Run the following command to initialize the YSQL API. Note that this step can take a few minutes depending on the resource utilization of your Kubernetes environment.
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
yb-master-0 1/1 Running 0 13s
yb-tserver-0 1/1 Running 0 12s
3. Initialize the YSQL API
$ kubectl exec -it yb-master-0 bash -- -c "YB_ENABLED_IN_POSTGRES=1 FLAGS_pggate_master_addresses=yb-master-0.yb-masters.default.svc.cluster.local:7100 /home/yugabyte/postgres/bin/initdb -D /tmp/yb_pg_initdb_tmp_data_dir -U postgres"
Clients can now connect to this YugaByte DB universe using YSQL and YCQL APIs on the 5433 and 9042 ports respectively.
4. Check cluster status via Kubernetes
You can see the status of the 3 services by simply running the following command.
$ kubectl get services
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 13m
yb-master-ui LoadBalancer 10.110.45.247 <pending> 7000:32291/TCP 11m
yb-masters ClusterIP None <none> 7000/TCP,7100/TCP 11m
yb-tservers ClusterIP None <none> 9000/TCP,9100/TCP,9042/TCP,6379/TCP,5433/TCP 11m
5. Check cluster status with Admin UI
In order to do this, we would need to access the UI on port 7000 exposed by any of the pods in the yb-master service. In order to do so, we find the URL for the yb-master-ui LoadBalancer service.
$ minikube service yb-master-ui --url
http://192.168.99.100:31283
Now, you can view the yb-master-0 Admin UI is available at the above URL.
5.1 Overview and Master status
The yb-master-0 home page shows that we have a cluster (aka a Universe) with Replication Factor of 1 and Num Nodes (TServers) as 1. The Num User Tables is 0 since there are no user tables created yet. YugaByte DB version is also shown for your reference.
The Masters section highlights the 1 yb-master along its corresponding cloud, region and zone placement information.
5.2 TServer status
Clicking on the See all nodes takes us to the Tablet Servers page where we can observe the 1 tserver along with the time since it last connected to this master via regular heartbeats. Additionally, we can see that the Load (Num Tablets) is balanced across all available tservers. These tablets are the shards of the user tables currently managed by the cluster (which in this case is the system_redis.redis table). As new tables get added, new tablets will get automatically created and distributed evenly across all the available tservers.
