From fb3d5d65897e6bc3deeed6f38cbc0bfe845cfa1f Mon Sep 17 00:00:00 2001 From: Tim Gerla Date: Sat, 23 Nov 2013 14:59:35 -0800 Subject: [PATCH] elaborate on a couple of sections --- docsite/rst/guide_vagrant.rst | 41 ++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/docsite/rst/guide_vagrant.rst b/docsite/rst/guide_vagrant.rst index 11c9872adf..dc861b9153 100644 --- a/docsite/rst/guide_vagrant.rst +++ b/docsite/rst/guide_vagrant.rst @@ -19,13 +19,17 @@ This guide will describe how to use Vagrant and Ansible together. If you're not familar with Vagrant, you should visit `the documentation `_. +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 +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 @@ -55,8 +59,8 @@ example that includes a section to use the Ansible provisioner: 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 +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. @@ -66,24 +70,35 @@ access. This will start the VM and run the provisioning playbook. -There are a lot of Ansible options you can configure in your Vagrantfile. +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 `_ 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 ```````````````````````` -You can re-run the Ansible playbook for your Vagrant machine by running -"vagrant provision", but sometimes you may want to run Ansible manually -against the machines. This is pretty easy to do. +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 called "vagrant_ansible_inventory_machinename". It +the same directory called ``vagrant_ansible_inventory_machinename``. It configures the inventory file according to the SSH tunnel that Vagrant -automatically creates, and executes "ansible-playbook" with the correct +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: @@ -94,9 +109,9 @@ inventory file may look something like this: 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" the correct arguments for the username -(usually "vagrant") and the SSH key (usually -"~/.vagrant.d/insecure_private_key"), and the autogenerated inventory file. +``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: