ansible/docsite/rst/guide_vagrant.rst

Using Vagrant and Ansible

Introduction

Vagrant is a tool to manage virtual machine environments, and allows you to configure and use reproducible work environments on top of various virtualization and cloud platforms. It also has integration with Ansible as a provisioner for these virtual machines, and the two tools work together well.

This guide will describe how to use Vagrant and Ansible together.

If you're not familiar with Vagrant, you should visit the documentation.

This guide assumes that you already have Ansible installed and working. Running from a Git checkout is fine. Follow the intro_installation guide for more information.

Vagrant Setup

The first step once you've installed Vagrant is to create a Vagrantfile and customize it to suit your needs. This is covered in detail in the Vagrant documentation, but here is a quick example:

$ mkdir vagrant-test
$ cd vagrant-test
$ vagrant init precise32 http://files.vagrantup.com/precise32.box

This will create a file called Vagrantfile that you can edit to suit your needs. The default Vagrantfile has a lot of comments. Here is a simplified example that includes a section to use the Ansible provisioner:

# 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|
    config.vm.box = "precise32"
    config.vm.box_url = "http://files.vagrantup.com/precise32.box"

    config.vm.network :public_network

    config.vm.provision "ansible" do |ansible|
        ansible.playbook = "playbook.yml"
    end
end

The Vagrantfile has a lot of options, but these are the most important ones. Notice the config.vm.provision section that refers to an Ansible playbook called playbook.yml in the same directory as the Vagrantfile. Vagrant runs the provisioner once the virtual machine has booted and is ready for SSH access.

$ vagrant up

This will start the VM and run the provisioning playbook.

There are a lot of Ansible options you can configure in your Vagrantfile. Some particularly useful options are ansible.extra_vars, ansible.sudo and ansible.sudo_user, and ansible.host_key_checking which you can disable to avoid SSH connection problems to new virtual machines.

Visit the Ansible Provisioner documentation for more information.

To re-run a playbook on an existing VM, just run:

$ vagrant provision

This will re-run the playbook.

Running Ansible Manually

Sometimes you may want to run Ansible manually against the machines. This is pretty easy to do.

Vagrant automatically creates an inventory file for each Vagrant machine in the same directory located under .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory. It configures the inventory file according to the SSH tunnel that Vagrant automatically creates, and executes ansible-playbook with the correct username and SSH key options to allow access. A typical automatically-created inventory file may look something like this:

# Generated by Vagrant

machine ansible_ssh_host=127.0.0.1 ansible_ssh_port=2222

If you want to run Ansible manually, you will want to make sure to pass ansible or ansible-playbook commands the correct arguments for the username (usually vagrant) and the SSH key (since Vagrant 1.7.0, this will be something like .vagrant/machines/[machine name]/[provider]/private_key), and the autogenerated inventory file.

Here is an example:

$ ansible-playbook -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory --private-key=.vagrant/machines/default/virtualbox/private_key -u vagrant playbook.yml

Note: Vagrant versions prior to 1.7.0 will use the private key located at ~/.vagrant.d/insecure_private_key.

Vagrant Home

The Vagrant homepage with downloads

Vagrant Documentation

Vagrant Documentation

Ansible Provisioner

The Vagrant documentation for the Ansible provisioner

playbooks

An introduction to playbooks