ansible/docsite/rst/guide_vagrant.rst

130 lines
4.3 KiB
ReStructuredText
Raw Normal View History

Using Vagrant and Ansible
=========================
.. _vagrant_intro:
Introduction
````````````
2013-11-23 20:10:43 +01:00
Vagrant is a tool to manage virtual machine environments, and allows you to
2014-03-31 01:45:55 +02:00
configure and use reproducible work environments on top of various
2013-11-23 20:10:43 +01:00
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
2013-11-23 20:10:43 +01:00
<http://docs.vagrantup.com/v2/>`_.
2013-11-23 23:59:35 +01:00
This guide assumes that you already have Ansible installed and working.
Running from a Git checkout is fine. Follow the :doc:`intro_installation`
guide for more information.
.. _vagrant_setup:
Vagrant Setup
`````````````
2013-11-23 23:59:35 +01:00
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
2013-11-23 20:10:43 +01:00
documentation, but here is a quick example:
.. code-block:: bash
$ mkdir vagrant-test
$ cd vagrant-test
$ vagrant init precise32 http://files.vagrantup.com/precise32.box
2013-11-23 20:10:43 +01:00
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:
.. code-block:: 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|
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
2013-11-23 20:10:43 +01:00
The Vagrantfile has a lot of options, but these are the most important ones.
2013-11-23 23:59:35 +01:00
Notice the ``config.vm.provision`` section that refers to an Ansible playbook
called ``playbook.yml`` in the same directory as the Vagrantfile. Vagrant runs
2013-11-23 20:10:43 +01:00
the provisioner once the virtual machine has booted and is ready for SSH
access.
.. code-block:: bash
$ vagrant up
This will start the VM and run the provisioning playbook.
2013-11-23 23:59:35 +01:00
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.
2013-11-23 20:10:43 +01:00
Visit the `Ansible Provisioner documentation
<http://docs.vagrantup.com/v2/provisioning/ansible.html>`_ for more
information.
2013-11-23 23:59:35 +01:00
To re-run a playbook on an existing VM, just run:
.. code-block:: bash
$ vagrant provision
This will re-run the playbook.
.. _running_ansible:
Running Ansible Manually
````````````````````````
2013-11-23 23:59:35 +01:00
Sometimes you may want to run Ansible manually against the machines. This is
pretty easy to do.
2013-11-23 20:10:43 +01:00
Vagrant automatically creates an inventory file for each Vagrant machine in
2013-11-23 23:59:35 +01:00
the same directory called ``vagrant_ansible_inventory_machinename``. It
2013-11-23 20:10:43 +01:00
configures the inventory file according to the SSH tunnel that Vagrant
2013-11-23 23:59:35 +01:00
automatically creates, and executes ``ansible-playbook`` with the correct
2013-11-23 20:10:43 +01:00
username and SSH key options to allow access. A typical automatically-created
inventory file may look something like this:
.. code-block:: none
# Generated by Vagrant
machine ansible_ssh_host=127.0.0.1 ansible_ssh_port=2222
2013-11-23 20:10:43 +01:00
If you want to run Ansible manually, you will want to make sure to pass
2013-11-23 23:59:35 +01:00
``ansible`` or ``ansible-playbook`` commands the correct arguments for the
username (usually ``vagrant``) and the SSH key (usually
``~/.vagrant.d/insecure_private_key``), and the autogenerated inventory file.
Here is an example:
.. code-block:: bash
$ ansible-playbook -i vagrant_ansible_inventory_machinename --private-key=~/.vagrant.d/insecure_private_key -u vagrant playbook.yml
.. seealso::
`Vagrant Home <http://www.vagrantup.com/>`_
The Vagrant homepage with downloads
`Vagrant Documentation <http://docs.vagrantup.com/v2/>`_
Vagrant Documentation
`Ansible Provisioner <http://docs.vagrantup.com/v2/provisioning/ansible.html>`_
The Vagrant documentation for the Ansible provisioner
:doc:`playbooks`
An introduction to playbooks