Merge branch 'docs' of git://github.com/angstwad/ansible into devel

docsite/rst/guide_rax.rst

@@ -11,7 +11,7 @@ Introduction
 Ansible contains a number of core modules for interacting with Rackspace Cloud.  
 
 The purpose of this section is to explain how to put Ansible modules together 
-(and use inventory scripts) to use Ansible in Rackspace Cloud context.
+(and use inventory scripts) to use Ansible in a Rackspace Cloud context.
 
 Prerequisites for using the rax modules are minimal.  In addition to ansible itself, 
 all of the modules require and are tested against pyrax 1.5 or higher. 
@@ -32,7 +32,7 @@ to add localhost to the inventory file.  (Ansible may not require this manual st
     [localhost]
     localhost ansible_connection=local
 
-In playbook steps we'll typically be using the following pattern:
+In playbook steps, we'll typically be using the following pattern:
 
 .. code-block:: yaml
 
@@ -66,21 +66,17 @@ https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authentic
 Running from a Python Virtual Environment (Optional)
 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-Special considerations need to 
-be taken if pyrax is not installed globally but instead using a python virtualenv (it's fine if you install it globally).  
-
-Ansible assumes, unless otherwise instructed, that the python binary will live at 
-/usr/bin/python.  This is done so via the interpret line in the modules, however 
-when instructed using ansible_python_interpreter, ansible will use this specified path instead for finding 
-python.
-
-If using virtualenv, you may wish to modify your localhost inventory definition to find this location as follows:
+There are special considerations when Ansible is installed to a Python virtualenv, rather than the default of installing at a global scope. Ansible assumes, unless otherwise instructed, that the python binary will live at /usr/bin/python.  This is done so via the interpret line in modules, however when instructed using ansible_python_interpreter, Ansible will use this specified path instead to find Python.   **This is a common cause of module failures**, because the user assumes that modules running on 'localhost', or perhaps running via 'local_action' are using the virtualenv Python interpreter.  By setting this line in the inventory, the modules will execute in the virtualenv interpreter and have available the virtualenv packages, specifically pyrax. If using virtualenv, you may wish to modify your localhost inventory definition to find this location as follows:
 
 .. code-block:: ini
 
     [localhost]
     localhost ansible_connection=local ansible_python_interpreter=/path/to/ansible_venv/bin/python
 
+.. note::
+
+    pyrax may be installed in the global Python package scope or in a virtual environment.  There are no special considerations to keep in mind when installing pyrax.
+
 .. _provisioning:
 
 Provisioning
@@ -88,16 +84,20 @@ Provisioning
 
 Now for the fun parts.
 
-The 'rax' module provides the ability to provision instances within Rackspace Cloud.  Typically the 
-provisioning task will be performed from your Ansible control server against the Rackspace cloud API.
+The 'rax' module provides the ability to provision instances within Rackspace Cloud.  Typically the provisioning task will be performed from your Ansible control server (in our example, localhost) against the Rackspace cloud API.  This is done for several reasons:
+
+    - Avoiding installing the pyrax library on remote nodes
+    - No need to encrypt and distribute credentials to remote nodes
+    - Speed and simplicity
 
 .. note::
 
    Authentication with the Rackspace-related modules is handled by either 
    specifying your username and API key as environment variables or passing
-   them as module arguments.
+   them as module arguments, or by specifying the location of a credentials
+   file.
 
-Here is a basic example of provisioning a instance in ad-hoc mode:
+Here is a basic example of provisioning an instance in ad-hoc mode:
 
 .. code-block:: bash
 
@@ -119,8 +119,9 @@ Here's what it would look like in a playbook, assuming the parameters were defin
             wait: yes
         register: rax
 
-By registering the return value of the step, it is then possible to dynamically add the resulting hosts to inventory (temporarily, in memory).
-This facilitates performing configuration actions on the hosts immediately in a subsequent task::
+The rax module returns data about the nodes it creates, like IP addresses, hostnames, and login passwords.  By registering the return value of the step, it is possible used this data to dynamically add the resulting hosts to inventory (temporarily, in memory). This facilitates performing configuration actions on the hosts in a follow-on task.  In the following example, the servers that were successfully created using the above task are dynamically added to a group called "raxhosts", with each nodes hostname, IP address, and root password being added to the inventory.
+
+.. code-block:: yaml
 
     - name: Add the instances we created (by public IP) to the group 'raxhosts'
       local_action:
@@ -132,7 +133,9 @@ This facilitates performing configuration actions on the hosts immediately in a
       with_items: rax.success
       when: rax.action == 'create'
 
-With the host group now created, a second play in your provision playbook could now configure them, for example::
+With the host group now created, the next play in this playbook could now configure servers belonging to the raxhosts group.
+
+.. code-block:: yaml
 
     - name: Configuration play
       hosts: raxhosts
@@ -141,7 +144,6 @@ With the host group now created, a second play in your provision playbook could
         - ntp
         - webserver
 
-
 The method above ties the configuration of a host with the provisioning step.  This isn't always what you want, and leads us 
 to the next section.
 
@@ -150,41 +152,28 @@ to the next section.
 Host Inventory
 ``````````````
 
-Once your nodes are spun up, you'll probably want to talk to them again.  
-
-The best way to handle his is to use the rax inventory plugin, which dynamically queries Rackspace Cloud and tells Ansible what
-nodes you have to manage.
-
-You might want to use this even if you are spinning up Ansible via other tools, including the Rackspace Cloud user interface.
-
-The inventory plugin can be used to group resources by their meta data.  Utilizing meta data is highly 
-recommended in rax and can provide an easy way to sort between host groups and roles.
-
-If you don't want to use the ``rax.py`` dynamic inventory script, you could also still choose to manually manage your INI inventory file,
-though this is less recommended.   
+Once your nodes are spun up, you'll probably want to talk to them again.  The best way to handle his is to use the "rax" inventory plugin, which dynamically queries Rackspace Cloud and tells Ansible what nodes you have to manage.  You might want to use this even if you are spinning up Ansible via other tools, including the Rackspace Cloud user interface. The inventory plugin can be used to group resources by metadata, region, OS, etc.  Utilizing metadata is highly recommended in "rax" and can provide an easy way to sort between host groups and roles. If you don't want to use the ``rax.py`` dynamic inventory script, you could also still choose to manually manage your INI inventory file, though this is less recommended.
 
-In Ansible it is quite possible to use multiple dynamic inventory plugins along with INI file data.  Just put them in a common
-directory and be sure the scripts are chmod +x, and the INI-based ones are not.
+In Ansible it is quite possible to use multiple dynamic inventory plugins along with INI file data.  Just put them in a common directory and be sure the scripts are chmod +x, and the INI-based ones are not.
 
 .. _raxpy:
 
 rax.py
 ++++++
 
-To use the rackspace dynamic inventory script, copy ``rax.py`` from ``plugins/inventory`` into your inventory directory and make it executable. You can specify credentials for ``rax.py`` utilizing the ``RAX_CREDS_FILE`` environment variable.
+To use the rackspace dynamic inventory script, copy ``rax.py`` into your inventory directory and make it executable. You can specify a credentails file for ``rax.py`` utilizing the ``RAX_CREDS_FILE`` environment variable.
+
+.. note:: Dynamic inventory scripts (like ``rax.py``) are saved in ``/usr/share/ansible/inventory`` if Ansible has been installed globally.  If installed to a virtualenv, the inventory scripts are installed to ``$VIRTUALENV/share/inventory``.
 
 .. note:: Users of :doc:`tower` will note that dynamic inventory is natively supported by Tower, and all you have to do is associate a group with your Rackspace Cloud credentials, and it will easily synchronize without going through these steps::
 
     $ RAX_CREDS_FILE=~/.raxpub ansible all -i rax.py -m setup
 
-``rax.py`` also accepts a ``RAX_REGION`` environment variable, which can contain an individual region, or a 
-comma separated list of regions.
+``rax.py`` also accepts a ``RAX_REGION`` environment variable, which can contain an individual region, or a comma separated list of regions.
 
 When using ``rax.py``, you will not have a 'localhost' defined in the inventory.  
 
-As mentioned previously, you will often be running most of these modules outside of the host loop, 
-and will need 'localhost' defined.  The recommended way to do this, would be to create an ``inventory`` directory, 
-and place both the ``rax.py`` script and a file containing ``localhost`` in it.  
+As mentioned previously, you will often be running most of these modules outside of the host loop, and will need 'localhost' defined.  The recommended way to do this, would be to create an ``inventory`` directory, and place both the ``rax.py`` script and a file containing ``localhost`` in it.
 
 Executing ``ansible`` or ``ansible-playbook`` and specifying the ``inventory`` directory instead 
 of an individual file, will cause ansible to evaluate each file in that directory for inventory.
@@ -295,8 +284,7 @@ following information, which will be utilized for inventory and variables.
 Standard Inventory
 ++++++++++++++++++
 
-When utilizing a standard ini formatted inventory file (as opposed to the inventory plugin), 
-it may still be adventageous to retrieve discoverable hostvar information  from the Rackspace API.  
+When utilizing a standard ini formatted inventory file (as opposed to the inventory plugin), it may still be adventageous to retrieve discoverable hostvar information  from the Rackspace API.
 
 This can be achieved with the ``rax_facts`` module and an inventory file similar to the following:
 
@@ -587,9 +575,16 @@ and less information has to be shared with remote hosts.
 
 .. _pending_information:
 
-Pending Information
-```````````````````
+Orchestration in the Rackspace Cloud
+++++++++++++++++++++++++++++++++++++
+
+Ansible is a powerful orchestration tool, and rax modules allow you the opportunity to orchestrate complex tasks, deployments, and configurations.  The key here is to automate provisioning of infrastructure, like any other pice of software in an environment.  Complex deployments might have previously required manaul manipulation of load balancers, or manual provisioning of servers.  Utilizing the rax modules included with Ansible, one can make the deployment of additioanl nodes contingent on the current number of running nodes, or the configuration of a clustered applicaiton dependent on the number of nodes with common metadata.  One could automate the following scenarios, for example:
+
+* Servers that are removed from a Cloud Load Balancer one-by-one, updated, verified, and returned to the load balancer pool
+* Expansion of an already-online environment, where nodes are provisioned, bootstrapped, configured, and software installed
+* A procedure where app log files are uploaded to a central location, like Cloud Files, before a node is decommissioned
+* Servers and load balancers that have DNS receords created and destroyed on creation and decomissioning, respectively
+
 
-More to come!