yb-docker-ctl
Attention
This page documents an earlier version. Go to the latest (v2.3) version.The yb-docker-ctl utility provides a simple command line interface (CLI), or shell, for administering local Docker-based clusters for development and learning. It manages the YB-Master and YB-TServer containers to perform the necessary administration.
Download
$ mkdir ~/yugabyte && cd ~/yugabyte
$ wget https://raw.githubusercontent.com/yugabyte/yugabyte-db/master/bin/yb-docker-ctl && chmod +x yb-docker-ctl
Help command
Use the -\-help option to see all of the supported commands.
$ ./yb-docker-ctl -h
usage: yb-docker-ctl [-h]
{create,add_node,status,destroy,stop_node,start_node,stop,start,remove_node}
...
Yugabyte Docker Container Control
positional arguments:
{create,add_node,status,destroy,stop_node,start_node,stop,start,remove_node}
Commands
create Create Yugabyte Cluster
add_node Add a new Yugabyte Cluster Node
status Check Yugabyte Cluster status
destroy Destroy Yugabyte Cluster
stop_node Stop a Yugabyte Cluster Node
start_node Start a Yugabyte Cluster Node
stop Stop Yugabyte Cluster so that it can be started later
start Start Yugabyte Cluster if one already exists
remove_node Stop a Yugabyte Cluster Node
optional arguments:
-h, --help show this help message and exit
Create a cluster
Use the yb-docker-ctl create command to create a local Docker-based cluster for development and learning.
The number of nodes created when you use the yb-dockter-ctl create command is always equal to the replication factor (RF), ensuring that all of the replicas for a given tablet can be placed on different nodes. With the add_node and remove_node commands, the size of the cluster can thereafter be expanded or shrunk as needed.
Create a 1-node local cluster with RF of 1
To create a 1-node local cluster for development and learning YugabyteDB, run the default yb-docker-ctl command. By default, this creates a 1-node cluster with a replication factor (RF) of 1. Note that the yb-docker-ctl create command pulls the latest yugabytedb/yugabyte image at the outset, in case the image has not yet downloaded or is not the latest version.
$ ./yb-docker-ctl create
Create a 3-node local cluster with RF of 3
When you create a 3-node local Docker-based cluster using the yb-docker-ctl create command, each of the initial nodes run a yb-tserver process and a yb-master process. Note that the number of YB-Masters in a cluster has to equal to the replication factor (RF) for the cluster to be considered as operating normally and the number of YB-TServers is equal to be the number of nodes.
To create a 3-node local Docker-based cluster for development and learning, run the following yb-docker-ctl command.
$ ./yb-docker-ctl create --rf 3
docker run --name yb-master-n1 --privileged -p 7000:7000 --net yb-net --detach yugabytedb/yugabyte:latest /home/yugabyte/yb-master --fs_data_dirs=/mnt/disk0,/mnt/disk1 --master_addresses=yb-master-n1:7100,yb-master-n2:7100,yb-master-n3:7100 --rpc_bind_addresses=yb-master-n1:7100
Adding node yb-master-n1
docker run --name yb-master-n2 --privileged --net yb-net --detach yugabytedb/yugabyte:latest /home/yugabyte/yb-master --fs_data_dirs=/mnt/disk0,/mnt/disk1 --master_addresses=yb-master-n1:7100,yb-master-n2:7100,yb-master-n3:7100 --rpc_bind_addresses=yb-master-n2:7100
Adding node yb-master-n2
docker run --name yb-master-n3 --privileged --net yb-net --detach yugabytedb/yugabyte:latest /home/yugabyte/yb-master --fs_data_dirs=/mnt/disk0,/mnt/disk1 --master_addresses=yb-master-n1:7100,yb-master-n2:7100,yb-master-n3:7100 --rpc_bind_addresses=yb-master-n3:7100
Adding node yb-master-n3
docker run --name yb-tserver-n1 --privileged -p 9000:9000 -p 9042:9042 -p 6379:6379 --net yb-net --detach yugabytedb/yugabyte:latest /home/yugabyte/yb-tserver --fs_data_dirs=/mnt/disk0,/mnt/disk1 --tserver_master_addrs=yb-master-n1:7100,yb-master-n2:7100,yb-master-n3:7100 --rpc_bind_addresses=yb-tserver-n1:9100
Adding node yb-tserver-n1
docker run --name yb-tserver-n2 --privileged --net yb-net --detach yugabytedb/yugabyte:latest /home/yugabyte/yb-tserver --fs_data_dirs=/mnt/disk0,/mnt/disk1 --tserver_master_addrs=yb-master-n1:7100,yb-master-n2:7100,yb-master-n3:7100 --rpc_bind_addresses=yb-tserver-n2:9100
Adding node yb-tserver-n2
docker run --name yb-tserver-n3 --privileged --net yb-net --detach yugabytedb/yugabyte:latest /home/yugabyte/yb-tserver --fs_data_dirs=/mnt/disk0,/mnt/disk1 --tserver_master_addrs=yb-master-n1:7100,yb-master-n2:7100,yb-master-n3:7100 --rpc_bind_addresses=yb-tserver-n3:9100
Adding node yb-tserver-n3
PID Type Node URL Status Started At
11818 tserver yb-tserver-n3 http://172.19.0.7:9000 Running 2017-11-28T23:33:00.369124907Z
11632 tserver yb-tserver-n2 http://172.19.0.6:9000 Running 2017-11-28T23:32:59.874963849Z
11535 tserver yb-tserver-n1 http://172.19.0.5:9000 Running 2017-11-28T23:32:59.444064946Z
11350 master yb-master-n3 http://172.19.0.4:9000 Running 2017-11-28T23:32:58.899308826Z
11231 master yb-master-n2 http://172.19.0.3:9000 Running 2017-11-28T23:32:58.403788411Z
11133 master yb-master-n1 http://172.19.0.2:9000 Running 2017-11-28T23:32:57.905097927Z
Create a 5-node local cluster with replication factor of 5
$ ./yb-docker-ctl create --rf 5
Check cluster status
Get the status of your local cluster, including the URLs for the Admin UI for each YB-Master and YB-TServer.
$ ./yb-docker-ctl status
PID Type Node URL Status Started At
11818 tserver yb-tserver-n3 http://172.19.0.7:9000 Running 2017-11-28T23:33:00.369124907Z
11632 tserver yb-tserver-n2 http://172.19.0.6:9000 Running 2017-11-28T23:32:59.874963849Z
11535 tserver yb-tserver-n1 http://172.19.0.5:9000 Running 2017-11-28T23:32:59.444064946Z
11350 master yb-master-n3 http://172.19.0.4:9000 Running 2017-11-28T23:32:58.899308826Z
11231 master yb-master-n2 http://172.19.0.3:9000 Running 2017-11-28T23:32:58.403788411Z
11133 master yb-master-n1 http://172.19.0.2:9000 Running 2017-11-28T23:32:57.905097927Z
Add a node
Add a new node to the cluster. This will start a new yb-tserver process and give it a new node_id for tracking purposes.
$ ./yb-docker-ctl add_node
docker run --name yb-tserver-n4 --net yb-net --detach yugabytedb/yugabyte:latest /home/yugabyte/yb-tserver --fs_data_dirs=/mnt/disk0,/mnt/disk1 --tserver_master_addrs=04:7100,04:7100,04:7100 --rpc_bind_addresses=yb-tserver-n4:9100
Adding node yb-tserver-n4
Remove a node
Remove a node from the cluster by executing the following command. The command takes the node_id of the node to be removed as input.
Help
$ ./yb-docker-ctl remove_node --help
usage: yb-docker-ctl remove_node [-h] node
positional arguments:
node_id Index of the node to remove
optional arguments:
-h, --help show this help message and exit
Example
$ ./yb-docker-ctl remove_node 3
Stopping node :yb-tserver-n3
Destroy cluster
The yb-docker-ctl destroy command below destroys the local cluster, including deletion of the data directories.
$ ./yb-docker-ctl destroy
Upgrade container image
The following docker pull command below upgrades the Docker image of YugabyteDB to the latest version.
$ docker pull yugabytedb/yugabyte