ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

Add docs on only_if

Browse source
This commit is contained in:
Michael DeHaan 2012-03-20 20:15:53 -04:00
parent a98e0a8cc4
commit a045630c02
17 changed files with 191 additions and 99 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
YAMLSyntax.html
View file

@ -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>

2
api.html
View file

@ -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>

2
examples.html
View file

@ -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>

2
faq.html
View file

@ -336,7 +336,7 @@ tasks &#8211; 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>

2
genindex.html
View file

@ -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>

2
gettingstarted.html
View file

@ -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>

9
index.html
View file

@ -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#user-line">User 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#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>

2
man.html
View file

@ -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>

2
man/ansible-playbook.1.html
View file

@ -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>

2
man/ansible.1.html
View file

@ -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>

2
moduledev.html
View file

@ -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>

2
modules.html
View file

@ -415,7 +415,7 @@ various configuration attributes. Values include &#8216;installed&#8217;, &#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>

2
patterns.html
View file

@ -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>

129
playbooks.html
View file

@ -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="#user-line">User line</a></li>
<li><a class="reference internal" href="#hosts-and-users">Hosts and Users</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">
<h3>Hosts line<a class="headerlink" href="#hosts-line" title="Permalink to this headline"></a></h3>
<div class="section" id="hosts-and-users">
<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
<cite>/usr/bin/ansible</cite>.</p>
<p>Each play gets to designate it&#8217;s own choice of patterns.</p>
</div>
<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>
documentation. The <cite>user</cite> is just the name of the user account:</p>
<div class="highlight-python"><pre>---
- hosts: webservers
user: root</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
can be used in templates or tasks and are dereferenced using
`jinja2</cite> syntax like this:</p>
<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>
<div class="highlight-python"><pre>---
- 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
same command again, which is totally ok if the command is something
like &#8216;chmod&#8217; or &#8216;setsebool&#8217;, etc.</p>
</div>
<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>
unless they have to change things.</p>
<p>Command will actually rerun the same command again,
which is totally ok if the command is something like
&#8216;chmod&#8217; or &#8216;setsebool&#8217;, etc.</p>
<p>Every task must have a name, which is included in the output from
running the playbook.</p>
<p>The action line is the name of an ansible module followed by
parameters in key=value form:</p>
<div class="highlight-python"><pre>- name: make sure apache is running
action: service name=httpd state=running</pre>
running the playbook. This is output for humans, so it is
nice to have reasonably good descriptions of each task step.</p>
<p>Here is what a basic task looks like, as with most modules,
the service module takes key=value arguments:</p>
<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>
<div class="highlight-python"><pre>- name: disable selinux
action: command /sbin/setenforce 0</pre>
of arguments, and doesn&#8217;t use the key=value form. This makes
it work just like you would expect. Simple:</p>
<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
action: template src=somefile.j2 dest=/etc/httpd/conf.d/{{ vhost }}</pre>
<div class="highlight-python"><pre>tasks:
- 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">
<h2>Notify statements &amp; Handlers<a class="headerlink" href="#notify-statements-handlers" 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
<div class="section" id="running-operations-on-change">
<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 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>
<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>
<p>The things listed in the &#8216;notify&#8217; section of a task are called
handlers.</p>
<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>

124
rst/playbooks.rst
View file

@ -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
`/usr/bin/ansible`.
documentation. The `user` is just the name of the user account::
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,
but you can specify others. Sudo support is pending.::
Support for running things from sudo is pending.
user: mdehaan
Vars section
++++++++++++
The `vars' section contains a list of variables and values that can be used in the plays. These
can be used in templates or tasks and are dereferenced using
`jinja2` syntax like this::
The `vars' section contains a list of variables and values that can be used in the plays, 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
same command again, which is totally ok if the command is something
like 'chmod' or 'setsebool', etc.
unless they have to change things.
Task name and action
++++++++++++++++++++
Command will actually rerun the same command again,
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
parameters in key=value form::
Here is what a basic task looks like, as with most modules,
the service module takes key=value arguments::
- name: make sure apache is running
action: service name=httpd state=running
tasks:
- 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
action: command /sbin/setenforce 0
tasks:
- 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
action: template src=somefile.j2 dest=/etc/httpd/conf.d/{{ vhost }}
tasks:
- 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.
.. note::
Notify handlers are always run in the order written.
The things listed in the 'notify' section of a task are called
handlers.
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
+++++++++++++++++++

2
search.html
View file

@ -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>

2
searchindex.js
View file

File diff suppressed because one or more lines are too long