vagrant/website/docs/source/v2/provisioning/ansible.html.md

sidebar_current
provisioning-ansible

Ansible Provisioner

Provisioner name: :ansible

The ansible provisioner allows you to provision the guest using Ansible playbooks.

Ansible playbooks are YAML documents that comprise the set of steps to be orchestrated on one or more machines. This documentation page will not go into how to use Ansible or how to write Ansible playbooks, since Ansible is a complete deployment and configuration management system that is beyond the scope of a single page of documentation.

Inventory File

Out of the box, Ansible can control with multiple systems in your infrastructure at the same time. It does this by selecting portions of systems listed in Ansible's inventory INI formatted file, which defaults to being located at /etc/ansible/hosts. This same file can be used with Vagrant, or the ansible.inventory_file option can be specified to direct Vagrant to use an inventory file dedicated to your Vagrant project. Using this option is recommended to avoid accidentally running playbooks against live infrastructure. A simple inventory file for use with Vagrant might look like:

[vagrant]
192.168.111.222

Where the above IP address is one set in your Vagrantfile:

config.vm.network :private_network, ip: "192.168.111.222"

(While Vagrant does have the IP address of your VM, entering it into an Ansible inventory file is preferred so that Ansible's group_vars and host_vars can be used; Their location is derived from the location of the inventory file.)

Playbook

The second component of a successful Ansible provisioner setup is the Ansible playbook which contains the steps that should be run on the guest. Ansible's playbook documentation goes into great detail on how to author playbooks, and there are a number of best practices that can be applied to use Ansible's powerful features effectively. A playbook that installs and starts (or restarts if it was updated) the NTP daemon via YUM looks like:

---
- hosts: vagrant
  tasks:
    - name: ensure ntpd is at the latest version
      yum: pkg=ntp state=latest
      notify:
      - restart ntpd
  handlers:
    - name: restart ntpd
      service: name=ntpd state=restarted

You can of course target other operating systems that don't have YUM by changing the playbook tasks. Ansible ships with a number of modules that make running otherwise tedious tasks dead simple.

Running Ansible

To run Ansible against your Vagrant guest, the basic Vagrantfile configuration looks like:

Vagrant.configure("2") do |config|
  config.vm.provision :ansible do |ansible|
    ansible.playbook = "playbook.yml"
    ansible.inventory_file = "ansible_hosts"
  end
end

This causes Vagrant to run the playbook.yml playbook against the vagrant group in the ansible_hosts file, both of which are adjacent to the Vagrantfile. Since an Ansible playbook can include many files, you may also collect the related files in a directory structure like this:

$ tree
.
|-- Vagrantfile
|-- provisioning
|   |-- ansible_hosts
|   |-- group_vars
|           |-- vagrant
|   |-- playbook.yml

In such an arrangement, the ansible.playbook and ansible.inventory_file options should be adjusted accordingly:

Vagrant.configure("2") do |config|
  config.vm.provision :ansible do |ansible|
    ansible.playbook = "provisioning/playbook.yml"
    ansible.inventory_file = "provisioning/ansible_hosts"
  end
end

Additional Options

The Ansible provisioner also includes a number of additional options that can be set, all of which get passed to the ansible-playbook command that ships with Ansible.

• ansible.extra_vars can be used to pass a hash of additional variables to the playbook. For example:

ansible.extra_vars = {
  ntp_server: "pool.ntp.org",
  nginx_workers: 4
}

These variables take the highest precedence over any other variables.

• ansible.sudo can be set to true to cause Ansible to perform commands using sudo.
• ansible.sudo_user can be set to a string containing a username on the guest who should be used by the sudo command.
• ansible.ask_sudo_pass can be set to true to require Ansible to prompt for a sudo password.
• ansible.limit can be set to a string or an array of machines or groups from the inventory file to further narrow down which hosts are affected. This option is best used in the case where you are using an inventory file containing more than just the Vagrant guest.
• ansible.verbose can be set to true to increase Ansible's verbosity to obtain more detailed logging during playbook execution.