rebuild

api.html

@@ -317,9 +317,13 @@ Welcome, I am templated with a value of a={{ a }}, b={{ b }}, and c={{ c }}</pre
 <div class="highlight-python"><pre>ansible webserver -m setup
 ansible webserver -m template -a "src=/tmp/motd.j2 dest=/etc/motd"</pre>
 </div>
-<p>Note that the name &#8216;webserver&#8217; came from cobbler, as did the variables for the config file.  You can still
+<div class="admonition note">
-pass in your own variables like normal in Ansible, but variables from the external inventory script will
+<p class="first admonition-title">Note</p>
-override any that have the same name.</p>
+<p class="last">The name &#8216;webserver&#8217; came from cobbler, as did the variables for
+the config file.  You can still pass in your own variables like
+normal in Ansible, but variables from the external inventory script
+will override any that have the same name.</p>
+</div>
 <p>So, with the template above (motd.j2), this would result in the following data being written to /etc/motd for system &#8216;foo&#8217;:</p>
 <div class="highlight-python"><pre>Welcome, I am templated with a value of a=2, b=3, and c=4</pre>
 </div>

bestpractices.html

@@ -187,50 +187,45 @@ s.parentNode.insertBefore(ga, s);
 <p>Here are some tips for making the most of Ansible.</p>
 <div class="section" id="always-mention-state">
 <h2>Always Mention State<a class="headerlink" href="#always-mention-state" title="Permalink to this headline">¶</a></h2>
-<p>The &#8216;state&#8217; parameter is optional to a lot of modules.  Whether state=present or state=absent, it&#8217;s always
+<p>The &#8216;state&#8217; parameter is optional to a lot of modules.  Whether
-best to leave that parameter in your playbooks to make it clear, especially as some modules support additional
+&#8216;state=present&#8217; or &#8216;state=absent&#8217;, it&#8217;s always best to leave that
-states.</p>
+parameter in your playbooks to make it clear, especially as some
+modules support additional states.</p>
 </div>
 <div class="section" id="group-by-roles">
 <h2>Group By Roles<a class="headerlink" href="#group-by-roles" title="Permalink to this headline">¶</a></h2>
 <p>A system can be in multiple groups.  See <a class="reference internal" href="patterns.html"><em>Inventory &amp; Patterns</em></a>.   Having groups named after things like
-&#8216;webservers&#8217; and &#8216;dbservers&#8217; is repeated in the examples because it&#8217;s a very powerful concept.</p>
+<em>webservers</em> and <em>dbservers</em> is repeated in the examples because it&#8217;s a very powerful concept.</p>
 <p>This allows playbooks to target machines based on role, as well as to assign role specific variables
 using the group variable system.</p>
 </div>
 <div class="section" id="directory-organization">
 <h2>Directory Organization<a class="headerlink" href="#directory-organization" title="Permalink to this headline">¶</a></h2>
 <p>Playbooks should be organized like this:</p>
-<div class="highlight-python"><pre>(root of source control repository)
+<div class="highlight-python"><pre># root of source control repository
-
+├── acme/
-    global_vars.yml # variables for all playbooks
+│   ├── setup.yml
-    acme/           # each playbook has a directory
+│   └── stop.yml
-
+├── files/
-        setup.yml   # playbook to manage the service
+│   └── some_file_path_foo.conf
-        stop.yml    # playbook to halt the service (optional)
+├── handlers/
-
+│   └── main.yml
-        files/
+├── tasks/
-           some_file_path_foo.conf
+│   ├── setup.yml
-
+│   └── stop.yml
-        templates/
+├── templates/
-           etc_acme_conf_acme.conf
+│   ├── etc_acme_conf_acme.conf
-           etc_other_conf_other.conf
+│   └── etc_other_conf_other.conf
-
+├── vars/
-        vars/
+│   └── main.yml
-           main.yml  # variables specific to this playbook
+└── global_vars.yml</pre>
-
-        handlers/
-           main.yml
-
-        tasks/
-           setup.yml
-           stop.yml</pre>
 </div>
-<p>Any directories or files not needed can be omitted.  Not all modules may require <cite>vars</cite> or <cite>files</cite> sections, though most
+<p>Any directories or files not needed can be omitted.  Not all modules
-will require <cite>handlers</cite>, <cite>tasks</cite>, and <cite>templates</cite>.  To review what each of these sections do, see <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> and <a class="reference internal" href="playbooks2.html"><em>Advanced Playbooks</em></a>.</p>
+may require &#8216;vars&#8217; or &#8216;files&#8217; sections, though most will require
+&#8216;handlers&#8217;, &#8216;tasks&#8217;, and &#8216;templates&#8217;.  To review what each of
+these sections do, see <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> and <a class="reference internal" href="playbooks2.html"><em>Advanced Playbooks</em></a>.</p>
 <p>The acme/setup.yml playbook would be as simple as:</p>
-<div class="highlight-python"><pre>----
+<div class="highlight-python"><pre>---
-
 - hosts: webservers
   user: root
 
@@ -246,7 +241,8 @@ will require <cite>handlers</cite>, <cite>tasks</cite>, and <cite>templates</cit
 are contained in &#8216;acme/handlers/main.yml&#8217;.  As a reminder, handlers are mostly just used to notify services to restart
 when things change, and these are described in <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>.</p>
 <p>Including more than one setup file or more than one handlers file is of course legal.</p>
-<p>Having playbooks be able to include other playbooks is coming in a future release. See Issue 538.</p>
+<p>Having playbooks be able to include other playbooks is coming in a
+future release. See <a class="reference external" href="https://github.com/ansible/ansible/issues/538">Issue 538</a>.</p>
 <p>Until then, to manage your entire site, simply execute all of your playbooks together, in the order desired.
 You don&#8217;t have to do this though. It&#8217;s fine to select sections of your infrastructure to manage at a single time.
 You may wish to construct simple shell scripts to wrap calls to ansible-playbook.</p>
@@ -262,17 +258,39 @@ keep modules that go with a playbook together.</p>
 </div>
 <div class="section" id="miscellaneous-tips">
 <h2>Miscellaneous Tips<a class="headerlink" href="#miscellaneous-tips" title="Permalink to this headline">¶</a></h2>
-<p>When you can do something simply, do something simply.  Do not reach to use every feature of Ansible together, all
+<p>When you can do something simply, do something simply.  Do not reach
-at once.  Use what works for you.  For example, you should probably not need <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">vars_files</span></tt>, <tt class="docutils literal"><span class="pre">vars_prompt</span></tt> and <tt class="docutils literal"><span class="pre">--extra-vars</span></tt> all at once, while also using an external inventory file.</p>
+to use every feature of Ansible together, all at once.  Use what works
-<p>Optimize for readability.  Whitespace between sections of YAML documents and in between tasks is strongly encouraged,
+for you.  For example, you should probably not need &#8216;vars&#8217;,
-as is usage of YAML comments, which start with &#8220;#&#8221;.  It is also useful to comment at the top of each file the purpose of the individual file and the author, including email address.</p>
+&#8216;vars_files&#8217;, &#8216;vars_prompt&#8217; and &#8216;&#8211;extra-vars&#8217; all at once,
-<p>It is possible to leave off the &#8220;name&#8221; for a given task, though it is recommended to provide
+while also using an external inventory file.</p>
-a descriptive comment about why something is being done instead.</p>
+<p>Optimize for readability.  Whitespace between sections of YAML
-<p>Use version control.  Keep your playbooks and inventory file in git (or another version control system), and commit when you make changes to them.
+documents and in between tasks is strongly encouraged, as is usage of
-This way you have an audit trail describing when and why you changed the rules automating your infrastructure.</p>
+YAML comments, which start with &#8216;#&#8217;.  It is also useful to comment
-<p>Resist the urge to write the same playbooks and configuration files for heterogeneous distributions.  While lots of software packages claim to make this easy on you, the configuration files are often quite different, to the point where it would be easier to treat them as different playbooks.  This is why, for example, Ansible has a seperate &#8216;yum&#8217; and &#8216;apt&#8217; module.  Yum and apt have different capabilities, and we don&#8217;t want to code for the least common denominator.</p>
+at the top of each file the purpose of the individual file and the
-<p>Use variables for user tunable settings versus having constants in the tasks file or templates, so that it is easy to reconfigure a playbook.  Think about this as exposing the knobs to things you would like to tweak.</p>
+author, including email address.</p>
-<p>Since a system can be in more than one group, if you have multiple datacenters or sites, consider putting systems into groups by role, but also different groups by geography.  This allows you to assign different variables to different geographies.</p>
+<p>It is possible to leave off the &#8216;name&#8217; for a given task, though it
+is recommended to provide a descriptive comment about why something is
+being done instead.</p>
+<p>Use version control.  Keep your playbooks and inventory file in git
+(or another version control system), and commit when you make changes
+to them.  This way you have an audit trail describing when and why you
+changed the rules automating your infrastructure.</p>
+<p>Resist the urge to write the same playbooks and configuration files
+for heterogeneous distributions.  While lots of software packages
+claim to make this easy on you, the configuration files are often
+quite different, to the point where it would be easier to treat them
+as different playbooks.  This is why, for example, Ansible has a
+separate <a class="reference internal" href="modules.html#yum"><em>yum</em></a> and <a class="reference internal" href="modules.html#apt"><em>apt</em></a> module.  Yum and apt have different
+capabilities, and we don&#8217;t want to code for the least common
+denominator.</p>
+<p>Use variables for user tunable settings versus having constants in the
+tasks file or templates, so that it is easy to reconfigure a playbook.
+Think about this as exposing the knobs to things you would like to
+tweak.</p>
+<p>Since a system can be in more than one group, if you have multiple
+datacenters or sites, consider putting systems into groups by role,
+but also different groups by geography.  This allows you to assign
+different variables to different geographies.</p>
 <div class="admonition-see-also admonition seealso">
 <p class="first admonition-title">See also</p>
 <dl class="last docutils">

modules.html

@@ -305,6 +305,8 @@ apt pkg=openjdk-6-jdk state=latest install-recommends=no</pre>
 </div>
 <div class="section" id="apt-repository">
 <span id="id2"></span><h2>apt_repository<a class="headerlink" href="#apt-repository" title="Permalink to this headline">¶</a></h2>
+<p class="versionadded">
+<span class="versionmodified">New in version 0.7.</span></p>
 <p>Manages apt repositores</p>
 <table border="1" class="docutils">
 <colgroup>
@@ -466,9 +468,13 @@ arguments, space delimited.</p>
 be processed through the shell, so variables like &#8220;$HOME&#8221; and
 operations like &#8220;&lt;&#8221;, &#8220;&gt;&#8221;, &#8220;|&#8221;, and &#8220;&amp;&#8221; will not work.  As such, all
 paths to commands must be fully qualified.</p>
-<p>NOTE:: If you want to run a command through the shell (say you are using
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">If you want to run a command through the shell (say you are using
 &#8216;&lt;&#8217;, &#8216;&gt;&#8217;, &#8216;|&#8217;, etc), you actually want the &#8216;shell&#8217; module instead.
-The &#8216;command&#8217; module is much more secure as it&#8217;s not affected by the user&#8217;s environment.</p>
+The &#8216;command&#8217; module is much more secure as it&#8217;s not affected by
+the user&#8217;s environment.</p>
+</div>
 <p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
 <div class="highlight-python"><pre>command /sbin/shutdown -t now</pre>
 </div>
@@ -521,6 +527,8 @@ relative.</td>
 </div>
 <div class="section" id="easy-install">
 <span id="easyinstall"></span><h2>easy_install<a class="headerlink" href="#easy-install" title="Permalink to this headline">¶</a></h2>
+<p class="versionadded">
+<span class="versionmodified">New in version 0.7.</span></p>
 <p>The easy_install module installs Python libraries.</p>
 <table border="1" class="docutils">
 <colgroup>
@@ -1059,6 +1067,8 @@ from /usr/bin/ansible:</p>
 </div>
 <div class="section" id="pip">
 <span id="id17"></span><h2>pip<a class="headerlink" href="#pip" title="Permalink to this headline">¶</a></h2>
+<p class="versionadded">
+<span class="versionmodified">New in version 0.7.</span></p>
 <p>Manages Python library dependencies.</p>
 <table border="1" class="docutils">
 <colgroup>
@@ -1415,17 +1425,22 @@ but runs the command through the user&#8217;s configured shell on the remote nod
 </tbody>
 </table>
 <p>The given command will be executed on all selected nodes.</p>
-<p>NOTE:: If you want to execute a command securely and predicably, it may
+<div class="admonition note">
-be better to use the &#8216;command&#8217; module instead.  Best practices
+<p class="first admonition-title">Note</p>
-when writing playbooks will follow the trend of using &#8216;command&#8217;
+<p class="last">If you want to execute a command securely and predicably, it may be
-unless &#8216;shell&#8217; is explicitly required.  When running ad-hoc commands,
+better to use the &#8216;command&#8217; module instead.  Best practices when
-use your best judgement.</p>
+writing playbooks will follow the trend of using &#8216;command&#8217; unless
+&#8216;shell&#8217; is explicitly required.  When running ad-hoc commands, use
+your best judgement.</p>
+</div>
 <p>Example action from a playbook:</p>
 <div class="highlight-python"><pre>shell somescript.sh &gt;&gt; somelog.txt</pre>
 </div>
 </div>
 <div class="section" id="supervisorctl">
 <span id="id22"></span><h2>supervisorctl<a class="headerlink" href="#supervisorctl" title="Permalink to this headline">¶</a></h2>
+<p class="versionadded">
+<span class="versionmodified">New in version 0.7.</span></p>
 <p>Manage the state of a program or group of programs running via Supervisord</p>
 <table border="1" class="docutils">
 <colgroup>

playbooks.html

@@ -267,12 +267,19 @@ documentation.  The <cite>user</cite> is just the name of the user account:</p>
 <p>If you need to specify a password to sudo, run <cite>ansible-playbook</cite> with <tt class="docutils literal"><span class="pre">--ask-sudo-pass</span></tt> (<cite>-K</cite>).
 If you run a sudo playbook and the playbook seems to hang, it&#8217;s probably stuck at the sudo prompt.
 Just <cite>Control-C</cite> to kill it and run it again with <cite>-K</cite>.</p>
-<p>NOTE:  When using <cite>sudo_user</cite> to a user other than root, the module arguments are briefly written into
+<div class="admonition important">
-a random tempfile in /tmp.  These are deleted immediately after the command is executed.  This only
+<p class="first admonition-title">Important</p>
-occurs when sudoing from a user like &#8216;bob&#8217; to &#8216;timmy&#8217;, not when going from &#8216;bob&#8217; to &#8216;root&#8217;, or
+<p class="last">When using <cite>sudo_user</cite> to a user other than root, the module
-logging in directly as &#8216;bob&#8217; or &#8216;root&#8217;.  If this concerns you that this data is briefly readable
+arguments are briefly written into a random tempfile in /tmp.
-(not writeable), avoid transferring uncrypted passwords with <cite>sudo_user</cite> set.  In other cases, &#8216;/tmp&#8217; is not used and
+These are deleted immediately after the command is executed.  This
-this does not come into play. Ansible also takes care to not log password parameters.</p>
+only occurs when sudoing from a user like &#8216;bob&#8217; to &#8216;timmy&#8217;, not
+when going from &#8216;bob&#8217; to &#8216;root&#8217;, or logging in directly as &#8216;bob&#8217; or
+&#8216;root&#8217;.  If this concerns you that this data is briefly readable
+(not writeable), avoid transferring uncrypted passwords with
+<cite>sudo_user</cite> set.  In other cases, &#8216;/tmp&#8217; is not used and this does
+not come into play. Ansible also takes care to not log password
+parameters.</p>
+</div>
 </div>
 <div class="section" id="vars-section">
 <h3>Vars section<a class="headerlink" href="#vars-section" title="Permalink to this headline">¶</a></h3>
@@ -459,12 +466,16 @@ 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:: you can not conditionally path the location to an include file, like you can
+<div class="admonition note">
-with &#8216;vars_files&#8217;.  If you find yourself needing to do this, consider how you can
+<p class="first admonition-title">Note</p>
-restructure your playbook to be more class/role oriented.  This is to say you cannot
+<p class="last">You can not conditionally path the location to an include file,
-use a &#8216;fact&#8217; to decide what include file to use.  All hosts contained within the play
+like you can with &#8216;vars_files&#8217;.  If you find yourself needing to do
-are going to get the same tasks.  (&#8216;only_if&#8217; provides some ability for hosts to conditionally
+this, consider how you can restructure your playbook to be more
-skip tasks).</p>
+class/role oriented.  This is to say you cannot use a &#8216;fact&#8217; to
+decide what include file to use.  All hosts contained within the
+play are going to get the same tasks.  (&#8216;only_if&#8217; provides some
+ability for hosts to conditionally skip tasks).</p>
+</div>
 </div>
 <div class="section" id="executing-a-playbook">
 <h2>Executing A Playbook<a class="headerlink" href="#executing-a-playbook" title="Permalink to this headline">¶</a></h2>

playbooks2.html

@@ -274,8 +274,12 @@ that is preferred:</p>
 assigned to another node, it&#8217;s easy to do so within a template or even an action line:</p>
 <div class="highlight-python"><pre>${hostvars.hostname.factname}</pre>
 </div>
-<p>NOTE: No database or other complex system is required to exchange data between hosts.  The hosts that you
+<div class="admonition note">
-want to reference data from must be included in either the current play or any previous play.</p>
+<p class="first admonition-title">Note</p>
+<p class="last">No database or other complex system is required to exchange data
+between hosts.  The hosts that you want to reference data from must
+be included in either the current play or any previous play.</p>
+</div>
 <p>Additionally, <em>group_names</em> is a list (array) of all the groups the current host is in.  This can be used in templates using Jinja2 syntax to make template source files that vary based on the group membership (or role) of the host:</p>
 <div class="highlight-python"><pre>{% if 'webserver' in group_names %}
    # some part of a configuration file that only applies to webservers
@@ -321,7 +325,11 @@ sharing your playbook source with them.</p>
 somevar: somevalue
 password: magic</pre>
 </div>
-<p>NOTE: It&#8217;s also possible to keep per-host and per-group variables in very similar files, this is covered in <a class="reference internal" href="patterns.html#patterns"><em>Inventory &amp; Patterns</em></a>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">It&#8217;s also possible to keep per-host and per-group variables in very
+similar files, this is covered in <a class="reference internal" href="patterns.html#patterns"><em>Inventory &amp; Patterns</em></a>.</p>
+</div>
 </div>
 <div class="section" id="prompting-for-sensitive-data">
 <h2>Prompting For Sensitive Data<a class="headerlink" href="#prompting-for-sensitive-data" title="Permalink to this headline">¶</a></h2>
@@ -421,8 +429,11 @@ but it is easily handled with a minimum of syntax in an Ansible Playbook:</p>
   - name: make sure apache is running
     action: service name=$apache state=running</pre>
 </div>
-<p>Note that a variable (<cite>$facter_operatingsystem</cite>) is being interpolated into the list of
+<div class="admonition note">
-filenames being defined for vars_files.</p>
+<p class="first admonition-title">Note</p>
+<p class="last">The variable (<cite>$facter_operatingsystem</cite>) is being interpolated into
+the list of filenames being defined for vars_files.</p>
+</div>
 <p>As a reminder, the various YAML files contain just keys and values:</p>
 <div class="highlight-python"><pre>---
 # for vars/CentOS.yml