cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Documentation: Update the Vagrant Guide

Browse source 
This is an attempt to solve #7665.

Revert the change applied by f56a6e0951
(#12310), as the inventory generated by Vagrant still rely on the legacy
`_ssh` setting names for backwards compatibility reasons.
See also https://github.com/mitchellh/vagrant/issues/6570
This commit is contained in:
Gilles Cornu 2014-12-25 01:37:47 +01:00
parent 591c81e95f
commit dc60e08aa0
1 changed files with 86 additions and 65 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

145
docsite/rst/guide_vagrant.rst
View file

@ -6,12 +6,13 @@ Using Vagrant and Ansible
Introduction Introduction
```````````` ````````````
Vagrant is a tool to manage virtual machine environments, and allows you to `Vagrant <http://vagrantup.com/>`_ is a tool to manage virtual machine
configure and use reproducible work environments on top of various environments, and allows you to configure and use reproducible work
virtualization and cloud platforms. It also has integration with Ansible as a environments on top of various virtualization and cloud platforms.
provisioner for these virtual machines, and the two tools work together well. 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. 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 If you're not familiar with Vagrant, you should visit `the documentation
<http://docs.vagrantup.com/v2/>`_. <http://docs.vagrantup.com/v2/>`_.
@ -27,54 +28,48 @@ Vagrant Setup
The first step once you've installed Vagrant is to create a ``Vagrantfile`` 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 and customize it to suit your needs. This is covered in detail in the Vagrant
documentation, but here is a quick example: documentation, but here is a quick example that includes a section to use the
Ansible provisioner to manage a single machine:
.. 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 .. code-block:: ruby
# Vagrantfile API/syntax version. Don't touch unless you know what you're doing! # This guide is optimized for Vagrant 1.7 and above.
VAGRANTFILE_API_VERSION = "2" # 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(VAGRANTFILE_API_VERSION) do |config| Vagrant.configure(2) do |config|
config.vm.box = "precise32"
config.vm.box_url = "http://files.vagrantup.com/precise32.box"
config.vm.network :public_network config.vm.box = "ubuntu/trusty64"
config.vm.provision "ansible" do |ansible| # Disable the new default behavior introduced in Vagrant 1.7, to
ansible.playbook = "playbook.yml" # ensure that all Vagrant machines will use the same SSH key pair.
end # See https://github.com/mitchellh/vagrant/issues/5005
config.ssh.insert_key = false
config.vm.provision "ansible" do |ansible|
ansible.verbose = "v"
ansible.playbook = "playbook.yml"
end 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 Notice the ``config.vm.provision`` section that refers to an Ansible playbook
called ``playbook.yml`` in the same directory as the Vagrantfile. Vagrant runs called ``playbook.yml`` in the same directory as the ``Vagrantfile``. Vagrant
the provisioner once the virtual machine has booted and is ready for SSH runs the provisioner once the virtual machine has booted and is ready for SSH
access. access.
There are a lot of Ansible options you can configure in your ``Vagrantfile``.
Visit the `Ansible Provisioner documentation
<http://docs.vagrantup.com/v2/provisioning/ansible.html>`_ for more
information.
.. code-block:: bash .. code-block:: bash
$ vagrant up $ vagrant up
This will start the VM and run the provisioning playbook. This will start the VM, and run the provisioning playbook (on the first VM
startup).
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: To re-run a playbook on an existing VM, just run:
@ -82,7 +77,19 @@ To re-run a playbook on an existing VM, just run:
$ vagrant provision $ vagrant provision
This will re-run the playbook. 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:
.. code-block:: bash
$ 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: .. _running_ansible:
@ -90,44 +97,58 @@ Running Ansible Manually
```````````````````````` ````````````````````````
Sometimes you may want to run Ansible manually against the machines. This is Sometimes you may want to run Ansible manually against the machines. This is
pretty easy to do. faster than kicking ``vagrant provision`` and pretty easy to do.
Vagrant automatically creates an inventory file for each Vagrant machine in With our ``Vagrantfile`` example, Vagrant automatically creates an Ansible
the same directory located under ``.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory``. inventory file in ``.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory``.
It configures the inventory file according to the SSH tunnel that Vagrant This inventory is configured according to the SSH tunnel that Vagrant
automatically creates, and executes ``ansible-playbook`` with the correct automatically creates. A typical automatically-created inventory file for a
username and SSH key options to allow access. A typical automatically-created single machine environment may look something like this:
inventory file may look something like this:
.. code-block:: none .. code-block:: none
# Generated by Vagrant # Generated by Vagrant
machine ansible_host=127.0.0.1 ansible_port=2222 default ansible_ssh_host=127.0.0.1 ansible_ssh_port=2222
.. include:: ansible_ssh_changes_note.rst
If you want to run Ansible manually, you will want to make sure to pass 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 ``ansible`` or ``ansible-playbook`` commands the correct arguments, at least
username (usually ``vagrant``) and the SSH key (since Vagrant 1.7.0, this will be something like for the *username*, the *SSH private key* and the *inventory*.
``.vagrant/machines/[machine name]/[provider]/private_key``), and the autogenerated inventory file.
Here is an example: Here is an example using the Vagrant global insecure key (``config.ssh.insert_key``
must be set to ``false`` in your ``Vagrantfile``):
.. code-block:: bash .. code-block:: bash
$ ansible-playbook -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory --private-key=.vagrant/machines/default/virtualbox/private_key -u vagrant playbook.yml $ ansible-playbook --private-key=~/.vagrant.d/insecure_private_key -u vagrant -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory playbook.yml
Note: Vagrant versions prior to 1.7.0 will use the private key located at ``~/.vagrant.d/insecure_private_key.`` 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``):
.. code-block:: bash
$ 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
<http://docs.vagrantup.com/v2/provisioning/ansible.html>`_ 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
.. seealso:: .. seealso::
`Vagrant Home <http://www.vagrantup.com/>`_ `Vagrant Home <http://www.vagrantup.com/>`_
The Vagrant homepage with downloads The Vagrant homepage with downloads
`Vagrant Documentation <http://docs.vagrantup.com/v2/>`_ `Vagrant Documentation <http://docs.vagrantup.com/v2/>`_
Vagrant Documentation Vagrant Documentation
`Ansible Provisioner <http://docs.vagrantup.com/v2/provisioning/ansible.html>`_ `Ansible Provisioner <http://docs.vagrantup.com/v2/provisioning/ansible.html>`_
The Vagrant documentation for the Ansible provisioner The Vagrant documentation for the Ansible provisioner
:doc:`playbooks` `Vagrant Issue Tracker <https://github.com/mitchellh/vagrant/issues?q=is%3Aopen+is%3Aissue+label%3Aprovisioners%2Fansible>`_
An introduction to playbooks The open issues for the Ansible provisioner in the Vagrant project
:doc:`playbooks`
An introduction to playbooks