Add docs on only_if

YAMLSyntax.html

@@ -245,7 +245,7 @@ languages:
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

api.html

@@ -330,7 +330,7 @@ a conf.d file appropriately or something similar.  Who knows.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

examples.html

@@ -318,7 +318,7 @@ a simplified syntax for this.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

faq.html

@@ -336,7 +336,7 @@ tasks – whether for a QA sytem, build system, or anything you can think of
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

genindex.html

@@ -160,7 +160,7 @@ s.parentNode.insertBefore(ga, s);
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

gettingstarted.html

@@ -299,7 +299,7 @@ explore, but you already have a fully working infrastructure!</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

index.html

@@ -274,16 +274,15 @@ you with questions about Ansible.</p>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="playbooks.html#playbook-example">Playbook Example</a></li>
 <li class="toctree-l2"><a class="reference internal" href="playbooks.html#basics">Basics</a><ul>
-<li class="toctree-l3"><a class="reference internal" href="playbooks.html#hosts-line">Hosts line</a></li>
+<li class="toctree-l3"><a class="reference internal" href="playbooks.html#hosts-and-users">Hosts and Users</a></li>
-<li class="toctree-l3"><a class="reference internal" href="playbooks.html#user-line">User line</a></li>
 <li class="toctree-l3"><a class="reference internal" href="playbooks.html#vars-section">Vars section</a></li>
 <li class="toctree-l3"><a class="reference internal" href="playbooks.html#tasks-list">Tasks list</a></li>
-<li class="toctree-l3"><a class="reference internal" href="playbooks.html#task-name-and-action">Task name and action</a></li>
 </ul>
 </li>
-<li class="toctree-l2"><a class="reference internal" href="playbooks.html#notify-statements-handlers">Notify statements &amp; Handlers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="playbooks.html#running-operations-on-change">Running Operations On Change</a></li>
 <li class="toctree-l2"><a class="reference internal" href="playbooks.html#power-tricks">Power Tricks</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="playbooks.html#external-variables-and-sensitive-data">External Variables And Sensitive Data</a></li>
+<li class="toctree-l3"><a class="reference internal" href="playbooks.html#conditional-execution">Conditional Execution</a></li>
 <li class="toctree-l3"><a class="reference internal" href="playbooks.html#conditional-imports">Conditional Imports</a></li>
 <li class="toctree-l3"><a class="reference internal" href="playbooks.html#include-files-and-reuse">Include Files And Reuse</a></li>
 <li class="toctree-l3"><a class="reference internal" href="playbooks.html#using-includes-to-assign-classes-of-systems">Using Includes To Assign Classes of Systems</a></li>
@@ -362,7 +361,7 @@ Puppet Labs, and rPath.  Reach Michael by email <a class="reference external" hr
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

man.html

@@ -194,7 +194,7 @@ examples of these tools in use.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

man/ansible-playbook.1.html

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-playbook</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-playbook" lang="en"><a id="id354228"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — run an ansible playbook</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible-playbook &lt;filename.yml&gt; … [options]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible playbooks</strong></span> are a configuration and multinode deployment system.  Ansible-playbook is the tool
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-playbook</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-playbook" lang="en"><a id="id527421"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — run an ansible playbook</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible-playbook &lt;filename.yml&gt; … [options]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible playbooks</strong></span> are a configuration and multinode deployment system.  Ansible-playbook is the tool
 used to run them.   See the project home page (link below) for more information.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
 <span class="strong"><strong>filename.yml</strong></span>
 </span></dt><dd>

man/ansible.1.html

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id351020"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id389386"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
 SSH.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
 <span class="strong"><strong>host-pattern</strong></span>
 </span></dt><dd>

moduledev.html

@@ -394,7 +394,7 @@ Stop by the mailing list to inquire about requirements.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

modules.html

@@ -415,7 +415,7 @@ various configuration attributes.  Values include ‘installed’, &#821
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

patterns.html

@@ -240,7 +240,7 @@ wildcards:</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

playbooks.html

@@ -131,16 +131,15 @@ s.parentNode.insertBefore(ga, s);
 <li><a class="reference internal" href="#">Playbooks</a><ul>
 <li><a class="reference internal" href="#playbook-example">Playbook Example</a></li>
 <li><a class="reference internal" href="#basics">Basics</a><ul>
-<li><a class="reference internal" href="#hosts-line">Hosts line</a></li>
+<li><a class="reference internal" href="#hosts-and-users">Hosts and Users</a></li>
-<li><a class="reference internal" href="#user-line">User line</a></li>
 <li><a class="reference internal" href="#vars-section">Vars section</a></li>
 <li><a class="reference internal" href="#tasks-list">Tasks list</a></li>
-<li><a class="reference internal" href="#task-name-and-action">Task name and action</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#notify-statements-handlers">Notify statements &amp; Handlers</a></li>
+<li><a class="reference internal" href="#running-operations-on-change">Running Operations On Change</a></li>
 <li><a class="reference internal" href="#power-tricks">Power Tricks</a><ul>
 <li><a class="reference internal" href="#external-variables-and-sensitive-data">External Variables And Sensitive Data</a></li>
+<li><a class="reference internal" href="#conditional-execution">Conditional Execution</a></li>
 <li><a class="reference internal" href="#conditional-imports">Conditional Imports</a></li>
 <li><a class="reference internal" href="#include-files-and-reuse">Include Files And Reuse</a></li>
 <li><a class="reference internal" href="#using-includes-to-assign-classes-of-systems">Using Includes To Assign Classes of Systems</a></li>
@@ -222,32 +221,42 @@ server group, then more commands back on the webservers group, etc.</p>
 </div>
 <div class="section" id="basics">
 <h2>Basics<a class="headerlink" href="#basics" title="Permalink to this headline">¶</a></h2>
-<div class="section" id="hosts-line">
+<div class="section" id="hosts-and-users">
-<h3>Hosts line<a class="headerlink" href="#hosts-line" title="Permalink to this headline">¶</a></h3>
+<h3>Hosts and Users<a class="headerlink" href="#hosts-and-users" title="Permalink to this headline">¶</a></h3>
+<p>For each play in a playbook, you get to choose which machines in your infrastructure
+to target and what remote user to complete the steps (called tasks) as.</p>
 <p>The <cite>hosts</cite> line is a list of one or more groups or host patterns,
 separated by colons, as described in the <a class="reference internal" href="patterns.html#patterns"><em>The Inventory File, Patterns, and Groups</em></a>
-documentation.  This is just like the first parameter to
+documentation.  The <cite>user</cite> is just the name of the user account:</p>
-<cite>/usr/bin/ansible</cite>.</p>
+<div class="highlight-python"><pre>---
-<p>Each play gets to designate it&#8217;s own choice of patterns.</p>
+- hosts: webservers
-</div>
+  user: root</pre>
-<div class="section" id="user-line">
-<h3>User line<a class="headerlink" href="#user-line" title="Permalink to this headline">¶</a></h3>
-<p>Playbook steps on the remote system can be executed as any user.  The default is root,
-but you can specify others.  Sudo support is pending.:</p>
-<div class="highlight-python"><pre>user: mdehaan</pre>
 </div>
+<p>Support for running things from sudo is pending.</p>
 </div>
 <div class="section" id="vars-section">
 <h3>Vars section<a class="headerlink" href="#vars-section" title="Permalink to this headline">¶</a></h3>
-<p>The <cite>vars&#8217; section contains a list of variables and values that can be used in the plays.  These
+<p>The <a href="#id1"><span class="problematic" id="id2">`</span></a>vars&#8217; section contains a list of variables and values that can be used in the plays, like this:</p>
-can be used in templates or tasks and are dereferenced using
+<div class="highlight-python"><pre>---
-`jinja2</cite> syntax like this:</p>
+- hosts: webservers
+  users: root
+  vars:
+     http_port: 80
+     van_halen_port: 5150
+     other: 'magic'</pre>
+</div>
+<p>These variables can be used later in the playbook, or on the managed system (in templates), just like this:</p>
 <div class="highlight-python"><pre>{{ varname }}</pre>
 </div>
+<p>Within playbooks themselves, but not within templates on the remote machines, it&#8217;s also legal
+to use nicer shorthand like this:</p>
+<div class="highlight-python"><pre>$varname</pre>
+</div>
 <p>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 <tt class="docutils literal"><span class="pre">facter_</span></tt> and Ohai
+variables.</p>
+<p>Facter variables are prefixed with <tt class="docutils literal"><span class="pre">facter_</span></tt> and Ohai
 variables are prefixed with <tt class="docutils literal"><span class="pre">ohai_</span></tt>.  So for instance, if I wanted
 to write the hostname into the /etc/motd file, I could say:</p>
 <div class="highlight-python"><pre>- name: write the motd
@@ -265,39 +274,44 @@ at a time, against all machines matched by the host pattern,
 before moving on to the next task.</p>
 <p>Hosts with failed tasks are taken out of the rotation for the entire
 playbook.  If things fail, simply correct the playbook file and rerun.</p>
+<p>The goal of each task is to execute a module, with very specific arguments.
+Variables, as mentioned above, can be used in arguments to modules.</p>
 <p>Modules other than <cite>command</cite> are &#8216;idempotent&#8217;, meaning if you run them
 again, they will make the changes they are told to make to bring the
 system to the desired state.  This makes it very safe to rerun
 the same playbook multiple times.  They won&#8217;t change things
-unless they have to change things.  Command will actually rerun the
+unless they have to change things.</p>
-same command again, which is totally ok if the command is something
+<p>Command will actually rerun the same command again,
-like &#8216;chmod&#8217; or &#8216;setsebool&#8217;, etc.</p>
+which is totally ok if the command is something like
-</div>
+&#8216;chmod&#8217; or &#8216;setsebool&#8217;, etc.</p>
-<div class="section" id="task-name-and-action">
-<h3>Task name and action<a class="headerlink" href="#task-name-and-action" title="Permalink to this headline">¶</a></h3>
 <p>Every task must have a name, which is included in the output from
-running the playbook.</p>
+running the playbook.   This is output for humans, so it is
-<p>The action line is the name of an ansible module followed by
+nice to have reasonably good descriptions of each task step.</p>
-parameters in key=value form:</p>
+<p>Here is what a basic task looks like, as with most modules,
-<div class="highlight-python"><pre>- name: make sure apache is running
+the service module takes key=value arguments:</p>
-  action: service name=httpd state=running</pre>
+<div class="highlight-python"><pre>tasks:
+  - name: make sure apache is running
+    action: service name=httpd state=running</pre>
 </div>
 <p>The command module is the one module that just takes a list
-of arguments, and doesn&#8217;t use the key=value form.  Simple:</p>
+of arguments, and doesn&#8217;t use the key=value form.  This makes
-<div class="highlight-python"><pre>- name: disable selinux
+it work just like you would expect. Simple:</p>
-  action: command /sbin/setenforce 0</pre>
+<div class="highlight-python"><pre>tasks:
+  - name: disable selinux
+    action: command /sbin/setenforce 0</pre>
 </div>
 <p>Variables can be used in action lines.   Suppose you defined
 a variable called &#8216;vhost&#8217; in the &#8216;vars&#8217; section, you could do this:</p>
-<div class="highlight-python"><pre>- name: make a directory
+<div class="highlight-python"><pre>tasks:
-  action: template src=somefile.j2 dest=/etc/httpd/conf.d/{{ vhost }}</pre>
+  - name: make a directory
+    action: template src=somefile.j2 dest=/etc/httpd/conf.d/$vhost</pre>
 </div>
 <p>Those same variables are usable in templates, which we&#8217;ll get to later.</p>
 </div>
 </div>
-<div class="section" id="notify-statements-handlers">
+<div class="section" id="running-operations-on-change">
-<h2>Notify statements &amp; Handlers<a class="headerlink" href="#notify-statements-handlers" title="Permalink to this headline">¶</a></h2>
+<h2>Running Operations On Change<a class="headerlink" href="#running-operations-on-change" title="Permalink to this headline">¶</a></h2>
-<p>As we&#8217;ve mentioned, nearly all modules are written to be &#8216;idempotent&#8217; and can signal when
+<p>As we&#8217;ve mentioned, nearly all modules are written to be &#8216;idempotent&#8217; and can relay  when
 they have affected a change on the remote system.   Playbooks recognize this and
 have a basic event system that can be used to respond to change.</p>
 <p>These &#8216;notify&#8217; actions are triggered at the end of each &#8216;play&#8217; in a playbook, and
@@ -311,11 +325,8 @@ change, but only if the file changes:</p>
      - restart memcached
      - restart apache</pre>
 </div>
-<p>Next up, we&#8217;ll show what a handler looks like.</p>
+<p>The things listed in the &#8216;notify&#8217; section of a task are called
-<div class="admonition note">
+handlers.</p>
-<p class="first admonition-title">Note</p>
-<p class="last">Notify handlers are always run in the order written.</p>
-</div>
 <p>Handlers are lists of tasks, not really any different from regular
 tasks, that are referenced by name.  Handlers are what notifiers
 notify.  If nothing notifies a handler, it will not run.  Regardless
@@ -330,6 +341,10 @@ of the tasks complete in a particular play.</p>
 </div>
 <p>Handlers are best used to restart services and trigger reboots.  You probably
 won&#8217;t need them for much else.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Notify handlers are always run in the order written.</p>
+</div>
 </div>
 <div class="section" id="power-tricks">
 <h2>Power Tricks<a class="headerlink" href="#power-tricks" title="Permalink to this headline">¶</a></h2>
@@ -361,6 +376,32 @@ somevar: somevalue
 password: magic</pre>
 </div>
 </div>
+<div class="section" id="conditional-execution">
+<h3>Conditional Execution<a class="headerlink" href="#conditional-execution" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes you will want to skip a particular step on a particular host.  This could be something
+as simple as not installing a certain package if the operating system is a particular version,
+or it could be something like performing some cleanup steps if a filesystem is getting full.</p>
+<p>This is easy to do in Ansible, with the <cite>only_if</cite> clause.  This clause can be applied to any task,
+and allows usage of variables from anywhere in ansible, either denoted with <cite>$dollar_sign_syntax</cite> or
+<cite>{{ braces_syntax }}</cite> and then evaluates them with a Python expression.   Don&#8217;t panic &#8211; it&#8217;s actually
+pretty simple.:</p>
+<div class="highlight-python"><pre>vars:
+  - favcolor: 'red'
+tasks:
+  - name: "shutdown if my favorite color is blue"
+    action: command /sbin/shutdown -t now
+    only_if: "'$favcolor' == 'blue'"</pre>
+</div>
+<p>Variables from tools like <cite>facter</cite> and <cite>ohai</cite> can also be used here, if installed.   As a reminder,
+these variables are prefixed, so it&#8217;s <cite>$facter_operatingsystem</cite>, not <cite>$operatingsystem</cite>.  The only_if
+expression is actually a tiny small bit of Python, so be sure to quote variables and make something
+that evaluates to <cite>True</cite> or <cite>False</cite>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Handlers don&#8217;t support only_if because they don&#8217;t need to.  If a handler is not notified,
+it will not run.</p>
+</div>
+</div>
 <div class="section" id="conditional-imports">
 <h3>Conditional Imports<a class="headerlink" href="#conditional-imports" title="Permalink to this headline">¶</a></h3>
 <p>Sometimes you will want to do certain things differently in a playbook based on certain criteria.
@@ -577,7 +618,7 @@ Let&#8217;s run a playbook using a parallelism level of 10:</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

rst/playbooks.rst

@@ -58,37 +58,52 @@ Below, we'll break down what the various features of the playbook language are.
 Basics
 ``````
 
-Hosts line
+Hosts and Users
-++++++++++
++++++++++++++++
+
+For each play in a playbook, you get to choose which machines in your infrastructure
+to target and what remote user to complete the steps (called tasks) as.
 
 The `hosts` line is a list of one or more groups or host patterns,
 separated by colons, as described in the :ref:`patterns`
-documentation.  This is just like the first parameter to
+documentation.  The `user` is just the name of the user account::
-`/usr/bin/ansible`. 
 
-Each play gets to designate it's own choice of patterns.
+    ---
+    - hosts: webservers
+      user: root
 
-User line
-+++++++++
 
-Playbook steps on the remote system can be executed as any user.  The default is root,
+Support for running things from sudo is pending.
-but you can specify others.  Sudo support is pending.::
 
-    user: mdehaan
 
 Vars section
 ++++++++++++
 
-The `vars' section contains a list of variables and values that can be used in the plays.  These
+The `vars' section contains a list of variables and values that can be used in the plays, like this::
-can be used in templates or tasks and are dereferenced using
+
-`jinja2` syntax like this::
+    ---
+    - hosts: webservers
+      users: root
+      vars:
+         http_port: 80
+         van_halen_port: 5150
+         other: 'magic'       
+
+These variables can be used later in the playbook, or on the managed system (in templates), just like this::
 
     {{ varname }}
 
+Within playbooks themselves, but not within templates on the remote machines, it's also legal
+to use nicer shorthand like this::
+
+    $varname
+
 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.  
+
+Facter variables are prefixed with ``facter_`` and Ohai
 variables are prefixed with ``ohai_``.  So for instance, if I wanted
 to write the hostname into the /etc/motd file, I could say::
 
@@ -111,45 +126,52 @@ before moving on to the next task.
 Hosts with failed tasks are taken out of the rotation for the entire
 playbook.  If things fail, simply correct the playbook file and rerun.
 
+The goal of each task is to execute a module, with very specific arguments.
+Variables, as mentioned above, can be used in arguments to modules.
+
 Modules other than `command` are 'idempotent', meaning if you run them
 again, they will make the changes they are told to make to bring the
 system to the desired state.  This makes it very safe to rerun
 the same playbook multiple times.  They won't change things
-unless they have to change things.  Command will actually rerun the
+unless they have to change things.  
-same command again, which is totally ok if the command is something
-like 'chmod' or 'setsebool', etc.
 
-
+Command will actually rerun the same command again, 
-Task name and action
+which is totally ok if the command is something like 
-++++++++++++++++++++
+'chmod' or 'setsebool', etc.
 
 Every task must have a name, which is included in the output from
-running the playbook.
+running the playbook.   This is output for humans, so it is
+nice to have reasonably good descriptions of each task step.
 
-The action line is the name of an ansible module followed by
+Here is what a basic task looks like, as with most modules,
-parameters in key=value form::
+the service module takes key=value arguments::
 
-   - name: make sure apache is running
+   tasks:
-     action: service name=httpd state=running
+     - name: make sure apache is running
+       action: service name=httpd state=running
 
 The command module is the one module that just takes a list
-of arguments, and doesn't use the key=value form.  Simple::
+of arguments, and doesn't use the key=value form.  This makes
+it work just like you would expect. Simple::
 
-   - name: disable selinux 
+   tasks:
-     action: command /sbin/setenforce 0
+     - name: disable selinux 
+       action: command /sbin/setenforce 0
 
 Variables can be used in action lines.   Suppose you defined
 a variable called 'vhost' in the 'vars' section, you could do this::
 
-   - name: make a directory
+   tasks:
-     action: template src=somefile.j2 dest=/etc/httpd/conf.d/{{ vhost }}
+     - name: make a directory
+       action: template src=somefile.j2 dest=/etc/httpd/conf.d/$vhost
 
 Those same variables are usable in templates, which we'll get to later.
 
-Notify statements & Handlers
+
+Running Operations On Change
 ````````````````````````````
 
-As we've mentioned, nearly all modules are written to be 'idempotent' and can signal when
+As we've mentioned, nearly all modules are written to be 'idempotent' and can relay  when
 they have affected a change on the remote system.   Playbooks recognize this and
 have a basic event system that can be used to respond to change.
 
@@ -166,10 +188,8 @@ change, but only if the file changes::
         - restart memcached
         - restart apache
 
-Next up, we'll show what a handler looks like.
+The things listed in the 'notify' section of a task are called
-
+handlers.  
-.. note::
-   Notify handlers are always run in the order written.
 
 Handlers are lists of tasks, not really any different from regular
 tasks, that are referenced by name.  Handlers are what notifiers
@@ -188,6 +208,9 @@ Here's an example handlers section::
 Handlers are best used to restart services and trigger reboots.  You probably
 won't need them for much else.
 
+.. note::
+   Notify handlers are always run in the order written.
+
 
 Power Tricks
 ````````````
@@ -225,6 +248,35 @@ The contents of each variables file is a simple YAML dictionary, like this::
     somevar: somevalue
     password: magic
 
+
+Conditional Execution
++++++++++++++++++++++
+
+Sometimes you will want to skip a particular step on a particular host.  This could be something
+as simple as not installing a certain package if the operating system is a particular version,
+or it could be something like performing some cleanup steps if a filesystem is getting full.
+
+This is easy to do in Ansible, with the `only_if` clause.  This clause can be applied to any task,
+and allows usage of variables from anywhere in ansible, either denoted with `$dollar_sign_syntax` or
+`{{ braces_syntax }}` and then evaluates them with a Python expression.   Don't panic -- it's actually
+pretty simple.::
+
+    vars:
+      - favcolor: 'red'
+    tasks:
+      - name: "shutdown if my favorite color is blue"
+        action: command /sbin/shutdown -t now
+        only_if: "'$favcolor' == 'blue'"
+      
+Variables from tools like `facter` and `ohai` can also be used here, if installed.   As a reminder,
+these variables are prefixed, so it's `$facter_operatingsystem`, not `$operatingsystem`.  The only_if
+expression is actually a tiny small bit of Python, so be sure to quote variables and make something
+that evaluates to `True` or `False`.
+
+.. note::
+     Handlers don't support only_if because they don't need to.  If a handler is not notified,
+     it will not run.  
+
 Conditional Imports
 +++++++++++++++++++
 

search.html

@@ -177,7 +177,7 @@ s.parentNode.insertBefore(ga, s);
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 19, 2012.<br/>
+      Last updated on Mar 20, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>