Merge pull request #5033 from tgerla/vagrantguide

Add a basic guide describing Vagrant and Ansible

2 files changed, 134 insertions, 1 deletions

diff --git a/docsite/rst/guide_vagrant.rst b/docsite/rst/guide_vagrant.rst
new file mode 100644
index 0000000000..dc861b9153
--- /dev/null
+++ b/docsite/rst/guide_vagrant.rst
@@ -0,0 +1,132 @@
+Using Vagrant and Ansible
+=========================
+
+.. contents::
+   :depth: 2
+
+.. _vagrant_intro:
+
+Introduction
+````````````
+
+Vagrant is a tool to manage virtual machine environments, and allows you to
+configure and use reproducable 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 familar 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 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
+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 insecure_private_key --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
+
diff --git a/docsite/rst/index.rst b/docsite/rst/index.rst
index ae29a5c7f5..30b0177f90 100644
--- a/docsite/rst/index.rst
+++ b/docsite/rst/index.rst
@@ -138,8 +138,9 @@ This section is new and evolving.  The idea here is explore particular use cases
    :maxdepth: 1
 
    guide_aws
+   guide_vagrant
 
-Pending topics may include: Vagrant, Docker, Jenkins, Rackspace Cloud, Google Compute Engine, Linode/Digital Ocean, Continous Deployment, and more.
+Pending topics may include: Docker, Jenkins, Rackspace Cloud, Google Compute Engine, Linode/Digital Ocean, Continous Deployment, and more.
 
 .. _community_information: