From 7adf33ed41e18dbaf3e60506d1d3d8cbcd51bdd3 Mon Sep 17 00:00:00 2001 From: Tim Gerla Date: Sat, 23 Nov 2013 11:07:51 -0800 Subject: [PATCH 1/4] add a topical guide for Vagrant integration --- docsite/rst/guide_vagrant.rst | 92 +++++++++++++++++++++++++++++++++++ docsite/rst/index.rst | 1 + 2 files changed, 93 insertions(+) create mode 100644 docsite/rst/guide_vagrant.rst diff --git a/docsite/rst/guide_vagrant.rst b/docsite/rst/guide_vagrant.rst new file mode 100644 index 00000000000..f10f08056c4 --- /dev/null +++ b/docsite/rst/guide_vagrant.rst @@ -0,0 +1,92 @@ +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 `_. + +.. _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. Visit the `Ansible Provisioner documentation `_ for more information. + +.. _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. + +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" 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 `_ + The Vagrant homepage with downloads + `Vagrant Documentation `_ + Vagrant Documentation + `Ansible Provisioner `_ + 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 ae29a5c7f5c..f910f8fdbdf 100644 --- a/docsite/rst/index.rst +++ b/docsite/rst/index.rst @@ -138,6 +138,7 @@ 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. From 1cd71b7899d0ba562195cea13826ba15b3225106 Mon Sep 17 00:00:00 2001 From: Tim Gerla Date: Sat, 23 Nov 2013 11:10:43 -0800 Subject: [PATCH 2/4] fix up word wrapping --- docsite/rst/guide_vagrant.rst | 43 +++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/docsite/rst/guide_vagrant.rst b/docsite/rst/guide_vagrant.rst index f10f08056c4..11c9872adfc 100644 --- a/docsite/rst/guide_vagrant.rst +++ b/docsite/rst/guide_vagrant.rst @@ -9,18 +9,24 @@ Using Vagrant and Ansible 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. +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 `_. +If you're not familar with Vagrant, you should visit `the documentation +`_. .. _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: +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 @@ -28,7 +34,9 @@ The first step once you've installed Vagrant is to create a Vagrantfile and cust $ 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: +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 @@ -46,7 +54,11 @@ This will create a file called Vagrantfile that you can edit to suit your needs. 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. +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 @@ -54,16 +66,26 @@ The Vagrantfile has a lot of options, but these are the most important ones. Not This will start the VM and run the provisioning playbook. -There are a lot of Ansible options you can configure in your Vagrantfile. Visit the `Ansible Provisioner documentation `_ for more information. +There are a lot of Ansible options you can configure in your Vagrantfile. +Visit the `Ansible Provisioner documentation +`_ for more +information. .. _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. +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. -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: +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 @@ -71,7 +93,10 @@ Vagrant automatically creates an inventory file for each Vagrant machine in the 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. +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. Here is an example: From 461afa2b25cb416b9e31d26d00cdcab9dba8173f Mon Sep 17 00:00:00 2001 From: Tim Gerla Date: Sat, 23 Nov 2013 11:13:56 -0800 Subject: [PATCH 3/4] remove Vagrant from the list of pending topics --- docsite/rst/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docsite/rst/index.rst b/docsite/rst/index.rst index f910f8fdbdf..30b0177f90c 100644 --- a/docsite/rst/index.rst +++ b/docsite/rst/index.rst @@ -140,7 +140,7 @@ This section is new and evolving. The idea here is explore particular use cases 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: From fb3d5d65897e6bc3deeed6f38cbc0bfe845cfa1f Mon Sep 17 00:00:00 2001 From: Tim Gerla Date: Sat, 23 Nov 2013 14:59:35 -0800 Subject: [PATCH 4/4] 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 11c9872adfc..dc861b9153e 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: