mirror of https://github.com/ansible/ansible.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
549 lines
25 KiB
HTML
549 lines
25 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="top" title="Ansible - SSH-Based Configuration Management & Deployment" href="index.html" />
|
|
<link rel="next" title="Using the Python API" 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">Site</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">Using the Python API</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</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="#hosts-line">Hosts line</a></li>
|
|
<li><a class="reference internal" href="#user-line">User line</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>
|
|
<li><a class="reference internal" href="#notify-statements">Notify statements</a></li>
|
|
<li><a class="reference internal" href="#handlers">Handlers</a></li>
|
|
<li><a class="reference internal" href="#power-tricks">Power Tricks</a><ul>
|
|
<li><a class="reference internal" href="#external-variables-and-sensitive-data">External Variables And Sensitive Data</a></li>
|
|
<li><a class="reference internal" href="#include-files-and-reuse">Include Files And Reuse</a></li>
|
|
<li><a class="reference internal" href="#using-includes-to-assign-classes-of-systems">Using Includes To Assign Classes of Systems</a></li>
|
|
<li><a class="reference internal" href="#asynchronous-actions-and-polling">Asynchronous Actions and Polling</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#executing-a-playbook">Executing A Playbook</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</span>
|
|
</li>
|
|
|
|
|
|
|
|
<li><a href="YAMLSyntax.html"
|
|
title="previous chapter">« YAML Syntax</a></li>
|
|
<li><a href="api.html"
|
|
title="next chapter">Using the Python API »</a></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="https://github.com/ansible/ansible"><img
|
|
style="position: absolute; top: 40px; right: 0; border: 0;"
|
|
src="https://a248.e.akamai.net/assets.github.com/img/71eeaab9d563c2b3c590319b398dd35683265e85/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677261795f3664366436642e706e67"
|
|
alt="Fork me on GitHub"
|
|
alt="Fork me on GitHub"></a>
|
|
<div class="container">
|
|
|
|
<div class="section" id="playbooks">
|
|
<h1>Playbooks<a class="headerlink" href="#playbooks" title="Permalink to this headline">¶</a></h1>
|
|
<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 and writing your own</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>
|
|
</dl>
|
|
</div>
|
|
<p>Playbooks are a completely different way to use ansible and are
|
|
particularly awesome.</p>
|
|
<p>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, or they can automate steps of
|
|
a manual ordered process. 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.</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="hosts-line">
|
|
<h2>Hosts line<a class="headerlink" href="#hosts-line" title="Permalink to this headline">¶</a></h2>
|
|
<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’s own choice of patterns.</p>
|
|
</div>
|
|
<div class="section" id="user-line">
|
|
<h2>User line<a class="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>
|
|
<div class="highlight-python"><pre>user: mdehaan</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="vars-section">
|
|
<h2>Vars section<a class="headerlink" href="#vars-section" title="Permalink to this headline">¶</a></h2>
|
|
<p>The <cite>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</cite> syntax 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 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
|
|
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">
|
|
<h2>Tasks list<a class="headerlink" href="#tasks-list" title="Permalink to this headline">¶</a></h2>
|
|
<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>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. Command will actually rerun the
|
|
same command again, which is totally ok if the command is something
|
|
like ‘chmod’ or ‘setsebool’, etc.</p>
|
|
</div>
|
|
<div class="section" id="task-name-and-action">
|
|
<h2>Task name and action<a class="headerlink" href="#task-name-and-action" title="Permalink to this headline">¶</a></h2>
|
|
<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>
|
|
</div>
|
|
<p>The command module is the one module that just takes a list
|
|
of arguments, and doesn’t use the key=value form. Simple:</p>
|
|
<div class="highlight-python"><pre>- 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>- 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 class="section" id="notify-statements">
|
|
<h2>Notify statements<a class="headerlink" href="#notify-statements" title="Permalink to this headline">¶</a></h2>
|
|
<p>As we’ve mentioned, nearly all modules are written to be ‘idempotent’ and can signal 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>Next up, we’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>
|
|
</div>
|
|
<div class="section" id="handlers">
|
|
<h2>Handlers<a class="headerlink" href="#handlers" title="Permalink to this headline">¶</a></h2>
|
|
<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>
|
|
<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="external-variables-and-sensitive-data">
|
|
<h3>External Variables And Sensitive Data<a class="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>
|
|
<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>
|
|
</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>
|
|
</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="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 it’s 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 note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">Don’t forget to check out the <a class="reference external" href="https://github.com/ansible/ansible/tree/master/examples/playbooks">Github examples directory</a> for examples of playbooks in action, so you can see how all of these features can be put together.</p>
|
|
</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 Mar 13, 2012.<br/>
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
|
|
</p>
|
|
</div>
|
|
</footer>
|
|
</body>
|
|
</html> |