Once we have a working Vagrant environment with a hypervisor, we can initialize our first environment. There are two ways with which we can often work with Vagrant:
In a new environment with a newly initialized Vagrantfile
In an environment maintained in source control that has a Vagrantfile included in a project
Keeping Vagrantfiles and projects in a source control system (such as Git, SVN, and so on) is a powerful technique to manage and track changes in Vagrant environments. The use of source control systems allows developers and users to check in Vagrant projects, which makes modification of the project less risky and makes the sharing of Vagrant projects much simpler. The use of source code repositories reinforces the concept of infrastructure as code, giving administrators the ability to recreate environments in a consistent and repeatable way.
No matter how you use Vagrant, knowing how to initialize a new environment will aid you to effectively use Vagrant. In this example, we will initialize a new environment and look at the basic configuration of a Vagrantfile.
We've seen in the previous section that Vagrant itself is a command-line-driven application. There are some GUI tools available that can help start and stop environments, but in order to truly understand how Vagrant works, we'll use the command-line interface to initialize and interact with our environment.
For this example (and others in the book), you'll need to open a terminal window (a Unix terminal program in Mac OS X, or Linux, or the windows command application). Verify that Vagrant is installed by typing the command:
vagrant version
A full example of what the command-line session would look like is given in the following screenshot:
If you encounter errors or if the system cannot find Vagrant, you might either need to repeat the installation steps to install Vagrant in the previous recipe, or adjust your system path to include Vagrant. In most cases, the installer should complete this step for you.
Before proceeding with this first command, you might also want to make sure that your desktop machine is connected to the Internet with a fairly reliable and fast connection. In this example, you will be downloading a Vagrant box file that can be a few hundred megabytes in size. (Using a 12 MB/s download connection, I often note that Vagrant box downloads can take between 6 to 10 minutes on average.)
Once you've verified your command-line environment, we can proceed to initialize our first environment.
With a terminal window open and the command getting executed in a directory of your choice, run the command:
vagrant init puppetlabs/ubuntu-14.04-32-nocm
This command should return a brief text summary of your action, informing you that a new Vagrantfile has been created in the current directory. With this file in place, execute the command:
vagrant up
This command might output several results; we'll note a few important ones:
A status message indicating that the default machine is being started with the VirtualBox provider.
If you are running this command for the first time, a message will also be displayed noting that the box (in this case,
puppetlabs/ubuntu-14.04-32-no-cm) cannot be found. Vagrant will automatically attempt to download a box file. This might take a while depending on the bandwidth available between you and the box provider. After starting a box for the first time, Vagrant will cache the box file itself so that subsequent uses of the box (even for different Vagrantfiles) will not trigger the download.After the box file is downloaded, you should see messages that note machine startup, port forwarding, shared folders, and networking.
After Vagrant returns to the command line, executing the vagrant ssh command will open a command-line interface in the newly initialized virtual machine. In this example, the operating system is Ubuntu 14.04, which is specified in the return prompt:
With the virtual machine running, feel free to modify the machine—create files, install programs, or make any modifications you wish. Once you are finished with this environment, log out of the virtual machine either with a control-d command, or by typing exit. At this point, we can either keep the machine active as a background process or we might wish to:
Stop the machine, keeping the environment available for later use. This is accomplished with the
vagrant haltcommand.Destroy the machine, discarding the entire working environment. This is accomplished with the
vagrant destroycommand.
In this example, we'll discard the virtual machine by typing vagrant destroy.
Vagrant will now prompt you to make sure that you want to destroy the environment; type y to proceed with destroying the environment and deleting the VM. The entire machine can be recreated in this directory again with the vagrant up command.
What we've done in this example is use Vagrant to create and destroy a virtual machine—an instance of Ubuntu running within the VirtualBox hypervisor. The information that Vagrant requires to create the environment is stored in a special type of file called a Vagrantfile. While Vagrantfiles can grow to become quite complex, this Vagrantfile contains only a few basic items of configuration.
Let's open the Vagrantfile we've created to see what our basic configuration instructs Vagrant to do. The first thing you'll notice when opening this file is that the initial Vagrantfile contains quite a bit of instruction on how to use the file—from box definitions to provisioning instructions. The only parts of the initial file that are not commented are:
A definition of the Vagrant environment itself
A definition of the box that serves as the base template of the environment itself
The opening of the Vagrantfile looks like this:
# -*- mode: ruby -*- # vi: set ft=ruby : # Vagrantfile API/syntax version. Don't touch unless you know what you're doing! VAGRANTFILE_API_VERSION = "2" 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 = "puppetlabs/ubuntu-14.04-32-nocm" …
Tip
Downloading the example code
You can download the example code files from your account at http://www.packtpub.com for all the Packt Publishing books you have purchased. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
You might notice a few features of the Vagrantfile itself:
Take note that the Vagrantfile uses the syntax of the Ruby programming language (http://ruby-lang.org). In fact, the Vagrantfile itself is Ruby code—something we'll use later on when we create more complex Vagrantfiles.
The Vagrantfile uses an API version. In this case, version 2: the most current version. Version 1 Vagrantfiles can still be found in use in a few projects as Vagrant itself can be backwards compatible. For most new projects, however, the latest revision of the API will be the one that is used.
The sole line of uncommented code is the definition of the
config.vm.boxparameter. This parameter was initialized with ourinitcommand that used this box name as a parameter. If we wished to change the base box for our project, we could do that in the definition of theconfig.vm.boxparameter.
This Vagrantfile can be expanded to include more complex requirements, which will be explored in later recipes.