Using existing virtual machines with Vagrant

Using Vagrant to create new environments for use up to this point has been pretty simple so far. In the previous recipes, we have downloaded existing Vagrant boxes, created new Vagrantfiles, and booted entirely new environments. This is a pretty suitable use for new software (or configuration) projects, or to possibly create environments in order to migrate existing projects. This isn't such a good workflow if your team or you have existing virtual environments in use (such as the virtual machine on a network share or a flash drive that is passed around between team members).

Fortunately, we can repackage existing environments to use with Vagrant, replacing the shared disk with a new box file. While box files are still essentially virtual machines, boxes can be published (and updated) and even have additional configuration applied after booting. These box files can make managing virtual machines and different versions of these virtual machines vastly simpler, especially, if you don't want to build environments from base boxes every time.

Getting ready

In this example, we'll assume that we have an existing virtual machine environment built with Oracle VirtualBox.

Note

Warning!

This example will use a VirtualBox-only feature to set up box packaging, as Vagrant has a built-in shortcut to package existing VirtualBox environments into box files. Creating Vagrant boxes for other platforms will be covered in later chapters.

In this example, I'll choose an existing environment based on the CentOS operating system that has been created as a VirtualBox machine. In this case, the virtual machine has a few properties we'll want to note:

• In this case, the virtual machine was created from an ISO installation of CentOS 6.5.
• There is a user account present on the machine that we want to reuse. The credentials are:

  Username	uaccount
  Password	passw0rd

• The machine is used as a development web server; we typically access the machine through terminal sessions (SSH).

  Note

  WARNING!

  We'll want to make sure that any machine that we will access using the vagrant ssh method has the SSH server daemon active and set to start on machine start. We'll also want to make one adjustment to the sshd configuration before packaging.

  With the machine created and active on a development workstation, the listing appears in the VirtualBox Manager console:

  

  If this machine boots locally and allows us to SSH into the machine normally, we can proceed to convert the virtual machine into a Vagrant box.

How to do it...

If we use an existing virtual machine with VirtualBox, we can use a few simple commands to export a new Vagrant box.

Packaging the VirtualBox machine

Before we can use the virtual machine with Vagrant, we need to package the machine into an appropriate box format.

1. Note the name that VirtualBox assigns to the machine. In this case, our virtual machine is named CentOS as displayed in the left-hand menu of the VM VirtualBox Manager console:
   
2. Create a temporary workspace to package the box. As with all Vagrant commands, you will do this on the command line. If you are working on a Unix machine (Linux or OS X), you can create a working directory with the mkdir ~/box-workspace command. This will create a folder in your home directory called box-workspace. Change directories to this workspace with cd ~/box-workspace.
3. Execute the packaging command. (Warning! This is for VirtualBox only.) This command is:

   vagrant package --base=CentOS --output=centos64.box
   

   We'll discuss a bit more about this in the following section. For now, Vagrant will return some text:

   ==> CentOS: Exporting VM...
   

   This command might take some time to execute; Vagrant is copying the existing VirtualBox machine into a box file along with some metadata that allows Vagrant to recognize the box file itself. When this command is finished, you'll end up with a single file called centos64.box in the working directory.

4. Import the box file into your environment. In this case, we will directly add the box for use to our local Vagrant environment so that we can proceed to test the new box with a Vagrantfile. It is also possible at this stage to simply publish the box to a web server for use by others, but it is highly recommended to attempt to boot the box and access it with an example Vagrantfile. Your users will appreciate it. Add the box with the command:

   vagrant box add centos64.box --name=centos64
   

   This command will copy the box to your local Vagrant cache, so you are now ready to directly use the box!

Configuring a Vagrant environment

Now that the box is added to our local cache, we'll need to configure a new Vagrant environment to use the box.

1. Initialize a new Vagrant environment with our new box. Do this by executing the vagrant init centos64 command. This will create a basic Vagrantfile that uses our new centos64 box.
2. Configure the Vagrantfile to use the correct user to SSH into the machine. We'll use the supplied username and password given in the preceding table. Edit the Vagrantfile created in the previous step to include two new lines that specify parameters for the config.ssh parameters:

   Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
     # All Vagrant configuration is done here. The most common configuration
     # options are documented and commented below. For a complete reference,
     # please see the online documentation at vagrantup.com.
   
     # Every Vagrant virtual environment requires a box to build off of.
     config.vm.box = "centos64"
     config.ssh.username="uaccount"
     config.ssh.password="passw0rd"

   By default, Vagrant relies on a common public key that is used by most box publishers that allows access to an account called vagrant. In this case, our environment will not have this key installed, we can instead configure the Vagrantfile to use a username and password. After the first login, Vagrant will place a key in the appropriate account; so, if desired, the password can be removed from the Vagrantfile after the first boot.

3. Boot the environment. You might need to specify the provider along with the vagrant up command:

   vagrant up --provider=virtualbox
   

   In this case, you will note quite a bit of output; the typical Vagrant boot messages along with some information about logging in with the password, replacing the password with the key, and so on. You might also (depending on how the box was packaged) see some information about Guest Additions. While Vagrant can use a virtual machine that has the guest additions disabled, some features (shared folders, port forwarding, and so on) rely on the VirtualBox guest additions to be installed. It's likely that your virtual machine has these already installed, especially if it has been used previously in a VirtualBox environment. Newly packaged boxes, however, will need to have the guest additions installed prior to packaging. (See the VirtualBox manual on the installation of guest additions at https://www.virtualbox.org/manual/ch04.html.)

Once the environment is booted, you can interact with the virtual machine, as you did previously, either through SSH or other services available on the machine.

How it works...

Using Vagrant with virtual machines is entirely dependent on the Vagrant box format. In this example, we used a built-in feature of Vagrant to export an existing VirtualBox environment into Vagrant. It's also possible to package box files for other environments, a topic we'll revisit later in the book. In this case, the package command generated a box file automatically.

The Vagrant box file is a file in a Unix Tape ARchive (TAR) format. If we untar the box file with the tar xvf centos64.box command, we can look at the contents of the box to see how it works. The following are the contents of the untarred file:

-rw-------  0 cothomps staff 1960775680 Jul 24 20:42 ./box-disk1.vmdk
-rw-------  0 cothomps staff      12368 Jul 24 20:38 ./box.ovf
-rw-r--r--  0 cothomps staff        505 Jul 24 20:42 ./Vagrantfile

So, the box file contains two files required to operate a VirtualBox virtual machine (the vmdk file that defines the virtual hard drive, and the ovf file that defines the properties of the virtual machine used by VirtualBox). The third file is a custom Vagrantfile that contains (primarily) the MAC address of the packaged virtual machine. There might also be custom files added to packaged boxes (such as metadata), describing the box or custom files required to operate the environment.