- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# Vagrant Guide

## 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 1.7+ 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 Installation Guide 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 that includes a section to use the Ansible provisioner to manage a single machine:

    # This guide is optimized for Vagrant 1.7 and above.
    # Although versions 1.6.x should behave very similarly, it is recommended
    # to upgrade instead of disabling the requirement below.
    Vagrant.require_version ">= 1.7.0"

    Vagrant.configure(2) do |config|

      config.vm.box = "ubuntu/trusty64"

      # Disable the new default behavior introduced in Vagrant 1.7, to
      # ensure that all Vagrant machines will use the same SSH key pair.
      # See https://github.com/hashicorp/vagrant/issues/5005
      config.ssh.insert_key = false

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

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.

There are a lot of Ansible options you can configure in your `Vagrantfile`. Visit the Ansible Provisioner documentation for more information.

    $ vagrant up

This will start the VM, and run the provisioning playbook (on the first VM startup).

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

    $ vagrant provision

This will re-run the playbook against the existing VM.

Note that having the `ansible.verbose` option enabled will instruct Vagrant to show the full `ansible-playbook` command used behind the scene, as illustrated by this example:

    $ PYTHONUNBUFFERED=1 ANSIBLE_FORCE_COLOR=true ANSIBLE_HOST_KEY_CHECKING=false ANSIBLE_SSH_ARGS='-o UserKnownHostsFile=/dev/null -o ControlMaster=auto -o ControlPersist=60s' ansible-playbook --private-key=/home/someone/.vagrant.d/insecure_private_key --user=vagrant --connection=ssh --limit='machine1' --inventory-file=/home/someone/coding-in-a-project/.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory playbook.yml

This information can be quite useful to debug integration issues and can also be used to manually execute Ansible from a shell, as explained in the next section.

## Running Ansible Manually

Sometimes you may want to run Ansible manually against the machines. This is faster than kicking `vagrant provision` and pretty easy to do.

With our `Vagrantfile` example, Vagrant automatically creates an Ansible inventory file in `.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory`. This inventory is configured according to the SSH tunnel that Vagrant automatically creates. A typical automatically-created inventory file for a single machine environment may look something like this:

    # Generated by Vagrant

    default 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, at least for the username, the SSH private key and the inventory.

Here is an example using the Vagrant global insecure key (`config.ssh.insert_key` must be set to `false` in your `Vagrantfile`):

    $ ansible-playbook --private-key=~/.vagrant.d/insecure_private_key -u vagrant -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory playbook.yml

Here is a second example using the random private key that Vagrant 1.7+ automatically configures for each new VM (each key is stored in a path like `.vagrant/machines/[machine name]/[provider]/private_key`):

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

## Advanced Usages

The “Tips and Tricks” chapter of the Ansible Provisioner documentation provides detailed information about more advanced Ansible features like:

> - how to parallely execute a playbook in a multi-machine environment
> - how to integrate a local `ansible.cfg` configuration file

See also

Vagrant Home
  The Vagrant homepage with downloads
Vagrant Documentation
  Vagrant Documentation
Ansible Provisioner
  The Vagrant documentation for the Ansible provisioner
Vagrant Issue Tracker
  The open issues for the Ansible provisioner in the Vagrant project
Working With Playbooks
  An introduction to playbooks