mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
18b41ebda5
according to the official Vagrant guide at http://docs.vagrantup.com/v2/provisioning/ansible.html
129 lines
4.3 KiB
ReStructuredText
129 lines
4.3 KiB
ReStructuredText
Using Vagrant and Ansible
|
|
=========================
|
|
|
|
.. _vagrant_intro:
|
|
|
|
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
|
|
<http://docs.vagrantup.com/v2/>`_.
|
|
|
|
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
|
|
`````````````
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ 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:
|
|
|
|
.. 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
|
|
|
|
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.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ 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
|
|
<http://docs.vagrantup.com/v2/provisioning/ansible.html>`_ for more
|
|
information.
|
|
|
|
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
|
|
````````````````````````
|
|
|
|
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:
|
|
|
|
.. code-block:: none
|
|
|
|
# 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 (usually
|
|
``~/.vagrant.d/insecure_private_key``), and the autogenerated inventory file.
|
|
|
|
Here is an example:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ ansible-playbook -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory --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
|
|
|