Docs updates

html/_sources/playbooks.txt

@@ -1,55 +1,118 @@
 Playbooks
 =========
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. In dignissim
-placerat nibh, non feugiat risus varius vitae. Donec eu libero
-lectus. Ut non orci felis, eget mattis mauris. Etiam ut tellus in
-magna porta venenatis. Quisque scelerisque, sem non ultrices bibendum,
-dolor diam rutrum lectus, sed luctus neque neque vitae eros. Vivamus
-mattis, ipsum ut bibendum gravida, lectus arcu venenatis elit, vitae
-luctus diam leo sit amet ligula. Nunc egestas justo in nulla sagittis
-ut suscipit sapien gravida. Morbi id dui nibh. Nullam diam massa,
-rhoncus a dignissim non, adipiscing vel arcu. Quisque ultricies
-tincidunt purus ut sodales. Quisque scelerisque dapibus purus quis
-egestas. Maecenas sagittis porttitor adipiscing. Duis eu magna
-sem. Donec arcu felis, faucibus et malesuada non, blandit vitae
-metus. Fusce nec sapien dolor.
+.. seealso::
 
-Aenean ac fermentum nisl. Integer leo sem, rutrum nec dictum at,
-pretium quis sapien. Duis felis metus, sodales sit amet gravida in,
-pretium ut arcu. Nulla ligula quam, aliquam sit amet sollicitudin
-eget, molestie tincidunt ipsum. Nulla leo nunc, mattis sed auctor at,
-suscipit ut metus. Suspendisse hendrerit, justo sagittis malesuada
-molestie, nisi nunc placerat libero, vel vulputate elit tellus et
-augue. Phasellus tempor lectus ac nisi aliquam faucibus. Donec feugiat
-egestas nibh id mattis. In hac habitasse platea dictumst. Ut accumsan
-lorem eget leo dictum viverra.
+   :doc:`YAMLScripts`
+       Learn about YAML syntax
+   :doc:`modules`
+       Learn about available modules and writing your own
+   :doc:`patterns`
+       Learn about how to select hosts
 
-Quisque egestas lorem sit amet felis tincidunt adipiscing. Aenean
-ornare fermentum accumsan. Aenean eu mauris arcu, id pulvinar
-quam. Suspendisse nec massa vel augue laoreet ultricies in convallis
-dolor. Mauris sodales porta enim, non ultricies dolor luctus
-in. Phasellus eu tortor lectus, vel porttitor nulla. Mauris vulputate,
-erat id scelerisque lobortis, nibh ipsum tristique elit, ac viverra
-arcu sem a ante. Praesent nec metus vestibulum augue eleifend
-suscipit. In feugiat, sem nec dignissim consequat, velit tortor
-scelerisque metus, sit amet mollis nisl sem eu nibh. Quisque in nibh
-turpis. Proin ac nisi ligula, a pretium augue.
 
-In nibh eros, laoreet id interdum vel, sodales sed tortor. Sed
-ullamcorper, sem vel mattis consectetur, nibh turpis molestie nisl,
-eget lobortis mi magna sed metus. Cras justo est, tempus quis
-adipiscing ut, hendrerit convallis sem. Mauris ullamcorper, sapien et
-luctus iaculis, urna elit egestas ipsum, et tristique enim risus vitae
-nunc. Vivamus aliquet lorem eu urna pulvinar hendrerit malesuada nunc
-sollicitudin. Cras in mi rhoncus quam egestas dignissim vel sit amet
-lacus. Maecenas interdum viverra laoreet. Quisque elementum
-sollicitudin ullamcorper.
+Playbooks are a completely different way to use ansible and are particularly awesome.
+
+They are the basis for a really simple configuration management and deployment system, unlike any that already exist, and one that is very well suited to deploying complex multi-machine applications. While you might run the main ansible program for ad-hoc tasks, playbooks are more likely to be kept in source control and used to push out your configuration or assure the configurations of your remote systems are in spec.
+
+
+Playbook Example
+````````````````
+
+Playbooks are expressed in YAML format and have a minimum of syntax.  Each playbook is composed
+of one or more patterns in a list.  By composing a playbook of multiple patterns, it is possible
+to orchestrate multi-machine deployments, running certain steps on all machines in
+the webservers group, then certain steps on the database server group, then more commands
+back on the webservers group, etc::
+
+---
+- hosts: all
+  vars:
+    http_port: 80
+    max_clients: 200
+  user: root
+  tasks:
+  - include: base.yml somevar=3 othervar=4
+  - name: write the apache config file
+    action: template src=/srv/httpd.j2 dest=/etc/httpd.conf
+    notify:
+    - restart apache
+  - name: ensure apache is running
+    action: service name=httpd state=started
+  handlers:
+    - include: handlers.yml
+
+Hosts line
+``````````
+
+The hosts line is alist of one or more groups or host patterns, seperated by colons.
+
+   webservers:dbservers:*.foo.example.com
+
+Vars section
+````````````
+
+A list of variables that can be used in the 'action' lines of the template, or in
+included templates.   Variables are deferenced like this::
+
+   {{ varname }}
+
+These variables will be pushed down to the managed systems for use in templating operations.
+
+Further, if there are discovered variables about the system (say, if facter or ohai were
+installed) these variables bubble up back into the playbook, and can be used on each
+system just like explicitly set variables.  Facter variables are prefixed with 'facter'
+and Ohai variables are prefixed with 'ohai'.
+
+Tasks list
+``````````
+
+Tasks are executed in order, one at a time, against all machines matched by the host
+pattern, before moving on to the next task.  Failed tasks are taken out of the rotation.
+
+Task name and comment
+`````````
+
+Each task has a name (required) and optional comment.  This is for informational purposes only
+
+Task action
+```````````
+
+The action line is the name of an ansible module followed by parameters.  Usually these
+are expressed in key=value form, except for the command module, which looks just like a Linux/Unix
+command line.  See the module documentation for more info.
+
+Notify statements
+`````````````````
+
+Nearly all modules are written to be 'idempotent' and can signal when they have affected a change
+on the remote system.  If a notify statement is used, the named handler will be run against
+each system where a change was effected, but NOT on systems where no change occurred.
+
+Handlers
+````````
+
+Handlers are lists of tasks, not really any different from regular tasks, that are referenced
+by name.  
+
+Includes
+````````
+
+Not all tasks have to be listed directly in the main file.  An include file can contain
+a list of tasks (in YAML) as well, optionally passing extra variables into the file.
+Variables passed in can be deferenced like this:
+
+   {{ variable }}
+
+Asynchronous Actions and Polling
+````````````````````````````````
+
+(Information on this feature is pending)
+
+Executing A Playbook
+````````````````````
+
+To run a playbook::
+
+    ansible-playbook playbook.yml
 
-Pellentesque mauris sem, malesuada at lobortis in, porta eget
-urna. Duis aliquet quam eget risus elementum quis auctor ligula
-gravida. Phasellus et ullamcorper libero. Nam elementum ultricies
-tellus, in sagittis magna aliquet quis. Ut sit amet tellus id erat
-tristique lobortis. Suspendisse est enim, tristique eu convallis id,
-rutrum nec lacus. Fusce iaculis diam non felis rutrum lobortis. Proin
-hendrerit mi tincidunt dui fermentum placerat.