@ -320,7 +320,7 @@ Stop by the mailing list if you have ideas.</p>
example is for configuration management where you
are starting from a clean OS with no extra software installed, adopting systems
that are already deployed.</p>
<p>Ansible is also great for running ad-hoc tasks across a wide variety of Linux, Unix, and <ahref="#id1"><spanclass="problematic"id="id2">*</span></a>BSDs.
<p>Ansible is also great for running ad-hoc tasks across a wide variety of Linux, Unix, and BSDs.
Because it just uses the basic tools available on the system, it is exceptionally cross platform
without needing to install management packages on each node.</p>
<liclass="toctree-l2"><aclass="reference internal"href="playbooks.html#using-includes-to-assign-classes-of-systems">Using Includes To Assign Classes of Systems</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="playbooks.html#asynchronous-actions-and-polling">Asynchronous Actions and Polling</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#external-variables-and-sensitive-data">External Variables And Sensitive Data</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#include-files-and-reuse">Include Files And Reuse</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#using-includes-to-assign-classes-of-systems">Using Includes To Assign Classes of Systems</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#asynchronous-actions-and-polling">Asynchronous Actions and Polling</a></li>
</ul>
</li>
<liclass="toctree-l2"><aclass="reference internal"href="playbooks.html#executing-a-playbook">Executing A Playbook</a></li>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<htmlxmlns="http://www.w3.org/1999/xhtml"><head><metahttp-equiv="Content-Type"content="text/html; charset=UTF-8"/><title>ansible-playbook</title><linkrel="stylesheet"href="./docbook-xsl.css"type="text/css"/><metaname="generator"content="DocBook XSL Stylesheets V1.75.2"/></head><body><divxml:lang="en"class="refentry"title="ansible-playbook"lang="en"><aid="id446525"></a><divclass="titlepage"></div><divclass="refnamediv"><h2>Name</h2><p>ansible-playbook — run an ansible playbook</p></div><divclass="refsynopsisdiv"title="Synopsis"><aid="_synopsis"></a><h2>Synopsis</h2><p>ansible-playbook <filename.yml> … [options]</p></div><divclass="refsect1"title="DESCRIPTION"><aid="_description"></a><h2>DESCRIPTION</h2><p><spanclass="strong"><strong>Ansible playbooks</strong></span> are a configuration and multinode deployment system. Ansible-playbook is the tool
<htmlxmlns="http://www.w3.org/1999/xhtml"><head><metahttp-equiv="Content-Type"content="text/html; charset=UTF-8"/><title>ansible-playbook</title><linkrel="stylesheet"href="./docbook-xsl.css"type="text/css"/><metaname="generator"content="DocBook XSL Stylesheets V1.75.2"/></head><body><divxml:lang="en"class="refentry"title="ansible-playbook"lang="en"><aid="id320402"></a><divclass="titlepage"></div><divclass="refnamediv"><h2>Name</h2><p>ansible-playbook — run an ansible playbook</p></div><divclass="refsynopsisdiv"title="Synopsis"><aid="_synopsis"></a><h2>Synopsis</h2><p>ansible-playbook <filename.yml> … [options]</p></div><divclass="refsect1"title="DESCRIPTION"><aid="_description"></a><h2>DESCRIPTION</h2><p><spanclass="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><divclass="refsect1"title="ARGUMENTS"><aid="_arguments"></a><h2>ARGUMENTS</h2><divclass="variablelist"><dl><dt><spanclass="term">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<htmlxmlns="http://www.w3.org/1999/xhtml"><head><metahttp-equiv="Content-Type"content="text/html; charset=UTF-8"/><title>ansible</title><linkrel="stylesheet"href="./docbook-xsl.css"type="text/css"/><metaname="generator"content="DocBook XSL Stylesheets V1.75.2"/></head><body><divxml:lang="en"class="refentry"title="ansible"lang="en"><aid="id302038"></a><divclass="titlepage"></div><divclass="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><divclass="refsynopsisdiv"title="Synopsis"><aid="_synopsis"></a><h2>Synopsis</h2><p>ansible <host-pattern> [-f forks] [-m module_name] [-a args]</p></div><divclass="refsect1"title="DESCRIPTION"><aid="_description"></a><h2>DESCRIPTION</h2><p><spanclass="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
<htmlxmlns="http://www.w3.org/1999/xhtml"><head><metahttp-equiv="Content-Type"content="text/html; charset=UTF-8"/><title>ansible</title><linkrel="stylesheet"href="./docbook-xsl.css"type="text/css"/><metaname="generator"content="DocBook XSL Stylesheets V1.75.2"/></head><body><divxml:lang="en"class="refentry"title="ansible"lang="en"><aid="id570190"></a><divclass="titlepage"></div><divclass="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><divclass="refsynopsisdiv"title="Synopsis"><aid="_synopsis"></a><h2>Synopsis</h2><p>ansible <host-pattern> [-f forks] [-m module_name] [-a args]</p></div><divclass="refsect1"title="DESCRIPTION"><aid="_description"></a><h2>DESCRIPTION</h2><p><spanclass="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
@ -227,19 +236,28 @@ server group, then more commands back on the webservers group, etc:</p>
handlers:
- include: handlers.yml</pre>
</div>
<p>Below, we’ll break down what the various features of the playbook language are.</p>
</div>
<divclass="section"id="hosts-line">
<h2>Hosts line<aclass="headerlink"href="#hosts-line"title="Permalink to this headline">¶</a></h2>
<p>The hosts line is a list of one or more groups or host patterns,
<p>The <cite>hosts</cite> line is a list of one or more groups or host patterns,
separated by colons, as described in the <aclass="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’s own choice of patterns.</p>
</div>
<divclass="section"id="user-line">
<h2>User line<aclass="headerlink"href="#user-line"title="Permalink to this headline">¶</a></h2>
<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>
<h3>External Variables And Sensitive Data<aclass="headerlink"href="#external-variables-and-sensitive-data"title="Permalink to this headline">¶</a></h3>
<p>It’s a great idea to keep your playbooks under source control, but
you may wish to make the playbook source public while keeping certain
important variables private. You can do this by using an external
variables file, or files, just like this:</p>
<divclass="highlight-python"><pre>---
- hosts: all
user: root
vars:
favcolor: blue
vars_files:
- /path/to/external_vars.yml
tasks:
- name: this is just a placeholder
action: command /bin/echo foo</pre>
</div>
<p>This removes the risk of sharing sensitive data with others when
sharing your playbook source with them.</p>
<p>The contents of each variables file is a simple YAML dictionary, like this:</p>
<divclass="highlight-python"><pre>---
somevar: somevalue
password: magic</pre>
</div>
</div>
<divclass="section"id="include-files-and-reuse">
<h3>Include Files And Reuse<aclass="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
include files to do this.</p>
<p>An include file simply contains a list of tasks, like so:</p>
<divclass="highlight-python"><pre>---
- name: placeholder foo
action: command /bin/foo
- name: placeholder bar
action: command /bin/bar</pre>
</div>
<p>Variables passed in can be deferenced too. Assume a variable named ‘user’. Using
<cite>jinja2</cite> syntax, anywhere in the included file, you can say:</p>
<divclass="highlight-python"><pre>{{ user }}</pre>
</div>
<p>For instance, if deploying multiple wordpress instances, I could
contain all of my tasks in a wordpress.yml file, and use it like so:</p>
contain all of my wordpress tasks in a single wordpress.yml file, and use it like so:</p>
<divclass="highlight-python"><pre>- tasks:
- include: wordpress.yml user=timmy
- include: wordpress.yml user=alice
- include: wordpress.yml user=bob</pre>
- include: wordpress.yml user=timmy
- include: wordpress.yml user=alice
- include: wordpress.yml user=bob</pre>
</div>
<p>In addition to the explicitly passed in parameters, all variables from
the vars section are also available.</p>
<p>The format of an included list of tasks or handlers looks just like a
flat list of tasks. Here is an example of what base.yml might look
like:</p>
<divclass="highlight-python"><pre>---
- name: no selinux
action: command /usr/sbin/setenforce 0
- name: no iptables
action: service name=iptables state=stopped
- name: this is just to show variables work here, favcolor={{ favcolor }}
action: command /bin/true</pre>
</div>
<p>As you can see above, variables in include files work just like they
do in the main file. Including a variable in the name of a task is a
contrived example, you could also pass them to the action command line
or use them inside a template file.</p>
the vars section are also available for use here as well. Variables that bubble
up from tools like facter and ohai are not though – but they ARE available for use
inside ‘action’ lines.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Note that include statements are only usable from the top level
playbook file. At this time, includes can not include other
<pclass="last">Include statements are only usable from the top level
playbook file. This means includes can not include other
includes.</p>
</div>
<p>Includes can also be used in the ‘handlers’ section, for instance, if you
want to define how to restart apache, you only have to do that once for all
of your playbooks. You might make a notifiers.yaml that looked like:</p>
<divclass="highlight-python"><pre>----
- name: restart apache
action: service name=apache state=restarted</pre>
</div>
<p>And in your main playbook file, just include it like so, at the bottom
of a play:</p>
<divclass="highlight-python"><pre>handlers:
- include: handlers.yml</pre>
</div>
<p>You can mix in includes along with your regular non-included tasks and handlers.</p>
<h2>Using Includes To Assign Classes of Systems<aclass="headerlink"href="#using-includes-to-assign-classes-of-systems"title="Permalink to this headline">¶</a></h2>
<p>Include files are best used to reuse logic between playbooks. You
<h3>Using Includes To Assign Classes of Systems<aclass="headerlink"href="#using-includes-to-assign-classes-of-systems"title="Permalink to this headline">¶</a></h3>
<p>Include files are really powerful when used to reuse logic between playbooks. You
could imagine a playbook describing your entire infrastructure like
this:</p>
this, in a list of just a few plays:</p>
<divclass="highlight-python"><pre>---
- hosts: atlanta-webservers
vars:
@ -366,22 +448,71 @@ this:</p>
- include: generic-handlers.yml</pre>
</div>
<p>There is one (or more) play defined for each group of systems, and
each play maps each group includes one or more ‘class definitions’
telling the systems what they are supposed to do or be.</p>
<p>Using a common handlers file could allow one task in ‘webservers’ to
define ‘restart apache’, and it could be reused between multiple
plays.</p>
<p>Variables like ‘database’ above can be used in templates referenced
from the configuration file to generate machine specific variables.</p>
each play maps each group to several includes. These includes represent
‘class definitions’, telling the systems what they are supposed to do or be.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Playbooks do not always have to be declarative; you can do something
similar to model a push process for a multi-tier web application. This is
actually one of the things playbooks were invented to do.</p>
Michael DeHaan
14 years ago