From e8eb7ab5ed723501fab33e4822c27cad64f63eb7 Mon Sep 17 00:00:00 2001
From: Michael DeHaan
Date: Fri, 9 Mar 2012 07:42:53 -0500
Subject: [PATCH] Update docs
---
html/YAMLScripts.html | 2 +-
html/_sources/api.txt | 42 ++++++++++-
html/_sources/examples.txt | 34 +++++----
html/_sources/playbooks.txt | 55 +++++++++++++-
html/api.html | 53 ++++++++++++--
html/communicate.html | 118 -------------------------------
html/examples.html | 35 ++++-----
html/genindex.html | 2 +-
html/gettingstarted.html | 4 +-
html/index.html | 12 ++--
html/man.html | 10 +--
html/man/ansible-modules.5.html | 2 +-
html/man/ansible-playbook.5.html | 2 +-
html/man/ansible.1.html | 2 +-
html/modules.html | 14 ++--
html/patterns.html | 12 ++--
html/playbooks.html | 59 ++++++++++++++--
html/search.html | 2 +-
html/searchindex.js | 2 +-
rst/api.rst | 42 ++++++++++-
rst/examples.rst | 34 +++++----
rst/playbooks.rst | 55 +++++++++++++-
22 files changed, 379 insertions(+), 214 deletions(-)
delete mode 100644 html/communicate.html
diff --git a/html/YAMLScripts.html b/html/YAMLScripts.html
index 09db73f8aea..ec72607e3ca 100644
--- a/html/YAMLScripts.html
+++ b/html/YAMLScripts.html
@@ -183,7 +183,7 @@ languages:
diff --git a/html/_sources/api.txt b/html/_sources/api.txt
index a3ddea45951..7eb71cf1f96 100644
--- a/html/_sources/api.txt
+++ b/html/_sources/api.txt
@@ -1,5 +1,5 @@
-API
-```
+Using the Python API
+====================
The Python API is very powerful, and is how the ansible CLI and ansible-playbook
are implemented.
@@ -32,4 +32,42 @@ expressed in the 'ansible-modules' documentation.::
A module can return any type of JSON data it wants, so Ansible can
be used as a framework to rapidly build powerful applications and scripts.
+Detailed API Example
+````````````````````
+
+The following script prints out the uptime information for all hosts::
+
+ #!/usr/bin/python
+
+ import ansible.runner
+ import sys
+
+ # construct the ansible runner and execute on all hosts
+ results = ansible.runner.Runner(
+ pattern='*', forks=10,
+ module_name='command', module_args=['/usr/bin/uptime'],
+ ).run()
+
+ if results is None:
+ print "No hosts found"
+ sys.exit(1)
+
+ print "UP ***********"
+ for (hostname, result) in results['contacted'].items():
+ if not 'failed' in result:
+ print "%s >>> %s" % (hostname, result['stdout'])
+
+ print "FAILED *******"
+ for (hostname, result) in results['contacted'].items():
+ if 'failed' in result:
+ print "%s >>> %s" % (hostname, result['msg'])
+
+ print "DOWN *********"
+ for (hostname, result) in results['dark'].items():
+ print "%s >>> %s" % (hostname, result)
+
+Advanced programmers may also wish to read the source to ansible itself, for
+it uses the Runner() API (with all available options) to implement the
+command line tools ``ansible`` and ``ansible-playbook``.
+
diff --git a/html/_sources/examples.txt b/html/_sources/examples.txt
index b061f31eaac..4adeeed94db 100644
--- a/html/_sources/examples.txt
+++ b/html/_sources/examples.txt
@@ -1,5 +1,9 @@
-Examples
-========
+Command Line Examples
+=====================
+
+The following examples show how to use `/usr/bin/ansible` for running ad-hoc tasks.
+Start here. For configuration management and deployments, you'll want to pick up on
+using `/usr/bin/ansible-playbook` -- the concepts port over directly.
.. seealso::
@@ -24,19 +28,6 @@ The -f 10 specifies the usage of 10 simultaneous processes.
Note that other than the command module, ansible modules do not work like simple scripts. They make the remote system look like you state, and run the commands neccessary to get it there. This is commonly refered to
as 'idempotency'.
-Time Limited Background Operations
-``````````````````````````````````
-
-Long running operations can be backgrounded, and their status can be checked on later. The same job ID is given to the same task on all hosts, so you won't lose track. Polling support is pending in the command line.::
-
- ansible all -B 3600 -a "/usr/bin/long_running_operation --do-stuff"
- ansible all -n job_status -a jid=123456789
-
-Any module other than 'copy' or 'template' can be backgrounded. Typically you'll be backgrounding shell
-commands or software upgrades only.
-
-After the time limit (in seconds) runs out (-B), the process on the remote nodes will be killed.
-
File Transfer & Templating
``````````````````````````
@@ -74,4 +65,17 @@ Alternatively, restart a service on all webservers::
ansible webservers -m service name=httpd state=restarted
+Time Limited Background Operations
+``````````````````````````````````
+
+Long running operations can be backgrounded, and their status can be checked on later. The same job ID is given to the same task on all hosts, so you won't lose track. Polling support is pending in the command line.::
+
+ ansible all -B 3600 -a "/usr/bin/long_running_operation --do-stuff"
+ ansible all -n job_status -a jid=123456789
+
+Any module other than 'copy' or 'template' can be backgrounded. Typically you'll be backgrounding shell
+commands or software upgrades only.
+
+After the time limit (in seconds) runs out (-B), the process on the remote nodes will be killed.
+
diff --git a/html/_sources/playbooks.txt b/html/_sources/playbooks.txt
index 71d87d3ee03..890768c5894 100644
--- a/html/_sources/playbooks.txt
+++ b/html/_sources/playbooks.txt
@@ -47,8 +47,7 @@ back on the webservers group, etc::
Hosts line
``````````
-The hosts line is a list of one or more groups or host patterns, seperated by colons, as
-described in the 'patterns' documentation. This is just like the first parameter to /usr/bin/ansible.
+The hosts line is a list of one or more groups or host patterns, seperated by colons, asdescribed in the 'patterns' documentation. This is just like the first parameter to /usr/bin/ansible.
Vars section
````````````
@@ -140,6 +139,58 @@ in a wordpress.yml file, and use it like so::
In addition to the explicitly passed in parameters, all variables from the vars section
are also available.
+The format of an included list of tasks or handlers looks just like a flat list of tasks. Here
+is an example of what base.yml might look like::
+
+ ---
+ - name: no selinux
+ action: command /usr/sbin/setenforce 0
+ - name: no iptables
+ action: service name=iptables state=stopped
+ - name: this is just to show variables work here, favcolor={{ favcolor }}
+ action: command /bin/true
+
+As you can see above, variables in include files work just like they do in the main file.
+Including a variable in the name of a task is a contrived example, you could also
+pass them to the action command line or use them inside a template file.
+
+Note that include statements are only usable from the top level playbook file.
+At this time, includes can not include other includes.
+
+Using Includes To Assign Classes of Systems
+```````````````````````````````````````````
+
+Include files are best used to reuse logic between playbooks. You could imagine
+a playbook describing your entire infrastructure like this::
+
+ ---
+ - hosts: atlanta-webservers
+ vars:
+ datacenter: atlanta
+ tasks:
+ - include: base.yml
+ - include: webservers.yml database=db.atlanta.com
+ handlers:
+ - include: generic-handlers.yml
+ - hosts: atlanta-dbservers
+ vars:
+ datacenter: atlanta
+ tasks:
+ - include: base.yml
+ - include: dbservers.yml
+ handlers:
+ - include: generic-handlers.yml
+
+There is one (or more) play defined for each group of systems, and each play maps
+each group includes one or more 'class definitions' telling the systems what they
+are supposed to do or be.
+
+Using a common handlers file could allow one task in 'webservers' to define 'restart apache',
+and it could be reused between multiple plays.
+
+Variables like 'database' above can be used in templates referenced from the
+configuration file to generate machine specific variables.
+
Asynchronous Actions and Polling
````````````````````````````````
diff --git a/html/api.html b/html/api.html
index 685a15f8c4c..cd965fc710b 100644
--- a/html/api.html
+++ b/html/api.html
@@ -7,7 +7,7 @@