The YugabyteDB Vagrant Box

Using Vagrant, anyone running Windows, Linux or Mac OS X can run and test drive a YugabyteDB cluster without the need to install and configure YugabyteDB. Plus, you can start over if you want to test something different in a matter of minutes, or scale up the cluster, etc.

Please mind that the Vagrant images are non-official images for demo and test purposes, and not configured nor representative for performance.

This is how it works (Mac OS X):

1. Add the box from the Vagrant Cloud:

fritshoogland@MacBook-Pro-van-Frits yugabyte % vagrant box add FritsHoogland/centos8-yugabyte-2.7.0.0
==> box: Loading metadata for box 'FritsHoogland/centos8-yugabyte-2.7.0.0'
    box: URL: https://vagrantcloud.com/FritsHoogland/centos8-yugabyte-2.7.0.0
==> box: Adding box 'FritsHoogland/centos8-yugabyte-2.7.0.0' (v0.0.3) for pro..
    box: Downloading: https://vagrantcloud.com/FritsHoogland/boxes/centos8-yu..
    box: Calculating and comparing box checksum...
==> box: Successfully added box 'FritsHoogland/centos8-yugabyte-2.7.0.0' (v0...
fritshoogland@MacBook-Pro-van-Frits yugabyte %

2. Create a directory where you want the Vagrantfile and disks to be stored, and copy the embedded Vagrantfile into it:

fritshoogland@MacBook-Pro-van-Frits T7 % mkdir yugabyte
fritshoogland@MacBook-Pro-van-Frits T7 % cd $_
fritshoogland@MacBook-Pro-van-Frits yugabyte % cp ~/.vagrant.d/boxes/FritsHoogland-VAGRANTSLASH-centos8-yugabyte-2.7.0.0/0.0.3/virtualbox/Vagrantfile .
fritshoogland@MacBook-Pro-van-Frits yugabyte %

Note that the step of copying the embedded Vagrantfile into the Vagrant directory is unique to the YugabyteDB Vagrant box. This is needed in order to be able to use the multi-machine definitions in the Vagrantfile.

3. Ask Vagrant to startup, which creates and configures the virtual machine(s):

fritshoogland@MacBook-Pro-van-Frits yugabyte % vagrant up
Bringing machine 'yb-1' up with 'virtualbox' provider...
==> yb-1: Running action triggers before up ...
==> yb-1: Running trigger...
==> yb-1: vagrant runs with the following settings:
==> yb-1: environment variable value
==> yb-1: NR                   1
==> yb-1: RF                   1
==> yb-1: NAME                 yb
==> yb-1: NET_ADDRESS          192.168.66
==> yb-1: HOST_ADDRESS         80
==> yb-1: MEM                  1024
==> yb-1: CPUS                 1
==> yb-1: ADD_DISK             yes
==> yb-1: DISK_SIZE            10240
==> yb-1: START_SERVICES       yes
... output cut for brevity ...
fritshoogland@MacBook-Pro-van-Frits yugabyte %

4. The YugabyteDB virtual machine is ready! Log on using SSH:

fritshoogland@MacBook-Pro-van-Frits yugabyte % vagrant ssh
[vagrant@yb-1 ~]$ . yb-env
[vagrant@yb-1 ~]$ yb-admin -init_master_addrs=localhost:7100 list_all_masters
Master UUID                      RPC Host/Port        State    Role
fd4bd4f5c99c49eb916b77c99c2442d4 yb-1.local:7100      ALIVE    LEA..
[vagrant@yb-1 ~]$

The default setup creates a single machine and the YugabyteDB database using a replication factor of 1, the simplest setup possible.

A Cluster with a Replication Factor of 3

Actual usage of YugabyteDB would typically be using a replication factor of 3. Running YugabyteDB with a replication factor of 3 requires at least 3 yb-master processes and 3 yb-tservers. This can be achieved using Vagrant in the following way:

1. Remove current YugabyteDB setup:

fritshoogland@MacBook-Pro-van-Frits yugabyte % vagrant destroy
    yb-1: Are you sure you want to destroy the 'yb-1' VM? [y/N] y
==> yb-1: Forcing shutdown of VM...
==> yb-1: Destroying VM and associated drives...
fritshoogland@MacBook-Pro-van-Frits yugabyte %

2. Set the replication factor to 3:

fritshoogland@MacBook-Pro-van-Frits yugabyte % export RF=3

3. Ask Vagrant to startup, which will create the cluster:

fritshoogland@MacBook-Pro-van-Frits yugabyte % vagrant up
Bringing machine 'yb-1' up with 'virtualbox' provider...
Bringing machine 'yb-2' up with 'virtualbox' provider...
Bringing machine 'yb-3' up with 'virtualbox' provider...
==> yb-1: Running action triggers before up ...
==> yb-1: Running trigger...
==> yb-1: vagrant runs with the following settings:
==> yb-1: environment variable value
==> yb-1: NR                   3
==> yb-1: RF                   3
==> yb-1: NAME                 yb
==> yb-1: NET_ADDRESS          192.168.66
==> yb-1: HOST_ADDRESS         80
==> yb-1: MEM                  1024
==> yb-1: CPUS                 1
==> yb-1: ADD_DISK             yes
==> yb-1: DISK_SIZE            10240
==> yb-1: START_SERVICES       yes
... output cut for brevity ...
fritshoogland@MacBook-Pro-van-Frits yugabyte %

4. The YugabyteDB cluster is ready! Log on using SSH:

fritshoogland@MacBook-Pro-van-Frits yugabyte % vagrant ssh yb-1
[vagrant@yb-1 ~]$ . yb-env
[vagrant@yb-1 ~]$ yb-admin -init_master_addrs=localhost:7100 list_all_masters
Master UUID                      RPC Host/Port        State    Role
87214377f03d4279a7890c66b50d9b28 yb-1.local:7100      ALIVE    FOL..
3d342cd8bbea48b281a7e97e71c3f675 yb-2.local:7100      ALIVE    FOL..
a60cedab2a7541259e8a7a450ecbe990 yb-3.local:7100      ALIVE    LEA..
[vagrant@yb-1 ~]$ yb-admin -init_master_addrs=localhost:7100 list_all_tablet_servers
Tablet Server UUID               RPC Host/Port Heartbeat delay Status   ..
c361b215e13e40e49b5ffa8a2ad2fc70 yb-1.local:9100 0.41s           ALIVE  ..
de93694aedc44fe584a3d0d0a5016657 yb-2.local:9100 0.40s           ALIVE  ..
e7115f88804f4df4aa6ec5807fb40077 yb-3.local:9100 0.43s           ALIVE  ..

Please mind the addition of the machine name ‘yb-1’ with the Vagrant SSH command. Because there are 3 individual machines (independent Virtualbox virtual machines) running YugabyteDB, you have to specify which machine you want to connect using SSH.

The settings, such as the replication factor (RF), but also the number of machines (NR), amount of memory per virtual machine (MEM), number of virtual CPUs per virtual machine (CPUS) are set using exported environment variables. The settings are written in a file in the Vagrant directory called ‘vagrant_settings.json’, which is read during startup, so settings different from the default value do not have to be set every single time the Vagrant environment is started.

Requirements

In order to use the Vagrant box, both Virtualbox and Vagrant must be installed. The ‘Vagrant box add’ command downloads the image from the Vagrant cloud, which is approximately 1.2G in size, which means a ‘reasonable’ connection to the internet is required. It also means there should be enough disk space to save the downloaded image, and host the images for the virtual machines.

Further Vagrant Usage

Other manipulation of the Vagrant virtual machine(s) is done using the Vagrant command. Most Vagrant commands have to be run inside the directory containing the Vagrantfile describing the configuration, which allows Vagrant to link it with the Virtualbox virtual machine(s).

These include:

• vagrant up: Startup and configure a virtual machine or virtual machines
• vagrant up: Startup an already configured setup, omitting provisioning
• vagrant halt: Shutdown a running setup
• vagrant destroy: Remove configured virtual machines
• vagrant status: Obtain the current status of a Vagrant setup
• vagrant global-status: Obtain the status of all configured Vagrant boxes

Conclusion

We invite you to reach out to your Yugabyte support team or contact us on the YugabyteDB community Slack so we can help you navigate through the process.