Using Vagrant to Test Traffic Server¶
The Apache Traffic Server™ project’s official repository includes a Vagrantfile, intended to ease the process of creating environments suitable for building and testing Traffic Server, where all the necessary dependencies are installed automatically for a variety of operating systems and common distribution releases.
Vagrant is a tool for building complete development environments. With an easy-to-use workflow and focus on automation, Vagrant lowers development environment setup time, increases development/production parity, and makes the “works on my machine” excuse a relic of the past.
Vagrant can be used in combination with any of the popular configuration management and automation tools, such as Chef, Puppet, Ansible, and more. The Vagrantfile included in the Traffic Server repository happens to make use of Puppet.
Installing Vagrant and Dependencies¶
VirtualBox¶
The virtualization software VirtualBox is required to create and run the virtual machines created by the included project Vagrantfile.
VirtualBox can be obtained by free from the official website, and many distributions provide their own packages as well. No special configuration of the software is required.
Vagrant¶
A fairly recent version of Vagrant is necessary to use the included Vagrantfile. While older versions of Vagrant could be installed through the Ruby Gems facility, modern versions are only provided as distribution specific packages.
NFS Server¶
The project Vagrantfile uses the NFS shared folders support of VirtualBox to mount the same directory in which the Vagrantfile is located on your host machine as a network directory inside the virtual machine. For this to work, your host machine must have an NFS server installed and running, and the user under which you run the vagrant commands must have sudo permissions to modify the NFS exports configuration and restart the NFS service.
The virtual machine created by Vagrant will still function without a working NFS server on your host machine, but you will not be able to access the shared folder which includes the entire Traffic Server source tree. You may opt to modify the Vagrantfile to use a method other than NFS, as per the Vagrant documentation.
Managing Virtual Machines¶
Listing Available Machines¶
The included Vagrantfile defines many variations of operating systems,
releases, and architectures. To see a complete list of the virtual machine
options available to you, run the command vagrant status from within the
same directory as the Vagrantfile. The command may take a few moments to run as
the configurations defined in the Vagrantfile are evaluated, and calls are made
to the underlying VirtualBox utilities to check for the existence and
operational state of each possibility. You should expect to see output along
the lines of:
$ vagrant status
Current machine states:
saucy32 not created (virtualbox)
raring32 not created (virtualbox)
quantal32 not created (virtualbox)
precise32 not created (virtualbox)
trusty32 not created (virtualbox)
saucy64 not created (virtualbox)
raring64 not created (virtualbox)
quantal64 not created (virtualbox)
precise64 not created (virtualbox)
trusty64 running (virtualbox)
freebsd not created (virtualbox)
omnios not created (virtualbox)
lucid64 not created (virtualbox)
fedora18 not created (virtualbox)
centos63 not created (virtualbox)
centos59 not created (virtualbox)
centos64 not created (virtualbox)
debian7 not created (virtualbox)
sles11 not created (virtualbox)
oel63 not created (virtualbox)
This environment represents multiple VMs. The VMs are all listed
above with their current state. For more information about a specific
VM, run `vagrant status NAME`.
Creating and Destroying¶
Creation and destruction of virtual machines with Vagrant is very simple. To bring a new virtual machine into existence, run the following command from the same directory in which the Vagrantfile is located:
vagrant up <name>
Where <name> should be the specific operating system release you wish to
use for the virtual machine. For example, to test Traffic Server in a CentOS 6.4
environment, you would run:
vagrant up centos64
Running the vagrant up command for a virtual machine which does not exist
yet (or has previously been deleted) will create a brand new virtual machine,
using the appropriate image (called a basebox in Vagrant parlance), as well as
provision the machine according to any configuration management rules specified
in the Vagrantfile.
Similarly, you may destroy the virtual machine when you are finished by running the command:
vagrant destroy <name>
Or if you wish to only stop the virtual machine temporarily without deleting it, you may run:
vagrant halt <name>
A halted virtual machine is started back up with the same vagrant up command
shown earlier. The difference is that Vagrant will recognize the box already
exists and do nothing more than start the vm process and configure the virtual
networking interfaces on your host. Any configuration management hooks in the
Vagrantfile will be skipped.
Logging In¶
Logging into a virtual machine created with Vagrant may be accomplished in a couple different ways. The easiest is to let Vagrant itself figure out where the machine is and how to properly authenticate you to it:
vagrant ssh <name>
Using that command from within the same directory as the Vagrantfile allows you
to skip figuring out what virtual network interface has been attached to the
machine, what local port may be assigned to handle SSH forwarding, and so on.
As long as the virtual machine was already running, you will be quickly dropped
into a local shell in the virtual machine as the vagrant user.
Important
Vagrant by default uses a widely-shared private RSA key on newly created virtual machines (that are built on public basebox images). The default user on these baseboxes is also configured for password-less sudo permissions. This is very clearly insecure, but Vagrant is designed for local testing and development, not production (or other public) uses, so the project has made the philosophical trade-off in favor of ease of use.
Alternatively, you may SSH directly to the virtual machine. Because the virtual machines are configured to use only the private virtual network layer provided by VirtualBox, you cannot directly. Instead, VirtualBox has created a local port mapping automatically which should be used. There is no fixed, pre-determined port mapping that will be universally valid, as Vagrant and VirtualBox may be used together to run an arbitrary number of virtual machines simultaneously, each provisioned in any order, and defined by any number and variety of Vagrantfiles.
The correct way to determine what port Vagrant and VirtualBox have used to map to a given virtual machine is to run the following command from within the same directory as your Vagrantfile:
vagrant ssh-config <name>
That will output a configuration block, suitable for inclusion in your local
~/.ssh/config file. Note specifically, in addition to the port, the path to
the private key you will need to use as your identity when attempting to log
into the virtual machine.
Forwarding Custom Ports¶
Building Traffic Server Inside Vagrant¶
Producing Traffic Server builds from within the Vagrant managed virtual machines is
effectively no different than in any other environment. The same directory in
which the Vagrantfile exists will be mounted via NFS inside the virtual machine
at the path /opt/src/trafficserver.git.
Note
If you have run autoconf or configure from outside the virtual
machine environment against the same Git working copy as is mounted inside
the virtual machine, you will encounter failures should you attempt to run
any of the Make targets inside the VM. Any build related commands should be
run inside of the virtual machine. Additionally, if you are running more
than one virtual machine simultaneously, remember that they are each using
the same NFS export on your host machine.