mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
683 lines
No EOL
33 KiB
HTML
683 lines
No EOL
33 KiB
HTML
|
|
<!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>Playbooks — Ansible - SSH-Based Configuration Management & Deployment</title>
|
|
<link rel="stylesheet" href="_static/default.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/bootstrap.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: '',
|
|
VERSION: '0.01',
|
|
COLLAPSE_INDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: false
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
<script type="text/javascript" src="_static/bootstrap-dropdown.js"></script>
|
|
<script type="text/javascript" src="_static/bootstrap-scrollspy.js"></script>
|
|
<link rel="shortcut icon" href="_static/favicon.ico"/>
|
|
<link rel="top" title="Ansible - SSH-Based Configuration Management & Deployment" href="index.html" />
|
|
<link rel="next" title="API & Integrations" href="api.html" />
|
|
<link rel="prev" title="YAML Syntax" href="YAMLSyntax.html" />
|
|
<script type="text/javascript">
|
|
(function () {
|
|
/**
|
|
* Patch TOC list.
|
|
*
|
|
* Will mutate the underlying span to have a correct ul for nav.
|
|
*
|
|
* @param $span: Span containing nested UL's to mutate.
|
|
* @param minLevel: Starting level for nested lists. (1: global, 2: local).
|
|
*/
|
|
var patchToc = function ($span, minLevel) {
|
|
var $tocList = $("<ul/>").attr('class', "dropdown-menu"),
|
|
findA;
|
|
|
|
// Find all a "internal" tags, traversing recursively.
|
|
findA = function ($elem, level) {
|
|
var level = level || 0,
|
|
$items = $elem.find("> li > a.internal, > ul, > li > ul");
|
|
|
|
// Iterate everything in order.
|
|
$items.each(function (index, item) {
|
|
var $item = $(item),
|
|
tag = item.tagName.toLowerCase(),
|
|
pad = 10 + ((level - minLevel) * 10);
|
|
|
|
if (tag === 'a' && level >= minLevel) {
|
|
// Add to existing padding.
|
|
$item.css('padding-left', pad + "px");
|
|
// Add list element.
|
|
$tocList.append($("<li/>").append($item));
|
|
} else if (tag === 'ul') {
|
|
// Recurse.
|
|
findA($item, level + 1);
|
|
}
|
|
});
|
|
};
|
|
|
|
// Start construction and return.
|
|
findA($span);
|
|
|
|
// Wipe out old list and patch in new one.
|
|
return $span.empty("ul").append($tocList);
|
|
};
|
|
|
|
$(document).ready(function () {
|
|
// Patch the global and local TOC's to be bootstrap-compliant.
|
|
patchToc($("span.globaltoc"), 1);
|
|
patchToc($("span.localtoc"), 2);
|
|
|
|
// Activate.
|
|
$('#topbar').dropdown();
|
|
});
|
|
}());
|
|
</script>
|
|
<script type="text/javascript">
|
|
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-29861888-1']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type =
|
|
'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
|
|
'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0];
|
|
s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
|
|
</script>
|
|
|
|
</head>
|
|
<body>
|
|
<div class="topbar" data-scrollspy="scrollspy" >
|
|
<div class="topbar-inner">
|
|
<div class="container">
|
|
<!-- <a class="brand" href="index.html">Ansible</a> -->
|
|
<ul class="nav">
|
|
|
|
<li class="dropdown" data-dropdown="dropdown">
|
|
<a href="index.html"
|
|
class="dropdown-toggle">Chapter</a>
|
|
<span class="globaltoc"><ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Downloads & Getting Started</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="patterns.html">The Inventory File, Patterns, and Groups</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="modules.html">Ansible Modules</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="">Playbooks</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
|
|
</ul>
|
|
</span>
|
|
</li>
|
|
<li class="dropdown" data-dropdown="dropdown">
|
|
<a href="#"
|
|
class="dropdown-toggle">Page</a>
|
|
<span class="localtoc"><ul>
|
|
<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-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>
|
|
</ul>
|
|
</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="#local-playbooks">Local Playbooks</a></li>
|
|
<li><a class="reference internal" href="#external-variables-and-prompted-or-sensitive-data">External Variables And Prompted or 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>
|
|
<li><a class="reference internal" href="#loop-shorthand">Loop Shorthand</a></li>
|
|
<li><a class="reference internal" href="#asynchronous-actions-and-polling">Asynchronous Actions and Polling</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#executing-a-playbook">Executing A Playbook</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</span>
|
|
</li>
|
|
|
|
</ul>
|
|
<ul class="nav secondary-nav">
|
|
|
|
|
|
<form class="pull-left" action="search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<a href="http://github.com/ansible/ansible"><img style="position: absolute; right: 0; border: 0;" src="https://a248.e.akamai.net/assets.github.com/img/e6bef7a091f5f3138b8cd40bc3e114258dd68ddf/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f7265645f6161303030302e706e67" alt="Fork me on GitHub"></a>
|
|
|
|
|
|
<div class="container">
|
|
<a href="http://ansible.github.com"><img src="http://ansible.github.com/ansible-logo.png" alt="Ansible"/></a><br/>
|
|
|
|
<div class="section" id="playbooks">
|
|
<h1>Playbooks<a class="headerlink" href="#playbooks" title="Permalink to this headline">¶</a></h1>
|
|
<p>Playbooks are a completely different way to use ansible and are
|
|
particularly awesome. They are the basis for a really simple
|
|
configuration management and multi-machine deployment system,
|
|
unlike any that already exist, and
|
|
one that is very well suited to deploying complex applications.</p>
|
|
<p>Playbooks can declare configurations, but they can also orchestrate steps of
|
|
any manual ordered process, even as different steps must bounce back and forth
|
|
between sets of machines in particular orders. They can launch tasks
|
|
synchronously or asynchronously.</p>
|
|
<p>While you might run the main /usr/bin/ansible program for ad-hoc
|
|
tasks, playbooks are more likely to be kept in source control and used
|
|
to push out your configuration or assure the configurations of your
|
|
remote systems are in spec.</p>
|
|
<p>Let’s dive in and see how they work. As you go, you may wish to open
|
|
the <a class="reference external" href="https://github.com/ansible/ansible/tree/master/examples/playbooks">github examples directory</a> in
|
|
another tab, so you can apply the theory to what things look like in practice.</p>
|
|
<div class="section" id="playbook-example">
|
|
<h2>Playbook Example<a class="headerlink" href="#playbook-example" title="Permalink to this headline">¶</a></h2>
|
|
<p>Playbooks are expressed in YAML format and have a minimum of syntax.
|
|
Each playbook is composed of one or more ‘plays’ in a list.</p>
|
|
<p>By composing a playbook of multiple ‘plays’, it is possible to
|
|
orchestrate multi-machine deployments, running certain steps on all
|
|
machines in the webservers group, then certain steps on the database
|
|
server group, then more commands back on the webservers group, etc.</p>
|
|
<p>For starters, here’s a playbook that contains just one play:</p>
|
|
<div class="highlight-python"><pre>---
|
|
- hosts: webservers
|
|
vars:
|
|
http_port: 80
|
|
max_clients: 200
|
|
user: root
|
|
tasks:
|
|
- name: ensure apache is at the latest version
|
|
action: yum pkg=httpd state=latest
|
|
- name: write the apache config file
|
|
action: template src=/srv/httpd.j2 dest=/etc/httpd.conf
|
|
notify:
|
|
- restart apache
|
|
- name: ensure apache is running
|
|
action: service name=httpd state=started
|
|
handlers:
|
|
- name: restart apache
|
|
action: service name=apache state=restarted</pre>
|
|
</div>
|
|
<p>Below, we’ll break down what the various features of the playbook language are.</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-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. 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 also available:</p>
|
|
<div class="highlight-python"><pre>---
|
|
- hosts: webservers
|
|
user: yourname
|
|
sudo: True</pre>
|
|
</div>
|
|
<p>If you need to specify a password to sudo, run <cite>ansible-playbook</cite> with <cite>–ask-sudo-pass</cite> (<cite>-K</cite>).
|
|
If you run a sudo playbook and the playbook seems to hang, it’s probably stuck at the sudo prompt.
|
|
Just <cite>Control-C</cite> to kill it and run it again with <cite>-K</cite>.</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</cite> 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’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 (ansible provides some of these,
|
|
plus we include ones taken from facter or ohai if installed) these variables bubble up back into the
|
|
playbook, and can be used on each system just like explicitly set
|
|
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>. Ansible variables (0.3 and later)
|
|
are not surprisingly prefixed with <tt class="docutils literal"><span class="pre">ansible_</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
|
|
action: template src=/srv/templates/motd.j2 dest=/etc/motd</pre>
|
|
</div>
|
|
<p>And in /srv/templates/motd.j2:</p>
|
|
<div class="highlight-python"><pre>You are logged into {{ facter_hostname }}</pre>
|
|
</div>
|
|
<p>But we’re getting ahead of ourselves. Let’s talk about tasks.</p>
|
|
</div>
|
|
<div class="section" id="tasks-list">
|
|
<h3>Tasks list<a class="headerlink" href="#tasks-list" title="Permalink to this headline">¶</a></h3>
|
|
<p>Each play contains a list of tasks. Tasks are executed in order, one
|
|
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 ‘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.</p>
|
|
<p>Command will actually rerun the same command again,
|
|
which is totally ok if the command is something like
|
|
‘chmod’ or ‘setsebool’, etc.</p>
|
|
<p>Every task must have a name, which is included in the output from
|
|
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’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 ‘vhost’ in the ‘vars’ section, you could do this:</p>
|
|
<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’ll get to later.</p>
|
|
</div>
|
|
</div>
|
|
<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’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.</p>
|
|
<p>These ‘notify’ actions are triggered at the end of each ‘play’ in a playbook, and
|
|
trigger only once each. For instance, multiple resources may indicate
|
|
that apache needs to be restarted, but apache will only be bounced once.</p>
|
|
<p>Here’s an example of restarting two services when the contents of a file
|
|
change, but only if the file changes:</p>
|
|
<div class="highlight-python"><pre>- name: template configuration file
|
|
action: template src=template.j2 dest=/etc/foo.conf
|
|
notify:
|
|
- restart memcached
|
|
- restart apache</pre>
|
|
</div>
|
|
<p>The things listed in the ‘notify’ 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
|
|
of how many things notify a handler, it will run only once, after all
|
|
of the tasks complete in a particular play.</p>
|
|
<p>Here’s an example handlers section:</p>
|
|
<div class="highlight-python"><pre>handlers:
|
|
- name: restart memcached
|
|
action: service name=memcached state=restarted
|
|
- name: restart apache
|
|
action: service name=apache state=restarted</pre>
|
|
</div>
|
|
<p>Handlers are best used to restart services and trigger reboots. You probably
|
|
won’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>
|
|
<p>Now that you have the basics down, let’s learn some more advanced
|
|
things you can do with playbooks.</p>
|
|
<div class="section" id="local-playbooks">
|
|
<h3>Local Playbooks<a class="headerlink" href="#local-playbooks" title="Permalink to this headline">¶</a></h3>
|
|
<p>It may be useful to use a playbook locally, rather than by connecting over SSH. This can be useful
|
|
for assuring the configuration of a system by putting a playbook on a crontab. This may also be used
|
|
to run a playbook inside a OS installer, such as an Anaconda kickstart.</p>
|
|
<p>To run an entire playbook locally, just set the “hosts:” line to “hosts:127.0.0.1” and then run the playbook like so:</p>
|
|
<div class="highlight-python"><pre>playbook playbook.yml --connection=local</pre>
|
|
</div>
|
|
<p>Alternatively, a local connection can be used in a single playbook play, even if other plays in the playbook
|
|
use the default remote connection type:</p>
|
|
<div class="highlight-python"><pre>hosts: 127.0.0.1
|
|
connection: local</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="external-variables-and-prompted-or-sensitive-data">
|
|
<h3>External Variables And Prompted or Sensitive Data<a class="headerlink" href="#external-variables-and-prompted-or-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. Similarly, sometimes you may just
|
|
want to keep certain information in different files, away from
|
|
the main playbook.</p>
|
|
<p>You can do this by using an external variables file, or files, just like this:</p>
|
|
<div class="highlight-python"><pre>---
|
|
- hosts: all
|
|
user: root
|
|
vars:
|
|
favcolor: blue
|
|
vars_files:
|
|
- /vars/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>
|
|
<div class="highlight-python"><pre>---
|
|
# in the above example, this would be vars/external_vars.yml
|
|
somevar: somevalue
|
|
password: magic</pre>
|
|
</div>
|
|
<p>Alternatively, you may wish to prompt the user for certain input, and can
|
|
do so with the similarly named ‘vars_prompt’ section. This has uses
|
|
beyond security, for instance, you may use the same playbook for all
|
|
software releases and would prompt for a particular release version
|
|
in a push-script:</p>
|
|
<div class="highlight-python"><pre>---
|
|
- hosts: all
|
|
user: root
|
|
vars:
|
|
from: "camelot"
|
|
vars_prompt:
|
|
name: "what is your name?"
|
|
quest: "what is your quest?"
|
|
favcolor: "what is your favorite color?"</pre>
|
|
</div>
|
|
<p>There are full examples of both of these items in the github examples/playbooks directory.</p>
|
|
</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’t panic – it’s actually
|
|
pretty simple:</p>
|
|
<div class="highlight-python"><pre>vars:
|
|
favcolor: blue
|
|
is_favcolor_blue: "'$favcolor' == 'blue'"
|
|
is_centos: "'$facter_operatingsystem' == 'CentOS'"
|
|
tasks:
|
|
- name: "shutdown if my favorite color is blue"
|
|
action: command /sbin/shutdown -t now
|
|
only_if: '$is_favcolor_blue'</pre>
|
|
</div>
|
|
<p>Variables from tools like <cite>facter</cite> and <cite>ohai</cite> can be used here, if installed, or you can
|
|
use variables that bubble up from ansible (0.3 and later). As a reminder,
|
|
these variables are prefixed, so it’s <cite>$facter_operatingsystem</cite>, not <cite>$operatingsystem</cite>. Ansible’s
|
|
built in variables are prefixed with <cite>ansible_</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>. It is a good idea to use ‘vars_files’ instead of ‘vars’ to define
|
|
all of your conditional expressions in a way that makes them very easy to reuse between plays
|
|
and playbooks.</p>
|
|
</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 ‘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.</p>
|
|
<p>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:</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’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.</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
|
|
include files to do this.</p>
|
|
<p>An include file simply contains a flat list of tasks, like so:</p>
|
|
<div class="highlight-python"><pre>---
|
|
# possibly saved as tasks/foo.yml
|
|
- name: placeholder foo
|
|
action: command /bin/foo
|
|
- name: placeholder bar
|
|
action: command /bin/bar</pre>
|
|
</div>
|
|
<p>Include directives look like this:</p>
|
|
<div class="highlight-python"><pre>- tasks:
|
|
- include: tasks/foo.yml</pre>
|
|
</div>
|
|
<p>Variables passed in can be used in the include files too. Assume a variable named ‘user’. Using
|
|
<cite>jinja2</cite> syntax, anywhere in the included file, you can say:</p>
|
|
<div class="highlight-python"><pre>{{ user }}</pre>
|
|
</div>
|
|
<p>I can also pass variables into includes directly. We might call this a ‘parameterized include’.</p>
|
|
<p>For instance, if deploying multiple wordpress instances, I could
|
|
contain all of my wordpress tasks in a single wordpress.yml file, and use it like so:</p>
|
|
<div class="highlight-python"><pre>- tasks:
|
|
- 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 for use here as well. Variables that bubble
|
|
up from tools like facter and ohai are not usable here though – but they ARE available for use
|
|
inside ‘action’ lines and in templates.</p>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="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>
|
|
<div class="highlight-python"><pre>----
|
|
# this might be in a file like handlers/handlers.yml
|
|
- 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>
|
|
<div class="highlight-python"><pre>handlers:
|
|
- 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 ‘vars_files’. 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>
|
|
<p>Include files are really powerful when used to reuse logic between playbooks. You
|
|
could imagine a playbook describing your entire infrastructure like
|
|
this, in a list of just a few plays:</p>
|
|
<div class="highlight-python"><pre>---
|
|
- hosts: atlanta-webservers
|
|
vars:
|
|
datacenter: atlanta
|
|
tasks:
|
|
- include: tasks/base.yml
|
|
- include: tasks/webservers.yml database=db.atlanta.com
|
|
handlers:
|
|
- include: handlers/common.yml
|
|
- hosts: atlanta-dbservers
|
|
vars:
|
|
datacenter: atlanta
|
|
tasks:
|
|
- include: tasks/base.yml
|
|
- include: tasks/dbservers.yml
|
|
handlers:
|
|
- include: handlers/common.yml</pre>
|
|
</div>
|
|
<p>There is one (or more) play defined for each group of systems, and
|
|
each play maps each group to several includes. These includes represent
|
|
‘class definitions’, telling the systems what they are supposed to do or be.
|
|
In the above example, all hosts get the base configuration first and further
|
|
customize it depending on what class or nature of machines they are.</p>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="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>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="loop-shorthand">
|
|
<h3>Loop Shorthand<a class="headerlink" href="#loop-shorthand" title="Permalink to this headline">¶</a></h3>
|
|
<p>To save some typing, repeated tasks can be written in short-hand like so:</p>
|
|
<div class="highlight-python"><pre>- name: add user $item
|
|
action: user name=$item state=present groups=wheel
|
|
with_items:
|
|
- testuser1
|
|
- testuser2</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="asynchronous-actions-and-polling">
|
|
<h3>Asynchronous Actions and Polling<a class="headerlink" href="#asynchronous-actions-and-polling" title="Permalink to this headline">¶</a></h3>
|
|
<p>By default tasks in playbooks block, meaning the connections stay open
|
|
until the task is done on each node. If executing playbooks with
|
|
a small parallelism value (aka <cite>–forks</cite>), you may wish that long
|
|
running operations can go faster. The easiest way to do this is
|
|
to kick them off all at once and then poll until they are done.</p>
|
|
<p>You will also want to use asynchronous mode on very long running
|
|
operations that might be subject to timeout.</p>
|
|
<p>To launch a task asynchronously, specify its maximum runtime
|
|
and how frequently you would like to poll for status. The default
|
|
poll value is 10 seconds if you do not specify a value for <cite>poll</cite>:</p>
|
|
<div class="highlight-python"><pre>---
|
|
- hosts: all
|
|
user: root
|
|
tasks:
|
|
- name: simulate long running op (15 sec), wait for up to 45, poll every 5
|
|
action: command /bin/sleep 15
|
|
async: 45
|
|
poll: 5</pre>
|
|
</div>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">There is no default for the async time limit. If you leave off the
|
|
‘async’ keyword, the task runs synchronously, which is Ansible’s
|
|
default.</p>
|
|
</div>
|
|
<p>Alternatively, if you do not need to wait on the task to complete, you may
|
|
“fire and forget” by specifying a poll value of 0:</p>
|
|
<div class="highlight-python"><pre>---
|
|
- hosts: all
|
|
user: root
|
|
tasks:
|
|
- name: simulate long running op, allow to run for 45, fire and forget
|
|
action: command /bin/sleep 15
|
|
async: 45
|
|
poll: 0</pre>
|
|
</div>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">You shouldn’t “fire and forget” with operations that require
|
|
exclusive locks, such as yum transactions, if you expect to run other
|
|
commands later in the playbook against those same resources.</p>
|
|
</div>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">Using a higher value for <cite>–forks</cite> will result in kicking off asynchronous
|
|
tasks even faster. This also increases the efficiency of polling.</p>
|
|
</div>
|
|
</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>
|
|
<p>Now that you’ve learned playbook syntax, how do you run a playbook? It’s simple.
|
|
Let’s run a playbook using a parallelism level of 10:</p>
|
|
<div class="highlight-python"><pre>ansible-playbook playbook.yml -f 10</pre>
|
|
</div>
|
|
<div class="admonition-see-also admonition seealso">
|
|
<p class="first admonition-title">See also</p>
|
|
<dl class="last docutils">
|
|
<dt><a class="reference internal" href="YAMLSyntax.html"><em>YAML Syntax</em></a></dt>
|
|
<dd>Learn about YAML syntax</dd>
|
|
<dt><a class="reference internal" href="modules.html"><em>Ansible Modules</em></a></dt>
|
|
<dd>Learn about available modules</dd>
|
|
<dt><a class="reference internal" href="moduledev.html"><em>Module Development Guide</em></a></dt>
|
|
<dd>Learn how to extend Ansible by writing your own modules</dd>
|
|
<dt><a class="reference internal" href="patterns.html"><em>The Inventory File, Patterns, and Groups</em></a></dt>
|
|
<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>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
<footer class="footer">
|
|
<div class="container">
|
|
<p class="pull-right"><a href="#">Back to top</a></p>
|
|
<p>
|
|
© Copyright 2012 Michael DeHaan.<br/>
|
|
Last updated on Apr 21, 2012.<br/>
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
|
|
</p>
|
|
</div>
|
|
</footer>
|
|
</body>
|
|
</html> |