Documentation: Update the Vagrant Guide

This is an attempt to solve #7665.

Revert the change applied by f56a6e0951af9ae68106a8f9569cc375f53d5b52
(#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

1 files changed, 85 insertions, 64 deletions

diff --git a/docsite/rst/guide_vagrant.rst b/docsite/rst/guide_vagrant.rst
index 2aad2f1a03..e5870bdd85 100644
--- a/docsite/rst/guide_vagrant.rst
+++ b/docsite/rst/guide_vagrant.rst
@@ -6,12 +6,13 @@ Using Vagrant and Ansible
 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.
+`Vagrant <http://vagrantup.com/>`_ 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.
+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
 <http://docs.vagrantup.com/v2/>`_.
@@ -27,54 +28,48 @@ 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:
+documentation, but here is a quick example that includes a section to use the
+Ansible provisioner to manage a single machine:
 
-.. code-block:: bash
+.. code-block:: ruby
 
-    $ mkdir vagrant-test
-    $ cd vagrant-test
-    $ vagrant init precise32 http://files.vagrantup.com/precise32.box
+  # 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"
 
-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:
+  Vagrant.configure(2) do |config|
 
-.. code-block:: ruby
+    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/mitchellh/vagrant/issues/5005
+    config.ssh.insert_key = false
 
-    # 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
+    config.vm.provision "ansible" do |ansible|
+      ansible.verbose = "v"
+      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
+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
+<http://docs.vagrantup.com/v2/provisioning/ansible.html>`_ for more
+information.
+
 .. 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.
+This will start the VM, and run the provisioning playbook (on the first VM
+startup).
 
-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:
 
@@ -82,7 +77,19 @@ To re-run a playbook on an existing VM, just run:
 
     $ 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:
 
@@ -90,44 +97,58 @@ Running Ansible Manually
 ````````````````````````
 
 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
-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:
+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:
 
 .. code-block:: none
 
     # Generated by Vagrant
 
-    machine ansible_host=127.0.0.1 ansible_port=2222
-
-.. include:: ansible_ssh_changes_note.rst
+    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 for the
-username (usually ``vagrant``) and the SSH key (since Vagrant 1.7.0, this will be something like
-``.vagrant/machines/[machine name]/[provider]/private_key``), and the autogenerated inventory file.
+``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``):
 
-Here is an example:
+.. code-block:: bash
+
+    $ 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``):
 
 .. 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
 
-Note: Vagrant versions prior to 1.7.0 will use the private key located at ``~/.vagrant.d/insecure_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
+<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::
 
-   `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
+    `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
+    `Vagrant Issue Tracker <https://github.com/mitchellh/vagrant/issues?q=is%3Aopen+is%3Aissue+label%3Aprovisioners%2Fansible>`_
+        The open issues for the Ansible provisioner in the Vagrant project
+    :doc:`playbooks`
+        An introduction to playbooks