Added docs on conditional import usage

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 18, 2012.<br/>
+      Last updated on Mar 19, 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 18, 2012.<br/>
+      Last updated on Mar 19, 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 18, 2012.<br/>
+      Last updated on Mar 19, 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 18, 2012.<br/>
+      Last updated on Mar 19, 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 18, 2012.<br/>
+      Last updated on Mar 19, 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 18, 2012.<br/>
+      Last updated on Mar 19, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

index.html

@@ -284,6 +284,7 @@ you with questions about Ansible.</p>
 <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#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-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>
 <li class="toctree-l3"><a class="reference internal" href="playbooks.html#asynchronous-actions-and-polling">Asynchronous Actions and Polling</a></li>
@@ -361,7 +362,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 18, 2012.<br/>
+      Last updated on Mar 19, 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 18, 2012.<br/>
+      Last updated on Mar 19, 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="id324020"></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="id460519"></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="id569302"></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="id340814"></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 18, 2012.<br/>
+      Last updated on Mar 19, 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 18, 2012.<br/>
+      Last updated on Mar 19, 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 18, 2012.<br/>
+      Last updated on Mar 19, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

playbooks.html

@@ -141,6 +141,7 @@ s.parentNode.insertBefore(ga, s);
 <li><a class="reference internal" href="#notify-statements-handlers">Notify statements &amp; Handlers</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-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>
 <li><a class="reference internal" href="#asynchronous-actions-and-polling">Asynchronous Actions and Polling</a></li>
@@ -360,6 +361,47 @@ somevar: somevalue
 password: magic</pre>
 </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.
+Having one playbook that works on multiple platforms and OS versions is a good example.</p>
+<p>As an example, the name of the Apache package may be different between CentOS and Debian,
+but it is easily handled with a minimum of syntax in an Ansible Playbook:</p>
+<div class="highlight-python"><pre>---
+- hosts: all
+  user: root
+  vars_files:
+    - vars/common.yml
+    - [ vars/$facter_operatingsystem.yml, vars/os_defaults.yml ]
+  tasks:
+  - name: make sure apache is running
+    action: service name=$apache state=running</pre>
+</div>
+<p>As a reminder, the various YAML files contain just keys and values:</p>
+<div class="highlight-python"><pre>---
+# for vars/CentOS.yml
+apache: httpd
+somethingelse: 42</pre>
+</div>
+<p>How does this work?  If the operating system was &#8216;CentOS&#8217;, the first file Ansible would try to import
+would be &#8216;vars/CentOS.yml&#8217;, followed up by &#8216;/vars/os_defaults.yml&#8217; if that file
+did not exist.   If no files in the list were found, an error would be raised.
+On Debian, it would instead first look towards &#8216;vars/Debian.yml&#8217; instead of &#8216;vars/CentOS.yml&#8217;, before
+falling back on &#8216;vars/os_defaults.yml&#8217;. Pretty simple.</p>
+<p>To use this conditional import feature, you&#8217;ll need facter or ohai installed prior to running the playbook, but
+you can of course push this out with Ansible if you like:</p>
+<div class="highlight-python"><pre># for facter
+ansible -m yum -a "pkg=facter ensure=installed"
+ansible -m yum -a "pkg=ruby-json ensure=installed"
+
+# for ohai
+ansible -m yum -a "pkg=ohai ensure=installed"</pre>
+</div>
+<p>Ansible&#8217;s approach to configuration &#8211; seperating variables from tasks, keeps your playbooks
+from turning into arbitrary code with ugly nested ifs, conditionals, and so on - and results
+in more streamlined &amp; auditable configuration rules &#8211; especially because there are a
+minimum of decision points to track.</p>
+</div>
 <div class="section" id="include-files-and-reuse">
 <h3>Include Files And Reuse<a class="headerlink" href="#include-files-and-reuse" title="Permalink to this headline">¶</a></h3>
 <p>Suppose you want to reuse lists of tasks between plays or playbooks.  You can use
@@ -412,6 +454,9 @@ of a play:</p>
   - include: handlers/handlers.yml</pre>
 </div>
 <p>You can mix in includes along with your regular non-included tasks and handlers.</p>
+<p>Note that you can not conditionally path the location to an include file, like you can
+with &#8216;vars_files&#8217;.  If you find yourself needing to do this, consider how you can
+restructure your playbook to be more class/role oriented.</p>
 </div>
 <div class="section" id="using-includes-to-assign-classes-of-systems">
 <h3>Using Includes To Assign Classes of Systems<a class="headerlink" href="#using-includes-to-assign-classes-of-systems" title="Permalink to this headline">¶</a></h3>
@@ -518,6 +563,8 @@ Let&#8217;s run a playbook using a parallelism level of 10:</p>
 <dd>Learn about how to select hosts</dd>
 <dt><a class="reference external" href="https://github.com/ansible/ansible/tree/master/examples/playbooks">Github examples directory</a></dt>
 <dd>Complete playbook files from the github project source</dd>
+<dt><a class="reference external" href="http://groups.google.com/group/ansible-project">Mailing List</a></dt>
+<dd>Questions? Help? Ideas?  Stop by the list on Google Groups</dd>
 </dl>
 </div>
 </div>
@@ -530,7 +577,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 18, 2012.<br/>
+      Last updated on Mar 19, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

rst/playbooks.rst

@@ -225,6 +225,54 @@ The contents of each variables file is a simple YAML dictionary, like this::
     somevar: somevalue
     password: magic
 
+Conditional Imports
++++++++++++++++++++
+
+Sometimes you will want to do certain things differently in a playbook based on certain criteria.
+Having one playbook that works on multiple platforms and OS versions is a good example.
+
+As an example, the name of the Apache package may be different between CentOS and Debian, 
+but it is easily handled with a minimum of syntax in an Ansible Playbook::
+
+    ---
+    - hosts: all
+      user: root
+      vars_files:
+        - vars/common.yml
+        - [ vars/$facter_operatingsystem.yml, vars/os_defaults.yml ] 
+      tasks:
+      - name: make sure apache is running
+        action: service name=$apache state=running
+
+
+As a reminder, the various YAML files contain just keys and values::
+
+    ---
+    # for vars/CentOS.yml
+    apache: httpd
+    somethingelse: 42
+
+How does this work?  If the operating system was 'CentOS', the first file Ansible would try to import
+would be 'vars/CentOS.yml', followed up by '/vars/os_defaults.yml' if that file
+did not exist.   If no files in the list were found, an error would be raised.
+On Debian, it would instead first look towards 'vars/Debian.yml' instead of 'vars/CentOS.yml', before
+falling back on 'vars/os_defaults.yml'. Pretty simple.
+
+To use this conditional import feature, you'll need facter or ohai installed prior to running the playbook, but
+you can of course push this out with Ansible if you like::
+
+    # for facter
+    ansible -m yum -a "pkg=facter ensure=installed"
+    ansible -m yum -a "pkg=ruby-json ensure=installed"
+
+    # for ohai
+    ansible -m yum -a "pkg=ohai ensure=installed"
+
+Ansible's approach to configuration -- seperating variables from tasks, keeps your playbooks
+from turning into arbitrary code with ugly nested ifs, conditionals, and so on - and results
+in more streamlined & auditable configuration rules -- especially because there are a 
+minimum of decision points to track.
+
 
 Include Files And Reuse
 +++++++++++++++++++++++
@@ -288,6 +336,10 @@ of a play::
 
 You can mix in includes along with your regular non-included tasks and handlers.
 
+Note that you can not conditionally path the location to an include file, like you can
+with 'vars_files'.  If you find yourself needing to do this, consider how you can
+restructure your playbook to be more class/role oriented.  
+
 
 Using Includes To Assign Classes of Systems
 +++++++++++++++++++++++++++++++++++++++++++
@@ -397,4 +449,7 @@ Let's run a playbook using a parallelism level of 10::
        Learn about how to select hosts
    `Github examples directory <https://github.com/ansible/ansible/tree/master/examples/playbooks>`_
        Complete playbook files from the github project source
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+
 

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 18, 2012.<br/>
+      Last updated on Mar 19, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>