Updating various doc items with 0.6 features, releasing soon, and removing references to things new in 0.4, which
has been out long enough to no longer be new.
This commit is contained in:
parent
dac0db9ca2
commit
1aa3c1522c
21 changed files with 360 additions and 152 deletions
|
@ -289,7 +289,7 @@ languages:
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
2
api.html
2
api.html
|
@ -465,7 +465,7 @@ e.g.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
|
@ -311,7 +311,7 @@ This way you have an audit trail describing when and why you changed the rules a
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
|
@ -396,7 +396,7 @@ a simplified syntax for this.</p>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
2
faq.html
2
faq.html
|
@ -403,7 +403,7 @@ tasks – whether for a QA sytem, build system, or anything you can think of
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
|
@ -204,7 +204,7 @@ s.parentNode.insertBefore(ga, s);
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
|
@ -391,7 +391,7 @@ explore, but you already have a fully working infrastructure!</p>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
|
@ -410,7 +410,7 @@ Puppet Labs, and is now with <a class="reference external" href="http://rpath.co
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
|
@ -340,8 +340,7 @@ a lot shorter than this:</p>
|
||||||
<h2>Module Provided ‘Facts’<a class="headerlink" href="#module-provided-facts" title="Permalink to this headline">¶</a></h2>
|
<h2>Module Provided ‘Facts’<a class="headerlink" href="#module-provided-facts" title="Permalink to this headline">¶</a></h2>
|
||||||
<p>The ‘setup’ module that ships with Ansible provides many variables about a system that can be used in playbooks
|
<p>The ‘setup’ module that ships with Ansible provides many variables about a system that can be used in playbooks
|
||||||
and templates. However, it’s possible to also add your own facts without modifying the system module. To do
|
and templates. However, it’s possible to also add your own facts without modifying the system module. To do
|
||||||
this, just have the module return a <cite>ansible_facts</cite> key, like so, along with other return data. This requires
|
this, just have the module return a <cite>ansible_facts</cite> key, like so, along with other return data:</p>
|
||||||
Ansible 0.4 and later:</p>
|
|
||||||
<div class="highlight-python"><pre>{
|
<div class="highlight-python"><pre>{
|
||||||
"changed" : True,
|
"changed" : True,
|
||||||
"rc" : 5,
|
"rc" : 5,
|
||||||
|
@ -469,7 +468,7 @@ Stop by the mailing list to inquire about requirements.</p>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
|
@ -818,8 +818,7 @@ host before using this module.</p>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="raw">
|
<div class="section" id="raw">
|
||||||
<span id="id13"></span><h2>raw<a class="headerlink" href="#raw" title="Permalink to this headline">¶</a></h2>
|
<span id="id13"></span><h2>raw<a class="headerlink" href="#raw" title="Permalink to this headline">¶</a></h2>
|
||||||
<p>Executes a low-down and dirty SSH command, not going through the module subsystem.
|
<p>Executes a low-down and dirty SSH command, not going through the module subsystem.</p>
|
||||||
This module is new in Ansible 0.4.</p>
|
|
||||||
<p>This is useful and should only be done in two cases. The first case is installing
|
<p>This is useful and should only be done in two cases. The first case is installing
|
||||||
python-simplejson on older (python 2.4 and before) hosts that need it as a dependency
|
python-simplejson on older (python 2.4 and before) hosts that need it as a dependency
|
||||||
to run modules, since nearly all core modules require it. Another is speaking to any
|
to run modules, since nearly all core modules require it. Another is speaking to any
|
||||||
|
@ -1275,7 +1274,7 @@ yum name=httpd state=installed</pre>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
|
@ -271,7 +271,7 @@ proxy=proxy.atlanta.example.com</pre>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="groups-of-groups-and-group-variables">
|
<div class="section" id="groups-of-groups-and-group-variables">
|
||||||
<h2>Groups of Groups, and Group Variables<a class="headerlink" href="#groups-of-groups-and-group-variables" title="Permalink to this headline">¶</a></h2>
|
<h2>Groups of Groups, and Group Variables<a class="headerlink" href="#groups-of-groups-and-group-variables" title="Permalink to this headline">¶</a></h2>
|
||||||
<p>Using Ansible 0.4, it is possible to make groups of groups and assign
|
<p>It is also possible to make groups of groups and assign
|
||||||
variables to groups. These variables can be used by /usr/bin/ansible-playbook, but not
|
variables to groups. These variables can be used by /usr/bin/ansible-playbook, but not
|
||||||
/usr/bin/ansible:</p>
|
/usr/bin/ansible:</p>
|
||||||
<div class="highlight-python"><pre>[atlanta]
|
<div class="highlight-python"><pre>[atlanta]
|
||||||
|
@ -380,7 +380,7 @@ a <a class="reference external" href="https://github.com/ansible/ansible/blob/de
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
101
playbooks.html
101
playbooks.html
|
@ -149,7 +149,7 @@ s.parentNode.insertBefore(ga, s);
|
||||||
class="dropdown-toggle">Page</a>
|
class="dropdown-toggle">Page</a>
|
||||||
<span class="localtoc"><ul>
|
<span class="localtoc"><ul>
|
||||||
<li><a class="reference internal" href="#">Playbooks</a><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="#playbook-language-example">Playbook Language Example</a></li>
|
||||||
<li><a class="reference internal" href="#basics">Basics</a><ul>
|
<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="#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="#vars-section">Vars section</a></li>
|
||||||
|
@ -157,7 +157,7 @@ s.parentNode.insertBefore(ga, s);
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li><a class="reference internal" href="#running-operations-on-change">Running Operations On Change</a></li>
|
<li><a class="reference internal" href="#running-operations-on-change">Running Operations On Change</a></li>
|
||||||
<li><a class="reference internal" href="#include-files-and-reuse">Include Files And Reuse</a></li>
|
<li><a class="reference internal" href="#include-files-and-encouraging-reuse">Include Files And Encouraging Reuse</a></li>
|
||||||
<li><a class="reference internal" href="#executing-a-playbook">Executing A Playbook</a></li>
|
<li><a class="reference internal" href="#executing-a-playbook">Executing A Playbook</a></li>
|
||||||
<li><a class="reference internal" href="#tips-and-tricks">Tips and Tricks</a></li>
|
<li><a class="reference internal" href="#tips-and-tricks">Tips and Tricks</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
|
@ -189,11 +189,10 @@ s.parentNode.insertBefore(ga, s);
|
||||||
|
|
||||||
<div class="section" id="playbooks">
|
<div class="section" id="playbooks">
|
||||||
<h1>Playbooks<a class="headerlink" href="#playbooks" title="Permalink to this headline">¶</a></h1>
|
<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
|
<p>Playbooks are a completely different way to use ansible than in task execution mode, and are
|
||||||
particularly awesome. They are the basis for a really simple
|
particularly awesome. Simply put, playbooks are the basis for a really simple
|
||||||
configuration management and multi-machine deployment system,
|
configuration management and multi-machine deployment system,
|
||||||
unlike any that already exist, and
|
unlike any that already exist, and one that is very well suited to deploying complex applications.</p>
|
||||||
one that is very well suited to deploying complex applications.</p>
|
|
||||||
<p>Playbooks can declare configurations, but they can also orchestrate steps of
|
<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
|
any manual ordered process, even as different steps must bounce back and forth
|
||||||
between sets of machines in particular orders. They can launch tasks
|
between sets of machines in particular orders. They can launch tasks
|
||||||
|
@ -205,10 +204,13 @@ remote systems are in spec.</p>
|
||||||
<p>Let’s dive in and see how they work. As you go, you may wish to open
|
<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
|
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>
|
another tab, so you can apply the theory to what things look like in practice.</p>
|
||||||
<div class="section" id="playbook-example">
|
<div class="section" id="playbook-language-example">
|
||||||
<h2>Playbook Example<a class="headerlink" href="#playbook-example" title="Permalink to this headline">¶</a></h2>
|
<h2>Playbook Language Example<a class="headerlink" href="#playbook-language-example" title="Permalink to this headline">¶</a></h2>
|
||||||
<p>Playbooks are expressed in YAML format and have a minimum of syntax.
|
<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>
|
Each playbook is composed of one or more ‘plays’ in a list.</p>
|
||||||
|
<p>The goal of a play is map a group of hosts to some well defined roles, represented by
|
||||||
|
things ansible called tasks. At the basic level, a task is nothing more than a call
|
||||||
|
to an ansible module, which you should have learned about in earlier chapters.</p>
|
||||||
<p>By composing a playbook of multiple ‘plays’, it is possible to
|
<p>By composing a playbook of multiple ‘plays’, it is possible to
|
||||||
orchestrate multi-machine deployments, running certain steps on all
|
orchestrate multi-machine deployments, running certain steps on all
|
||||||
machines in the webservers group, then certain steps on the database
|
machines in the webservers group, then certain steps on the database
|
||||||
|
@ -285,21 +287,18 @@ this does not come into play. Ansible also takes care to not log password parame
|
||||||
<p>These variables can be used later in the playbook like this:</p>
|
<p>These variables can be used later in the playbook like this:</p>
|
||||||
<div class="highlight-python"><pre>$varname or ${varname}</pre>
|
<div class="highlight-python"><pre>$varname or ${varname}</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>The later is useful in the event you need to do something like ${other}_concatenated_value.</p>
|
<p>The later is useful in the event you need to do something like ${other}_some_string.</p>
|
||||||
<p>The full power of the Jinja2 templating language is also available (note: in 0.4, this is only true inside of templates), which looks like this:</p>
|
<p>The full power of the <a class="reference external" href="http://jinja.pocoo.org/docs/">Jinja2</a> templating language is also available, which looks like this:</p>
|
||||||
<div class="highlight-python"><pre>{{ varname }}</pre>
|
<div class="highlight-python"><pre>{{ varname }}</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>The Jinja2 documentation provides information about how to construct loops and conditionals for those
|
<p>The Jinja2 documentation provides information about how to construct loops and conditionals for those
|
||||||
who which to use more advanced templating. This is optional and the $varname format still works in template
|
who which to use more advanced templating. This is optional and the $varname format still works in template
|
||||||
files.</p>
|
files.</p>
|
||||||
<p>If there are discovered variables about the system (ansible provides some of these,
|
<p>If there are discovered variables about the system, called ‘facts’, these variables bubble up back into the
|
||||||
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. Ansible provides several
|
||||||
playbook, and can be used on each system just like explicitly set
|
of these, prefixed with ‘ansible’, and are documented under <a class="reference internal" href="modules.html#setup"><em>setup</em></a> in the module documentation. Additionally,
|
||||||
variables.</p>
|
facts can be gathered by ohai and facter if they are installed. Facter variables are prefixed with <tt class="docutils literal"><span class="pre">facter_</span></tt> and Ohai
|
||||||
<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>.</p>
|
||||||
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> (See the <a class="reference internal" href="modules.html#setup"><em>setup</em></a> module
|
|
||||||
documentation for a list of Ansible variables).</p>
|
|
||||||
<p>So for instance, if I wanted
|
<p>So for instance, if I wanted
|
||||||
to write the hostname into the /etc/motd file, I could say:</p>
|
to write the hostname into the /etc/motd file, I could say:</p>
|
||||||
<div class="highlight-python"><pre>- name: write the motd
|
<div class="highlight-python"><pre>- name: write the motd
|
||||||
|
@ -314,19 +313,22 @@ to write the hostname into the /etc/motd file, I could say:</p>
|
||||||
<h3>Tasks list<a class="headerlink" href="#tasks-list" title="Permalink to this headline">¶</a></h3>
|
<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
|
<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,
|
at a time, against all machines matched by the host pattern,
|
||||||
before moving on to the next task.</p>
|
before moving on to the next task. It is important to understand that, within a play,
|
||||||
<p>Hosts with failed tasks are taken out of the rotation for the entire
|
all hosts are going to get the same task directives. It is the purpose of a play to map
|
||||||
playbook. If things fail, simply correct the playbook file and rerun.</p>
|
a selection of hosts to tasks.</p>
|
||||||
|
<p>When running the playbook, which runs top to bottom, 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.
|
<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>
|
Variables, as mentioned above, can be used in arguments to modules.</p>
|
||||||
<p>Modules other than <cite>command</cite> and <cite>shell</cite> are ‘idempotent’, meaning if you run them
|
<p>Modules are ‘idempotent’, meaning if you run them
|
||||||
again, they will make the changes they are told to make to bring the
|
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
|
system to the desired state. This makes it very safe to rerun
|
||||||
the same playbook multiple times. They won’t change things
|
the same playbook multiple times. They won’t change things
|
||||||
unless they have to change things.</p>
|
unless they have to change things.</p>
|
||||||
<p>The <cite>command</cite> and <cite>shell</cite> modules will actually rerun the same command again,
|
<p>The <cite>command</cite> and <cite>shell</cite> modules will typically rerun the same command again,
|
||||||
which is totally ok if the command is something like
|
which is totally ok if the command is something like
|
||||||
‘chmod’ or ‘setsebool’, etc.</p>
|
‘chmod’ or ‘setsebool’, etc. Though there is a ‘creates’ flag available which can
|
||||||
|
be used to make these modules also idempotent.</p>
|
||||||
<p>Every task should have a <cite>name</cite>, which is included in the output from
|
<p>Every task should have a <cite>name</cite>, which is included in the output from
|
||||||
running the playbook. This is output for humans, so it is
|
running the playbook. This is output for humans, so it is
|
||||||
nice to have reasonably good descriptions of each task step. If the name
|
nice to have reasonably good descriptions of each task step. If the name
|
||||||
|
@ -345,6 +347,18 @@ them work just like you would expect. Simple:</p>
|
||||||
- name: disable selinux
|
- name: disable selinux
|
||||||
action: command /sbin/setenforce 0</pre>
|
action: command /sbin/setenforce 0</pre>
|
||||||
</div>
|
</div>
|
||||||
|
<p>The command and shell module care about return codes, so if you have a command
|
||||||
|
who’s successful exit code is not zero, you may wish to do this:</p>
|
||||||
|
<blockquote>
|
||||||
|
<div><dl class="docutils">
|
||||||
|
<dt>tasks:</dt>
|
||||||
|
<dd><ul class="first last simple">
|
||||||
|
<li>name: run this command and ignore the result
|
||||||
|
action: shell /usr/bin/somecommand & /bin/true</li>
|
||||||
|
</ul>
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
</div></blockquote>
|
||||||
<p>Variables can be used in action lines. Suppose you defined
|
<p>Variables can be used in action lines. Suppose you defined
|
||||||
a variable called ‘vhost’ in the ‘vars’ section, you could do this:</p>
|
a variable called ‘vhost’ in the ‘vars’ section, you could do this:</p>
|
||||||
<div class="highlight-python"><pre>tasks:
|
<div class="highlight-python"><pre>tasks:
|
||||||
|
@ -352,11 +366,13 @@ a variable called ‘vhost’ in the ‘vars’ section, you cou
|
||||||
action: template src=somefile.j2 dest=/etc/httpd/conf.d/$vhost</pre>
|
action: template src=somefile.j2 dest=/etc/httpd/conf.d/$vhost</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>Those same variables are usable in templates, which we’ll get to later.</p>
|
<p>Those same variables are usable in templates, which we’ll get to later.</p>
|
||||||
|
<p>Now in a very basic playbook all the tasks will be listed directly in that play, though it will usually
|
||||||
|
make more sense to break up tasks using the ‘include:’ directive. We’ll show that a bit later.</p>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="running-operations-on-change">
|
<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>
|
<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
|
<p>As we’ve mentioned, modules are written to be ‘idempotent’ and can relay when
|
||||||
they have made a change on the remote system. Playbooks recognize this and
|
they have made a change on the remote system. Playbooks recognize this and
|
||||||
have a basic event system that can be used to respond to change.</p>
|
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
|
<p>These ‘notify’ actions are triggered at the end of each ‘play’ in a playbook, and
|
||||||
|
@ -391,11 +407,13 @@ won’t need them for much else.</p>
|
||||||
<p class="last">Notify handlers are always run in the order written.</p>
|
<p class="last">Notify handlers are always run in the order written.</p>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="include-files-and-reuse">
|
<div class="section" id="include-files-and-encouraging-reuse">
|
||||||
<h2>Include Files And Reuse<a class="headerlink" href="#include-files-and-reuse" title="Permalink to this headline">¶</a></h2>
|
<h2>Include Files And Encouraging Reuse<a class="headerlink" href="#include-files-and-encouraging-reuse" title="Permalink to this headline">¶</a></h2>
|
||||||
<p>Suppose you want to reuse lists of tasks between plays or playbooks. You can use
|
<p>Suppose you want to reuse lists of tasks between plays or playbooks. You can use
|
||||||
include files to do this.</p>
|
include files to do this. Use of included task lists is a great way to define a role
|
||||||
<p>An include file simply contains a flat list of tasks, like so:</p>
|
that system is going to fulfill. Remember, the goal of a play in a playbook is to map
|
||||||
|
a group of systems into multiple roles. Let’s see what this looks like...</p>
|
||||||
|
<p>A task include file simply contains a flat list of tasks, like so:</p>
|
||||||
<div class="highlight-python"><pre>---
|
<div class="highlight-python"><pre>---
|
||||||
# possibly saved as tasks/foo.yml
|
# possibly saved as tasks/foo.yml
|
||||||
- name: placeholder foo
|
- name: placeholder foo
|
||||||
|
@ -403,11 +421,11 @@ include files to do this.</p>
|
||||||
- name: placeholder bar
|
- name: placeholder bar
|
||||||
action: command /bin/bar</pre>
|
action: command /bin/bar</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>Include directives look like this:</p>
|
<p>Include directives look like this, and can be mixed in with regular tasks in a playbook:</p>
|
||||||
<div class="highlight-python"><pre>- tasks:
|
<div class="highlight-python"><pre>- tasks:
|
||||||
- include: tasks/foo.yml</pre>
|
- include: tasks/foo.yml</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>You can also pass variables into includes directly. We might call this a ‘parameterized include’.</p>
|
<p>You can also pass variables into includes. We call this a ‘parameterized include’.</p>
|
||||||
<p>For instance, if deploying multiple wordpress instances, I could
|
<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>
|
contain all of my wordpress tasks in a single wordpress.yml file, and use it like so:</p>
|
||||||
<div class="highlight-python"><pre>- tasks:
|
<div class="highlight-python"><pre>- tasks:
|
||||||
|
@ -415,16 +433,16 @@ contain all of my wordpress tasks in a single wordpress.yml file, and use it lik
|
||||||
- include: wordpress.yml user=alice
|
- include: wordpress.yml user=alice
|
||||||
- include: wordpress.yml user=bob</pre>
|
- include: wordpress.yml user=bob</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>Variables passed in can be used in the included files. You can reference them like this:</p>
|
<p>Variables passed in can then be used in the included files. You can reference them like this:</p>
|
||||||
<div class="highlight-python"><pre>$user</pre>
|
<div class="highlight-python"><pre>$user</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>In addition to the explicitly passed in parameters, all variables from
|
<p>(In addition to the explicitly passed in parameters, all variables from
|
||||||
the vars section are also available for use here as well.</p>
|
the vars section are also available for use here as well.)</p>
|
||||||
<div class="admonition note">
|
<div class="admonition note">
|
||||||
<p class="first admonition-title">Note</p>
|
<p class="first admonition-title">Note</p>
|
||||||
<p class="last">Include statements are only usable from the top level
|
<p class="last">Task include statements are only usable one-level deep.
|
||||||
playbook file. This means includes can not include other
|
This means task includes can not include other
|
||||||
includes. This may be implemented in a later release.</p>
|
task includes. This may change in a later release.</p>
|
||||||
</div>
|
</div>
|
||||||
<p>Includes can also be used in the ‘handlers’ section, for instance, if you
|
<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
|
want to define how to restart apache, you only have to do that once for all
|
||||||
|
@ -440,9 +458,12 @@ of a play:</p>
|
||||||
- include: handlers/handlers.yml</pre>
|
- include: handlers/handlers.yml</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>You can mix in includes along with your regular non-included tasks and handlers.</p>
|
<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
|
<p>NOTE:: 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
|
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>
|
restructure your playbook to be more class/role oriented. This is to say you cannot
|
||||||
|
use a ‘fact’ to decide what include file to use. All hosts contained within the play
|
||||||
|
are going to get the same tasks. (‘only_if’ provides some ability for hosts to conditionally
|
||||||
|
skip tasks).</p>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="executing-a-playbook">
|
<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>
|
<h2>Executing A Playbook<a class="headerlink" href="#executing-a-playbook" title="Permalink to this headline">¶</a></h2>
|
||||||
|
@ -514,7 +535,7 @@ package is installed. Try it!</p>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
144
playbooks2.html
144
playbooks2.html
|
@ -149,9 +149,10 @@ s.parentNode.insertBefore(ga, s);
|
||||||
class="dropdown-toggle">Page</a>
|
class="dropdown-toggle">Page</a>
|
||||||
<span class="localtoc"><ul>
|
<span class="localtoc"><ul>
|
||||||
<li><a class="reference internal" href="#">Advanced Playbooks</a><ul>
|
<li><a class="reference internal" href="#">Advanced Playbooks</a><ul>
|
||||||
|
<li><a class="reference internal" href="#tags">Tags</a></li>
|
||||||
|
<li><a class="reference internal" href="#playbooks-including-playbooks">Playbooks Including Playbooks</a><ul>
|
||||||
<li><a class="reference internal" href="#accessing-complex-variable-data">Accessing Complex Variable Data</a></li>
|
<li><a class="reference internal" href="#accessing-complex-variable-data">Accessing Complex Variable Data</a></li>
|
||||||
<li><a class="reference internal" href="#accessing-information-about-other-hosts">Accessing Information About Other Hosts</a></li>
|
<li><a class="reference internal" href="#accessing-information-about-other-hosts">Accessing Information About Other Hosts</a></li>
|
||||||
<li><a class="reference internal" href="#magic-variables">Magic Variables</a></li>
|
|
||||||
<li><a class="reference internal" href="#variable-file-seperation">Variable File Seperation</a></li>
|
<li><a class="reference internal" href="#variable-file-seperation">Variable File Seperation</a></li>
|
||||||
<li><a class="reference internal" href="#prompting-for-sensitive-data">Prompting For Sensitive Data</a></li>
|
<li><a class="reference internal" href="#prompting-for-sensitive-data">Prompting For Sensitive Data</a></li>
|
||||||
<li><a class="reference internal" href="#passing-variables-on-the-command-line">Passing Variables On The Command Line</a></li>
|
<li><a class="reference internal" href="#passing-variables-on-the-command-line">Passing Variables On The Command Line</a></li>
|
||||||
|
@ -161,7 +162,11 @@ s.parentNode.insertBefore(ga, s);
|
||||||
<li><a class="reference internal" href="#selecting-files-and-templates-based-on-variables">Selecting Files And Templates Based On Variables</a></li>
|
<li><a class="reference internal" href="#selecting-files-and-templates-based-on-variables">Selecting Files And Templates Based On Variables</a></li>
|
||||||
<li><a class="reference internal" href="#asynchronous-actions-and-polling">Asynchronous Actions and Polling</a></li>
|
<li><a class="reference internal" href="#asynchronous-actions-and-polling">Asynchronous Actions and Polling</a></li>
|
||||||
<li><a class="reference internal" href="#local-playbooks">Local Playbooks</a></li>
|
<li><a class="reference internal" href="#local-playbooks">Local Playbooks</a></li>
|
||||||
|
<li><a class="reference internal" href="#turning-off-facts">Turning Off Facts</a></li>
|
||||||
<li><a class="reference internal" href="#pull-mode-playbooks">Pull-Mode Playbooks</a></li>
|
<li><a class="reference internal" href="#pull-mode-playbooks">Pull-Mode Playbooks</a></li>
|
||||||
|
<li><a class="reference internal" href="#style-points">Style Points</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
@ -195,11 +200,44 @@ s.parentNode.insertBefore(ga, s);
|
||||||
are not neccessary, but many of them will prove useful. If a feature doesn’t seem immediately
|
are not neccessary, but many of them will prove useful. If a feature doesn’t seem immediately
|
||||||
relevant, feel free to skip it. For many people, the features documented in <cite>playbooks</cite> will
|
relevant, feel free to skip it. For many people, the features documented in <cite>playbooks</cite> will
|
||||||
be 90% or more of what they use in Ansible.</p>
|
be 90% or more of what they use in Ansible.</p>
|
||||||
|
<div class="section" id="tags">
|
||||||
|
<h2>Tags<a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h2>
|
||||||
|
<p>(New in 0.6) If you have a large playbook it may become useful to be able to run a specific
|
||||||
|
part of the configuration. Both plays and tasks support a “tags:” attribute for this reason.</p>
|
||||||
|
<p>Example:</p>
|
||||||
|
<div class="highlight-python"><pre>tasks:
|
||||||
|
|
||||||
|
- action: yum name=$item state=installed
|
||||||
|
with_items:
|
||||||
|
- httpd
|
||||||
|
- memcached
|
||||||
|
tags:
|
||||||
|
- packages
|
||||||
|
|
||||||
|
- action: template src=templates/src.j2 dest=/etc/foo.conf
|
||||||
|
tags:
|
||||||
|
- configuration</pre>
|
||||||
|
</div>
|
||||||
|
<p>If you wanted to just run the “configuration” and “packages” part of a very long playbook, you could do this:</p>
|
||||||
|
<div class="highlight-python"><pre>ansible-playbook example.yml --tags "configuration,packages"</pre>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="playbooks-including-playbooks">
|
||||||
|
<h2>Playbooks Including Playbooks<a class="headerlink" href="#playbooks-including-playbooks" title="Permalink to this headline">¶</a></h2>
|
||||||
|
<p>(New in 0.6) To further advance the concept of include files, playbook files can include other playbook
|
||||||
|
files. Suppose you define the behavior of all your webservers in “webservers.yml” and
|
||||||
|
all your database servers in “dbservers.yml”. You can create a “site.yml” that would
|
||||||
|
reconfigure all of your systems like this:</p>
|
||||||
|
<div class="highlight-python"><pre>----
|
||||||
|
- include: playbooks/webservers.yml
|
||||||
|
- include: playbooks/dbservers.yml</pre>
|
||||||
|
</div>
|
||||||
|
<p>This concept works great with tags to rapidly select exactly what plays you want to run, and exactly
|
||||||
|
what parts of those plays.</p>
|
||||||
<div class="section" id="accessing-complex-variable-data">
|
<div class="section" id="accessing-complex-variable-data">
|
||||||
<h2>Accessing Complex Variable Data<a class="headerlink" href="#accessing-complex-variable-data" title="Permalink to this headline">¶</a></h2>
|
<h3>Accessing Complex Variable Data<a class="headerlink" href="#accessing-complex-variable-data" title="Permalink to this headline">¶</a></h3>
|
||||||
<p>Some provided facts, like networking information, are made available as nested data structures. To access
|
<p>Some provided facts, like networking information, are made available as nested data structures. To access
|
||||||
them a simple ‘$foo’ is not sufficient, but it is still easy to do. Here’s how we get an IP address using
|
them a simple ‘$foo’ is not sufficient, but it is still easy to do. Here’s how we get an IP address:</p>
|
||||||
Ansible 0.4 and later:</p>
|
|
||||||
<div class="highlight-python"><pre>${ansible_eth0.ipv4.address}</pre>
|
<div class="highlight-python"><pre>${ansible_eth0.ipv4.address}</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>It is also possible to access variables whose elements are arrays:</p>
|
<p>It is also possible to access variables whose elements are arrays:</p>
|
||||||
|
@ -212,19 +250,14 @@ that is preferred:</p>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="accessing-information-about-other-hosts">
|
<div class="section" id="accessing-information-about-other-hosts">
|
||||||
<h2>Accessing Information About Other Hosts<a class="headerlink" href="#accessing-information-about-other-hosts" title="Permalink to this headline">¶</a></h2>
|
<h3>Accessing Information About Other Hosts<a class="headerlink" href="#accessing-information-about-other-hosts" title="Permalink to this headline">¶</a></h3>
|
||||||
<p>If your database server wants to check the value of a ‘fact’ from another node, or an inventory variable
|
<p>If your database server wants to check the value of a ‘fact’ from another node, or an inventory variable
|
||||||
assigned to another node, it’s easy to do so within a template or even an action line (note: this uses syntax available in 0.4 and later):</p>
|
assigned to another node, it’s easy to do so within a template or even an action line:</p>
|
||||||
<div class="highlight-python"><pre>${hostvars.hostname.factname}</pre>
|
<div class="highlight-python"><pre>${hostvars.hostname.factname}</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>NOTE: No database or other complex system is required to exchange data between hosts. The hosts that you
|
<p>NOTE: No database or other complex system is required to exchange data between hosts. The hosts that you
|
||||||
want to reference data from must be included in either the current play or any previous play.</p>
|
want to reference data from must be included in either the current play or any previous play.</p>
|
||||||
</div>
|
<p>Additionally, <em>group_names</em> is a list (array) of all the groups the current host is in. This can be used in templates using Jinja2 syntax to make template source files that vary based on the group membership (or role) of the host:</p>
|
||||||
<div class="section" id="magic-variables">
|
|
||||||
<h2>Magic Variables<a class="headerlink" href="#magic-variables" title="Permalink to this headline">¶</a></h2>
|
|
||||||
<p>Some variables made available to hosts don’t come from definitions in a playbook, the inventory file, or discovery from the system. There are only two of these, and are used in special cases that many users won’t need.</p>
|
|
||||||
<p><em>group_names</em> is a list (array) of all the groups the current host is in. This can be used in templates using Jinja2
|
|
||||||
syntax to make template source files that vary based on the group membership (or role) of the host:</p>
|
|
||||||
<div class="highlight-python"><pre>{% if 'webserver' in group_names %}
|
<div class="highlight-python"><pre>{% if 'webserver' in group_names %}
|
||||||
# some part of a configuration file that only applies to webservers
|
# some part of a configuration file that only applies to webservers
|
||||||
{% endif %}</pre>
|
{% endif %}</pre>
|
||||||
|
@ -238,10 +271,12 @@ For example:</p>
|
||||||
<p>Use cases include pointing a frontend proxy server to all of the app servers, setting up the correct firewall rules between servers, etc.</p>
|
<p>Use cases include pointing a frontend proxy server to all of the app servers, setting up the correct firewall rules between servers, etc.</p>
|
||||||
<p><em>inventory_hostname</em> is the name of the hostname as configured in Ansible’s inventory host file. This can
|
<p><em>inventory_hostname</em> is the name of the hostname as configured in Ansible’s inventory host file. This can
|
||||||
be useful for when you don’t want to rely on the discovered hostname <cite>ansible_hostname</cite> or for other mysterious
|
be useful for when you don’t want to rely on the discovered hostname <cite>ansible_hostname</cite> or for other mysterious
|
||||||
reasons. Don’t worry about it unless you think you need it.</p>
|
reasons. If you have a long FQDN, <em>inventory_hostname_short</em> (in Ansible 0.6) also contains the part up to the first
|
||||||
|
period.</p>
|
||||||
|
<p>Don’t worry about any of this unless you think you need it. You’ll know when you do.</p>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="variable-file-seperation">
|
<div class="section" id="variable-file-seperation">
|
||||||
<h2>Variable File Seperation<a class="headerlink" href="#variable-file-seperation" title="Permalink to this headline">¶</a></h2>
|
<h3>Variable File Seperation<a class="headerlink" href="#variable-file-seperation" title="Permalink to this headline">¶</a></h3>
|
||||||
<p>It’s a great idea to keep your playbooks under source control, but
|
<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
|
you may wish to make the playbook source public while keeping certain
|
||||||
important variables private. Similarly, sometimes you may just
|
important variables private. Similarly, sometimes you may just
|
||||||
|
@ -267,9 +302,10 @@ sharing your playbook source with them.</p>
|
||||||
somevar: somevalue
|
somevar: somevalue
|
||||||
password: magic</pre>
|
password: magic</pre>
|
||||||
</div>
|
</div>
|
||||||
|
<p>NOTE: It’s also possible to keep per-host and per-group variables in very similar files, this is covered in <a class="reference internal" href="patterns.html#patterns"><em>Inventory & Patterns</em></a>.</p>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="prompting-for-sensitive-data">
|
<div class="section" id="prompting-for-sensitive-data">
|
||||||
<h2>Prompting For Sensitive Data<a class="headerlink" href="#prompting-for-sensitive-data" title="Permalink to this headline">¶</a></h2>
|
<h3>Prompting For Sensitive Data<a class="headerlink" href="#prompting-for-sensitive-data" title="Permalink to this headline">¶</a></h3>
|
||||||
<p>You may wish to prompt the user for certain input, and can
|
<p>You may wish to prompt the user for certain input, and can
|
||||||
do so with the similarly named ‘vars_prompt’ section. This has uses
|
do so with the similarly named ‘vars_prompt’ section. This has uses
|
||||||
beyond security, for instance, you may use the same playbook for all
|
beyond security, for instance, you may use the same playbook for all
|
||||||
|
@ -286,17 +322,37 @@ in a push-script:</p>
|
||||||
favcolor: "what is your favorite color?"</pre>
|
favcolor: "what is your favorite color?"</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>There are full examples of both of these items in the github examples/playbooks directory.</p>
|
<p>There are full examples of both of these items in the github examples/playbooks directory.</p>
|
||||||
|
<p>An alternative form of vars_prompt allows for hiding input from the user, and may later support
|
||||||
|
some other options, but otherwise works equivalently:</p>
|
||||||
|
<div class="highlight-python"><pre>vars_prompt:
|
||||||
|
- name: "some_password"
|
||||||
|
prompt: "Enter password"
|
||||||
|
private: True
|
||||||
|
- name: "release_version"
|
||||||
|
prompt: "Product release version"
|
||||||
|
private: False</pre>
|
||||||
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="passing-variables-on-the-command-line">
|
<div class="section" id="passing-variables-on-the-command-line">
|
||||||
<h2>Passing Variables On The Command Line<a class="headerlink" href="#passing-variables-on-the-command-line" title="Permalink to this headline">¶</a></h2>
|
<h3>Passing Variables On The Command Line<a class="headerlink" href="#passing-variables-on-the-command-line" title="Permalink to this headline">¶</a></h3>
|
||||||
<p>In addition to <cite>vars_prompt</cite> and <cite>vars_files</cite>, it is possible to send variables over
|
<p>In addition to <cite>vars_prompt</cite> and <cite>vars_files</cite>, it is possible to send variables over
|
||||||
the ansible command line. This is particularly useful when writing a generic release playbook
|
the ansible command line. This is particularly useful when writing a generic release playbook
|
||||||
where you may want to pass in the version of the application to deploy:</p>
|
where you may want to pass in the version of the application to deploy:</p>
|
||||||
<div class="highlight-python"><pre>ansible-playbook release.yml --extra-vars "version=1.23.45 other_variable=foo"</pre>
|
<div class="highlight-python"><pre>ansible-playbook release.yml --extra-vars "version=1.23.45 other_variable=foo"</pre>
|
||||||
</div>
|
</div>
|
||||||
|
<p>This is useful, for, among other things, setting the hosts group or the user for the playbook.</p>
|
||||||
|
<p>Example:</p>
|
||||||
|
<div class="highlight-python"><pre>-----
|
||||||
|
- user: $user
|
||||||
|
hosts: $hosts
|
||||||
|
tasks:
|
||||||
|
- ...
|
||||||
|
|
||||||
|
ansible-playbook release.yml --extra-vars "hosts=vipers user=starbuck"</pre>
|
||||||
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="conditional-execution">
|
<div class="section" id="conditional-execution">
|
||||||
<h2>Conditional Execution<a class="headerlink" href="#conditional-execution" title="Permalink to this headline">¶</a></h2>
|
<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
|
<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,
|
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>
|
or it could be something like performing some cleanup steps if a filesystem is getting full.</p>
|
||||||
|
@ -306,22 +362,32 @@ Don’t panic – it’s actually pretty simple:</p>
|
||||||
favcolor: blue
|
favcolor: blue
|
||||||
is_favcolor_blue: "'$favcolor' == 'blue'"
|
is_favcolor_blue: "'$favcolor' == 'blue'"
|
||||||
is_centos: "'$facter_operatingsystem' == 'CentOS'"
|
is_centos: "'$facter_operatingsystem' == 'CentOS'"
|
||||||
|
|
||||||
tasks:
|
tasks:
|
||||||
- name: "shutdown if my favorite color is blue"
|
- name: "shutdown if my favorite color is blue"
|
||||||
action: command /sbin/shutdown -t now
|
action: command /sbin/shutdown -t now
|
||||||
only_if: '$is_favcolor_blue'</pre>
|
only_if: '$is_favcolor_blue'</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>Variables from tools like <cite>facter</cite> and <cite>ohai</cite> can be used here, if installed, or you can
|
<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,
|
use variables that bubble up from ansible, which many are provided by the <a class="reference internal" href="modules.html#setup"><em>setup</em></a> module. As a reminder,
|
||||||
these variables are prefixed, so it’s <cite>$facter_operatingsystem</cite>, not <cite>$operatingsystem</cite>. Ansible’s
|
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
|
built in variables are prefixed with <cite>ansible_</cite>.</p>
|
||||||
expression is actually a tiny small bit of Python, so be sure to quote variables and make something
|
<p>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
|
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
|
all of your conditional expressions in a way that makes them very easy to reuse between plays
|
||||||
and playbooks.</p>
|
and playbooks.</p>
|
||||||
|
<p>You cannot use live checks here, like ‘os.path.exists’, so don’t try.</p>
|
||||||
|
<p>It’s also easy to provide your own facts if you want, which is covered in <a class="reference internal" href="moduledev.html"><em>Module Development</em></a>. To run them, just
|
||||||
|
make a call to your own custom fact gathering module at the top of your list of tasks, and variables returned
|
||||||
|
there will be accessible to future tasks:</p>
|
||||||
|
<div class="highlight-python"><pre>tasks:
|
||||||
|
- name: gather site specific fact data
|
||||||
|
action: site_facts
|
||||||
|
- action: command echo ${my_custom_fact_can_be_used_now}</pre>
|
||||||
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="conditional-imports">
|
<div class="section" id="conditional-imports">
|
||||||
<h2>Conditional Imports<a class="headerlink" href="#conditional-imports" title="Permalink to this headline">¶</a></h2>
|
<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.
|
<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>
|
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,
|
<p>As an example, the name of the Apache package may be different between CentOS and Debian,
|
||||||
|
@ -364,7 +430,7 @@ in more streamlined & auditable configuration rules – especially becau
|
||||||
minimum of decision points to track.</p>
|
minimum of decision points to track.</p>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="loop-shorthand">
|
<div class="section" id="loop-shorthand">
|
||||||
<h2>Loop Shorthand<a class="headerlink" href="#loop-shorthand" title="Permalink to this headline">¶</a></h2>
|
<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>
|
<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
|
<div class="highlight-python"><pre>- name: add user $item
|
||||||
action: user name=$item state=present groups=wheel
|
action: user name=$item state=present groups=wheel
|
||||||
|
@ -372,6 +438,9 @@ minimum of decision points to track.</p>
|
||||||
- testuser1
|
- testuser1
|
||||||
- testuser2</pre>
|
- testuser2</pre>
|
||||||
</div>
|
</div>
|
||||||
|
<p>If you have defined a YAML list in a variables file, or the ‘vars’ section, you can also do:</p>
|
||||||
|
<div class="highlight-python"><pre>with_items: $somelist</pre>
|
||||||
|
</div>
|
||||||
<p>The above would be the equivalent of:</p>
|
<p>The above would be the equivalent of:</p>
|
||||||
<div class="highlight-python"><pre>- name: add user testuser1
|
<div class="highlight-python"><pre>- name: add user testuser1
|
||||||
action: user name=testuser1 state=present groups=wheel
|
action: user name=testuser1 state=present groups=wheel
|
||||||
|
@ -382,9 +451,9 @@ minimum of decision points to track.</p>
|
||||||
manager transactions.</p>
|
manager transactions.</p>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="selecting-files-and-templates-based-on-variables">
|
<div class="section" id="selecting-files-and-templates-based-on-variables">
|
||||||
<h2>Selecting Files And Templates Based On Variables<a class="headerlink" href="#selecting-files-and-templates-based-on-variables" title="Permalink to this headline">¶</a></h2>
|
<h3>Selecting Files And Templates Based On Variables<a class="headerlink" href="#selecting-files-and-templates-based-on-variables" title="Permalink to this headline">¶</a></h3>
|
||||||
<p>Sometimes a configuration file you want to copy, or a template you will use may depend on a variable.
|
<p>Sometimes a configuration file you want to copy, or a template you will use may depend on a variable.
|
||||||
The following construct (new in 0.4) selects the first available file appropriate for the variables of a given host,
|
The following construct selects the first available file appropriate for the variables of a given host,
|
||||||
which is often much cleaner than putting a lot of if conditionals in a template.</p>
|
which is often much cleaner than putting a lot of if conditionals in a template.</p>
|
||||||
<p>The following example shows how to template out a configuration file that was very different between, say,
|
<p>The following example shows how to template out a configuration file that was very different between, say,
|
||||||
CentOS and Debian:</p>
|
CentOS and Debian:</p>
|
||||||
|
@ -396,7 +465,7 @@ CentOS and Debian:</p>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="asynchronous-actions-and-polling">
|
<div class="section" id="asynchronous-actions-and-polling">
|
||||||
<h2>Asynchronous Actions and Polling<a class="headerlink" href="#asynchronous-actions-and-polling" title="Permalink to this headline">¶</a></h2>
|
<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
|
<p>By default tasks in playbooks block, meaning the connections stay open
|
||||||
until the task is done on each node. If executing playbooks with
|
until the task is done on each node. If executing playbooks with
|
||||||
a small parallelism value (aka <tt class="docutils literal"><span class="pre">--forks</span></tt>), you may wish that long
|
a small parallelism value (aka <tt class="docutils literal"><span class="pre">--forks</span></tt>), you may wish that long
|
||||||
|
@ -446,7 +515,7 @@ tasks even faster. This also increases the efficiency of polling.</p>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="local-playbooks">
|
<div class="section" id="local-playbooks">
|
||||||
<h2>Local Playbooks<a class="headerlink" href="#local-playbooks" title="Permalink to this headline">¶</a></h2>
|
<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
|
<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
|
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>
|
to run a playbook inside a OS installer, such as an Anaconda kickstart.</p>
|
||||||
|
@ -459,10 +528,19 @@ use the default remote connection type:</p>
|
||||||
connection: local</pre>
|
connection: local</pre>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
<div class="section" id="turning-off-facts">
|
||||||
|
<h3>Turning Off Facts<a class="headerlink" href="#turning-off-facts" title="Permalink to this headline">¶</a></h3>
|
||||||
|
<p>If you know you don’t need any fact data about your hosts, and know everything about your systems centrally, you
|
||||||
|
can turn off fact gathering. This has advantages in scaling ansible in push mode with very large numbers of
|
||||||
|
systems, mainly, or if you are using Ansible on experimental platforms. In any play, just do this:</p>
|
||||||
|
<div class="highlight-python"><pre>- hosts: whatever
|
||||||
|
gather_facts: False</pre>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
<div class="section" id="pull-mode-playbooks">
|
<div class="section" id="pull-mode-playbooks">
|
||||||
<h2>Pull-Mode Playbooks<a class="headerlink" href="#pull-mode-playbooks" title="Permalink to this headline">¶</a></h2>
|
<h3>Pull-Mode Playbooks<a class="headerlink" href="#pull-mode-playbooks" title="Permalink to this headline">¶</a></h3>
|
||||||
<p>The use of playbooks in local mode (above) is made extremely powerful with the addition of <cite>ansible-pull</cite> in the
|
<p>The use of playbooks in local mode (above) is made extremely powerful with the addition of <cite>ansible-pull</cite>.
|
||||||
0.4 release. A script for setting up ansible-pull is provided in the examples/playbooks directory of the source
|
A script for setting up ansible-pull is provided in the examples/playbooks directory of the source
|
||||||
checkout.</p>
|
checkout.</p>
|
||||||
<p>The basic idea is to use Ansible to set up a remote copy of ansible on each managed node, each set to run via
|
<p>The basic idea is to use Ansible to set up a remote copy of ansible on each managed node, each set to run via
|
||||||
cron and update playbook source via git. This interverts the default push architecture of ansible into a pull
|
cron and update playbook source via git. This interverts the default push architecture of ansible into a pull
|
||||||
|
@ -470,6 +548,11 @@ architecture, which has near-limitless scaling potential. The setup playbook ca
|
||||||
the cron frequency, logging locations, and parameters to ansible-pull.</p>
|
the cron frequency, logging locations, and parameters to ansible-pull.</p>
|
||||||
<p>This is useful both for extreme scale-out as well as periodic remediation. Usage of the ‘fetch’ module to retrieve
|
<p>This is useful both for extreme scale-out as well as periodic remediation. Usage of the ‘fetch’ module to retrieve
|
||||||
logs from ansible-pull runs would be an excellent way to gather and analyze remote logs from ansible-pull.</p>
|
logs from ansible-pull runs would be an excellent way to gather and analyze remote logs from ansible-pull.</p>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="style-points">
|
||||||
|
<h3>Style Points<a class="headerlink" href="#style-points" title="Permalink to this headline">¶</a></h3>
|
||||||
|
<p>Ansible playbooks are colorized. If you do not like this, set the ANSIBLE_NOCOLOR=1 environment variable.</p>
|
||||||
|
<p>Ansible playbooks also look more impressive with cowsay installed, and we encourage installing this package.</p>
|
||||||
<div class="admonition-see-also admonition seealso">
|
<div class="admonition-see-also admonition seealso">
|
||||||
<p class="first admonition-title">See also</p>
|
<p class="first admonition-title">See also</p>
|
||||||
<dl class="last docutils">
|
<dl class="last docutils">
|
||||||
|
@ -493,6 +576,7 @@ logs from ansible-pull runs would be an excellent way to gather and analyze remo
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
|
||||||
<br/>
|
<br/>
|
||||||
|
@ -522,7 +606,7 @@ logs from ansible-pull runs would be an excellent way to gather and analyze remo
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
|
@ -174,8 +174,7 @@ Module Provided 'Facts'
|
||||||
|
|
||||||
The 'setup' module that ships with Ansible provides many variables about a system that can be used in playbooks
|
The 'setup' module that ships with Ansible provides many variables about a system that can be used in playbooks
|
||||||
and templates. However, it's possible to also add your own facts without modifying the system module. To do
|
and templates. However, it's possible to also add your own facts without modifying the system module. To do
|
||||||
this, just have the module return a `ansible_facts` key, like so, along with other return data. This requires
|
this, just have the module return a `ansible_facts` key, like so, along with other return data::
|
||||||
Ansible 0.4 and later::
|
|
||||||
|
|
||||||
{
|
{
|
||||||
"changed" : True,
|
"changed" : True,
|
||||||
|
|
|
@ -433,7 +433,6 @@ raw
|
||||||
```
|
```
|
||||||
|
|
||||||
Executes a low-down and dirty SSH command, not going through the module subsystem.
|
Executes a low-down and dirty SSH command, not going through the module subsystem.
|
||||||
This module is new in Ansible 0.4.
|
|
||||||
|
|
||||||
This is useful and should only be done in two cases. The first case is installing
|
This is useful and should only be done in two cases. The first case is installing
|
||||||
python-simplejson on older (python 2.4 and before) hosts that need it as a dependency
|
python-simplejson on older (python 2.4 and before) hosts that need it as a dependency
|
||||||
|
|
|
@ -110,7 +110,7 @@ Variables can also be applied to an entire group at once::
|
||||||
Groups of Groups, and Group Variables
|
Groups of Groups, and Group Variables
|
||||||
+++++++++++++++++++++++++++++++++++++
|
+++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
Using Ansible 0.4, it is possible to make groups of groups and assign
|
It is also possible to make groups of groups and assign
|
||||||
variables to groups. These variables can be used by /usr/bin/ansible-playbook, but not
|
variables to groups. These variables can be used by /usr/bin/ansible-playbook, but not
|
||||||
/usr/bin/ansible::
|
/usr/bin/ansible::
|
||||||
|
|
||||||
|
|
|
@ -1,11 +1,10 @@
|
||||||
Playbooks
|
Playbooks
|
||||||
=========
|
=========
|
||||||
|
|
||||||
Playbooks are a completely different way to use ansible and are
|
Playbooks are a completely different way to use ansible than in task execution mode, and are
|
||||||
particularly awesome. They are the basis for a really simple
|
particularly awesome. Simply put, playbooks are the basis for a really simple
|
||||||
configuration management and multi-machine deployment system,
|
configuration management and multi-machine deployment system,
|
||||||
unlike any that already exist, and
|
unlike any that already exist, and one that is very well suited to deploying complex applications.
|
||||||
one that is very well suited to deploying complex applications.
|
|
||||||
|
|
||||||
Playbooks can declare configurations, but they can also orchestrate steps of
|
Playbooks can declare configurations, but they can also orchestrate steps of
|
||||||
any manual ordered process, even as different steps must bounce back and forth
|
any manual ordered process, even as different steps must bounce back and forth
|
||||||
|
@ -21,12 +20,16 @@ Let's dive in and see how they work. As you go, you may wish to open
|
||||||
the `github examples directory <https://github.com/ansible/ansible/tree/master/examples/playbooks>`_ in
|
the `github examples directory <https://github.com/ansible/ansible/tree/master/examples/playbooks>`_ in
|
||||||
another tab, so you can apply the theory to what things look like in practice.
|
another tab, so you can apply the theory to what things look like in practice.
|
||||||
|
|
||||||
Playbook Example
|
Playbook Language Example
|
||||||
````````````````
|
`````````````````````````
|
||||||
|
|
||||||
Playbooks are expressed in YAML format and have a minimum of syntax.
|
Playbooks are expressed in YAML format and have a minimum of syntax.
|
||||||
Each playbook is composed of one or more 'plays' in a list.
|
Each playbook is composed of one or more 'plays' in a list.
|
||||||
|
|
||||||
|
The goal of a play is map a group of hosts to some well defined roles, represented by
|
||||||
|
things ansible called tasks. At the basic level, a task is nothing more than a call
|
||||||
|
to an ansible module, which you should have learned about in earlier chapters.
|
||||||
|
|
||||||
By composing a playbook of multiple 'plays', it is possible to
|
By composing a playbook of multiple 'plays', it is possible to
|
||||||
orchestrate multi-machine deployments, running certain steps on all
|
orchestrate multi-machine deployments, running certain steps on all
|
||||||
machines in the webservers group, then certain steps on the database
|
machines in the webservers group, then certain steps on the database
|
||||||
|
@ -116,25 +119,21 @@ These variables can be used later in the playbook like this::
|
||||||
|
|
||||||
$varname or ${varname}
|
$varname or ${varname}
|
||||||
|
|
||||||
The later is useful in the event you need to do something like ${other}_concatenated_value.
|
The later is useful in the event you need to do something like ${other}_some_string.
|
||||||
|
|
||||||
The full power of the Jinja2 templating language is also available (note: in 0.4, this is only true inside of templates), which looks like this::
|
The full power of the `Jinja2 <http://jinja.pocoo.org/docs/>`_ templating language is also available, which looks like this::
|
||||||
|
|
||||||
{{ varname }}
|
{{ varname }}
|
||||||
|
|
||||||
The Jinja2 documentation provides information about how to construct loops and conditionals for those
|
The Jinja2 documentation provides information about how to construct loops and conditionals for those
|
||||||
who which to use more advanced templating. This is optional and the $varname format still works in template
|
who which to use more advanced templating. This is optional and the $varname format still works in template
|
||||||
files.
|
files.
|
||||||
|
|
||||||
If there are discovered variables about the system (ansible provides some of these,
|
If there are discovered variables about the system, called 'facts', these variables bubble up back into the
|
||||||
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. Ansible provides several
|
||||||
playbook, and can be used on each system just like explicitly set
|
of these, prefixed with 'ansible', and are documented under :ref:`setup` in the module documentation. Additionally,
|
||||||
variables.
|
facts can be gathered by ohai and facter if they are installed. Facter variables are prefixed with ``facter_`` and Ohai
|
||||||
|
variables are prefixed with ``ohai_``.
|
||||||
Facter variables are prefixed with ``facter_`` and Ohai
|
|
||||||
variables are prefixed with ``ohai_``. Ansible variables (0.3 and later)
|
|
||||||
are not surprisingly prefixed with ``ansible_`` (See the :ref:`setup` module
|
|
||||||
documentation for a list of Ansible variables).
|
|
||||||
|
|
||||||
So for instance, if I wanted
|
So for instance, if I wanted
|
||||||
to write the hostname into the /etc/motd file, I could say::
|
to write the hostname into the /etc/motd file, I could say::
|
||||||
|
@ -153,23 +152,26 @@ Tasks list
|
||||||
|
|
||||||
Each play contains a list of tasks. Tasks are executed in order, one
|
Each play contains a list of tasks. Tasks are executed in order, one
|
||||||
at a time, against all machines matched by the host pattern,
|
at a time, against all machines matched by the host pattern,
|
||||||
before moving on to the next task.
|
before moving on to the next task. It is important to understand that, within a play,
|
||||||
|
all hosts are going to get the same task directives. It is the purpose of a play to map
|
||||||
|
a selection of hosts to tasks.
|
||||||
|
|
||||||
Hosts with failed tasks are taken out of the rotation for the entire
|
When running the playbook, which runs top to bottom, hosts with failed tasks are
|
||||||
playbook. If things fail, simply correct the playbook file and rerun.
|
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.
|
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.
|
Variables, as mentioned above, can be used in arguments to modules.
|
||||||
|
|
||||||
Modules other than `command` and `shell` are 'idempotent', meaning if you run them
|
Modules are 'idempotent', meaning if you run them
|
||||||
again, they will make the changes they are told to make to bring the
|
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
|
system to the desired state. This makes it very safe to rerun
|
||||||
the same playbook multiple times. They won't change things
|
the same playbook multiple times. They won't change things
|
||||||
unless they have to change things.
|
unless they have to change things.
|
||||||
|
|
||||||
The `command` and `shell` modules will actually rerun the same command again,
|
The `command` and `shell` modules will typically rerun the same command again,
|
||||||
which is totally ok if the command is something like
|
which is totally ok if the command is something like
|
||||||
'chmod' or 'setsebool', etc.
|
'chmod' or 'setsebool', etc. Though there is a 'creates' flag available which can
|
||||||
|
be used to make these modules also idempotent.
|
||||||
|
|
||||||
Every task should have a `name`, which is included in the output from
|
Every task should have a `name`, which is included in the output from
|
||||||
running the playbook. This is output for humans, so it is
|
running the playbook. This is output for humans, so it is
|
||||||
|
@ -192,6 +194,13 @@ them work just like you would expect. Simple::
|
||||||
- name: disable selinux
|
- name: disable selinux
|
||||||
action: command /sbin/setenforce 0
|
action: command /sbin/setenforce 0
|
||||||
|
|
||||||
|
The command and shell module care about return codes, so if you have a command
|
||||||
|
who's successful exit code is not zero, you may wish to do this:
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
- name: run this command and ignore the result
|
||||||
|
action: shell /usr/bin/somecommand & /bin/true
|
||||||
|
|
||||||
Variables can be used in action lines. Suppose you defined
|
Variables can be used in action lines. Suppose you defined
|
||||||
a variable called 'vhost' in the 'vars' section, you could do this::
|
a variable called 'vhost' in the 'vars' section, you could do this::
|
||||||
|
|
||||||
|
@ -201,11 +210,13 @@ a variable called 'vhost' in the 'vars' section, you could do this::
|
||||||
|
|
||||||
Those same variables are usable in templates, which we'll get to later.
|
Those same variables are usable in templates, which we'll get to later.
|
||||||
|
|
||||||
|
Now in a very basic playbook all the tasks will be listed directly in that play, though it will usually
|
||||||
|
make more sense to break up tasks using the 'include:' directive. We'll show that a bit later.
|
||||||
|
|
||||||
Running Operations On Change
|
Running Operations On Change
|
||||||
````````````````````````````
|
````````````````````````````
|
||||||
|
|
||||||
As we've mentioned, nearly all modules are written to be 'idempotent' and can relay when
|
As we've mentioned, modules are written to be 'idempotent' and can relay when
|
||||||
they have made a change on the remote system. Playbooks recognize this and
|
they have made a change on the remote system. Playbooks recognize this and
|
||||||
have a basic event system that can be used to respond to change.
|
have a basic event system that can be used to respond to change.
|
||||||
|
|
||||||
|
@ -246,13 +257,15 @@ won't need them for much else.
|
||||||
Notify handlers are always run in the order written.
|
Notify handlers are always run in the order written.
|
||||||
|
|
||||||
|
|
||||||
Include Files And Reuse
|
Include Files And Encouraging Reuse
|
||||||
```````````````````````
|
```````````````````````````````````
|
||||||
|
|
||||||
Suppose you want to reuse lists of tasks between plays or playbooks. You can use
|
Suppose you want to reuse lists of tasks between plays or playbooks. You can use
|
||||||
include files to do this.
|
include files to do this. Use of included task lists is a great way to define a role
|
||||||
|
that system is going to fulfill. Remember, the goal of a play in a playbook is to map
|
||||||
|
a group of systems into multiple roles. Let's see what this looks like...
|
||||||
|
|
||||||
An include file simply contains a flat list of tasks, like so::
|
A task include file simply contains a flat list of tasks, like so::
|
||||||
|
|
||||||
---
|
---
|
||||||
# possibly saved as tasks/foo.yml
|
# possibly saved as tasks/foo.yml
|
||||||
|
@ -261,12 +274,12 @@ An include file simply contains a flat list of tasks, like so::
|
||||||
- name: placeholder bar
|
- name: placeholder bar
|
||||||
action: command /bin/bar
|
action: command /bin/bar
|
||||||
|
|
||||||
Include directives look like this::
|
Include directives look like this, and can be mixed in with regular tasks in a playbook::
|
||||||
|
|
||||||
- tasks:
|
- tasks:
|
||||||
- include: tasks/foo.yml
|
- include: tasks/foo.yml
|
||||||
|
|
||||||
You can also pass variables into includes directly. We might call this a 'parameterized include'.
|
You can also pass variables into includes. We call this a 'parameterized include'.
|
||||||
|
|
||||||
For instance, if deploying multiple wordpress instances, I could
|
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::
|
contain all of my wordpress tasks in a single wordpress.yml file, and use it like so::
|
||||||
|
@ -276,17 +289,17 @@ contain all of my wordpress tasks in a single wordpress.yml file, and use it lik
|
||||||
- include: wordpress.yml user=alice
|
- include: wordpress.yml user=alice
|
||||||
- include: wordpress.yml user=bob
|
- include: wordpress.yml user=bob
|
||||||
|
|
||||||
Variables passed in can be used in the included files. You can reference them like this::
|
Variables passed in can then be used in the included files. You can reference them like this::
|
||||||
|
|
||||||
$user
|
$user
|
||||||
|
|
||||||
In addition to the explicitly passed in parameters, all variables from
|
(In addition to the explicitly passed in parameters, all variables from
|
||||||
the vars section are also available for use here as well.
|
the vars section are also available for use here as well.)
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
Include statements are only usable from the top level
|
Task include statements are only usable one-level deep.
|
||||||
playbook file. This means includes can not include other
|
This means task includes can not include other
|
||||||
includes. This may be implemented in a later release.
|
task includes. This may change in a later release.
|
||||||
|
|
||||||
Includes can also be used in the 'handlers' section, for instance, if you
|
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
|
want to define how to restart apache, you only have to do that once for all
|
||||||
|
@ -305,10 +318,12 @@ of a play::
|
||||||
|
|
||||||
You can mix in includes along with your regular non-included tasks and handlers.
|
You can mix in includes along with your regular non-included tasks and handlers.
|
||||||
|
|
||||||
Note that you can not conditionally path the location to an include file, like you can
|
NOTE:: 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
|
with 'vars_files'. If you find yourself needing to do this, consider how you can
|
||||||
restructure your playbook to be more class/role oriented.
|
restructure your playbook to be more class/role oriented. This is to say you cannot
|
||||||
|
use a 'fact' to decide what include file to use. All hosts contained within the play
|
||||||
|
are going to get the same tasks. ('only_if' provides some ability for hosts to conditionally
|
||||||
|
skip tasks).
|
||||||
|
|
||||||
Executing A Playbook
|
Executing A Playbook
|
||||||
````````````````````
|
````````````````````
|
||||||
|
|
|
@ -6,12 +6,51 @@ are not neccessary, but many of them will prove useful. If a feature doesn't se
|
||||||
relevant, feel free to skip it. For many people, the features documented in `playbooks` will
|
relevant, feel free to skip it. For many people, the features documented in `playbooks` will
|
||||||
be 90% or more of what they use in Ansible.
|
be 90% or more of what they use in Ansible.
|
||||||
|
|
||||||
|
Tags
|
||||||
|
````
|
||||||
|
|
||||||
|
(New in 0.6) If you have a large playbook it may become useful to be able to run a specific
|
||||||
|
part of the configuration. Both plays and tasks support a "tags:" attribute for this reason.
|
||||||
|
|
||||||
|
Example::
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
|
||||||
|
- action: yum name=$item state=installed
|
||||||
|
with_items:
|
||||||
|
- httpd
|
||||||
|
- memcached
|
||||||
|
tags:
|
||||||
|
- packages
|
||||||
|
|
||||||
|
- action: template src=templates/src.j2 dest=/etc/foo.conf
|
||||||
|
tags:
|
||||||
|
- configuration
|
||||||
|
|
||||||
|
If you wanted to just run the "configuration" and "packages" part of a very long playbook, you could do this::
|
||||||
|
|
||||||
|
ansible-playbook example.yml --tags "configuration,packages"
|
||||||
|
|
||||||
|
Playbooks Including Playbooks
|
||||||
|
`````````````````````````````
|
||||||
|
|
||||||
|
(New in 0.6) To further advance the concept of include files, playbook files can include other playbook
|
||||||
|
files. Suppose you define the behavior of all your webservers in "webservers.yml" and
|
||||||
|
all your database servers in "dbservers.yml". You can create a "site.yml" that would
|
||||||
|
reconfigure all of your systems like this::
|
||||||
|
|
||||||
|
----
|
||||||
|
- include: playbooks/webservers.yml
|
||||||
|
- include: playbooks/dbservers.yml
|
||||||
|
|
||||||
|
This concept works great with tags to rapidly select exactly what plays you want to run, and exactly
|
||||||
|
what parts of those plays.
|
||||||
|
|
||||||
Accessing Complex Variable Data
|
Accessing Complex Variable Data
|
||||||
+++++++++++++++++++++++++++++++
|
+++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
Some provided facts, like networking information, are made available as nested data structures. To access
|
Some provided facts, like networking information, are made available as nested data structures. To access
|
||||||
them a simple '$foo' is not sufficient, but it is still easy to do. Here's how we get an IP address using
|
them a simple '$foo' is not sufficient, but it is still easy to do. Here's how we get an IP address::
|
||||||
Ansible 0.4 and later::
|
|
||||||
|
|
||||||
${ansible_eth0.ipv4.address}
|
${ansible_eth0.ipv4.address}
|
||||||
|
|
||||||
|
@ -30,26 +69,19 @@ Accessing Information About Other Hosts
|
||||||
+++++++++++++++++++++++++++++++++++++++
|
+++++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
If your database server wants to check the value of a 'fact' from another node, or an inventory variable
|
If your database server wants to check the value of a 'fact' from another node, or an inventory variable
|
||||||
assigned to another node, it's easy to do so within a template or even an action line (note: this uses syntax available in 0.4 and later)::
|
assigned to another node, it's easy to do so within a template or even an action line::
|
||||||
|
|
||||||
${hostvars.hostname.factname}
|
${hostvars.hostname.factname}
|
||||||
|
|
||||||
NOTE: No database or other complex system is required to exchange data between hosts. The hosts that you
|
NOTE: No database or other complex system is required to exchange data between hosts. The hosts that you
|
||||||
want to reference data from must be included in either the current play or any previous play.
|
want to reference data from must be included in either the current play or any previous play.
|
||||||
|
|
||||||
Magic Variables
|
Additionally, *group_names* is a list (array) of all the groups the current host is in. This can be used in templates using Jinja2 syntax to make template source files that vary based on the group membership (or role) of the host::
|
||||||
+++++++++++++++
|
|
||||||
|
|
||||||
Some variables made available to hosts don't come from definitions in a playbook, the inventory file, or discovery from the system. There are only two of these, and are used in special cases that many users won't need.
|
|
||||||
|
|
||||||
*group_names* is a list (array) of all the groups the current host is in. This can be used in templates using Jinja2
|
|
||||||
syntax to make template source files that vary based on the group membership (or role) of the host::
|
|
||||||
|
|
||||||
{% if 'webserver' in group_names %}
|
{% if 'webserver' in group_names %}
|
||||||
# some part of a configuration file that only applies to webservers
|
# some part of a configuration file that only applies to webservers
|
||||||
{% endif %}
|
{% endif %}
|
||||||
|
|
||||||
|
|
||||||
*groups* is a list of all the groups (and hosts) in the inventory. This can be used to enumerate all hosts within a group.
|
*groups* is a list of all the groups (and hosts) in the inventory. This can be used to enumerate all hosts within a group.
|
||||||
For example::
|
For example::
|
||||||
|
|
||||||
|
@ -57,12 +89,14 @@ For example::
|
||||||
# something that applies to all app servers.
|
# something that applies to all app servers.
|
||||||
{% endfor %}
|
{% endfor %}
|
||||||
|
|
||||||
|
|
||||||
Use cases include pointing a frontend proxy server to all of the app servers, setting up the correct firewall rules between servers, etc.
|
Use cases include pointing a frontend proxy server to all of the app servers, setting up the correct firewall rules between servers, etc.
|
||||||
|
|
||||||
*inventory_hostname* is the name of the hostname as configured in Ansible's inventory host file. This can
|
*inventory_hostname* is the name of the hostname as configured in Ansible's inventory host file. This can
|
||||||
be useful for when you don't want to rely on the discovered hostname `ansible_hostname` or for other mysterious
|
be useful for when you don't want to rely on the discovered hostname `ansible_hostname` or for other mysterious
|
||||||
reasons. Don't worry about it unless you think you need it.
|
reasons. If you have a long FQDN, *inventory_hostname_short* (in Ansible 0.6) also contains the part up to the first
|
||||||
|
period.
|
||||||
|
|
||||||
|
Don't worry about any of this unless you think you need it. You'll know when you do.
|
||||||
|
|
||||||
Variable File Seperation
|
Variable File Seperation
|
||||||
++++++++++++++++++++++++
|
++++++++++++++++++++++++
|
||||||
|
@ -96,6 +130,8 @@ The contents of each variables file is a simple YAML dictionary, like this::
|
||||||
somevar: somevalue
|
somevar: somevalue
|
||||||
password: magic
|
password: magic
|
||||||
|
|
||||||
|
NOTE: It's also possible to keep per-host and per-group variables in very similar files, this is covered in :ref:`patterns`.
|
||||||
|
|
||||||
Prompting For Sensitive Data
|
Prompting For Sensitive Data
|
||||||
++++++++++++++++++++++++++++
|
++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
@ -117,6 +153,18 @@ in a push-script::
|
||||||
|
|
||||||
There are full examples of both of these items in the github examples/playbooks directory.
|
There are full examples of both of these items in the github examples/playbooks directory.
|
||||||
|
|
||||||
|
An alternative form of vars_prompt allows for hiding input from the user, and may later support
|
||||||
|
some other options, but otherwise works equivalently::
|
||||||
|
|
||||||
|
vars_prompt:
|
||||||
|
- name: "some_password"
|
||||||
|
prompt: "Enter password"
|
||||||
|
private: True
|
||||||
|
- name: "release_version"
|
||||||
|
prompt: "Product release version"
|
||||||
|
private: False
|
||||||
|
|
||||||
|
|
||||||
Passing Variables On The Command Line
|
Passing Variables On The Command Line
|
||||||
+++++++++++++++++++++++++++++++++++++
|
+++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
|
@ -126,6 +174,18 @@ where you may want to pass in the version of the application to deploy::
|
||||||
|
|
||||||
ansible-playbook release.yml --extra-vars "version=1.23.45 other_variable=foo"
|
ansible-playbook release.yml --extra-vars "version=1.23.45 other_variable=foo"
|
||||||
|
|
||||||
|
This is useful, for, among other things, setting the hosts group or the user for the playbook.
|
||||||
|
|
||||||
|
Example::
|
||||||
|
|
||||||
|
-----
|
||||||
|
- user: $user
|
||||||
|
hosts: $hosts
|
||||||
|
tasks:
|
||||||
|
- ...
|
||||||
|
|
||||||
|
ansible-playbook release.yml --extra-vars "hosts=vipers user=starbuck"
|
||||||
|
|
||||||
Conditional Execution
|
Conditional Execution
|
||||||
+++++++++++++++++++++
|
+++++++++++++++++++++
|
||||||
|
|
||||||
|
@ -140,20 +200,32 @@ Don't panic -- it's actually pretty simple::
|
||||||
favcolor: blue
|
favcolor: blue
|
||||||
is_favcolor_blue: "'$favcolor' == 'blue'"
|
is_favcolor_blue: "'$favcolor' == 'blue'"
|
||||||
is_centos: "'$facter_operatingsystem' == 'CentOS'"
|
is_centos: "'$facter_operatingsystem' == 'CentOS'"
|
||||||
|
|
||||||
tasks:
|
tasks:
|
||||||
- name: "shutdown if my favorite color is blue"
|
- name: "shutdown if my favorite color is blue"
|
||||||
action: command /sbin/shutdown -t now
|
action: command /sbin/shutdown -t now
|
||||||
only_if: '$is_favcolor_blue'
|
only_if: '$is_favcolor_blue'
|
||||||
|
|
||||||
Variables from tools like `facter` and `ohai` can be used here, if installed, or you can
|
Variables from tools like `facter` and `ohai` can be used here, if installed, or you can
|
||||||
use variables that bubble up from ansible (0.3 and later). As a reminder,
|
use variables that bubble up from ansible, which many are provided by the :ref:`setup` module. As a reminder,
|
||||||
these variables are prefixed, so it's `$facter_operatingsystem`, not `$operatingsystem`. Ansible's
|
these variables are prefixed, so it's `$facter_operatingsystem`, not `$operatingsystem`. Ansible's
|
||||||
built in variables are prefixed with `ansible_`. The only_if
|
built in variables are prefixed with `ansible_`.
|
||||||
expression is actually a tiny small bit of Python, so be sure to quote variables and make something
|
|
||||||
|
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`. It is a good idea to use 'vars_files' instead of 'vars' to define
|
that evaluates to `True` or `False`. 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
|
all of your conditional expressions in a way that makes them very easy to reuse between plays
|
||||||
and playbooks.
|
and playbooks.
|
||||||
|
|
||||||
|
You cannot use live checks here, like 'os.path.exists', so don't try.
|
||||||
|
|
||||||
|
It's also easy to provide your own facts if you want, which is covered in :doc:`moduledev`. To run them, just
|
||||||
|
make a call to your own custom fact gathering module at the top of your list of tasks, and variables returned
|
||||||
|
there will be accessible to future tasks::
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
- name: gather site specific fact data
|
||||||
|
action: site_facts
|
||||||
|
- action: command echo ${my_custom_fact_can_be_used_now}
|
||||||
|
|
||||||
Conditional Imports
|
Conditional Imports
|
||||||
+++++++++++++++++++
|
+++++++++++++++++++
|
||||||
|
@ -216,6 +288,10 @@ To save some typing, repeated tasks can be written in short-hand like so::
|
||||||
- testuser1
|
- testuser1
|
||||||
- testuser2
|
- testuser2
|
||||||
|
|
||||||
|
If you have defined a YAML list in a variables file, or the 'vars' section, you can also do::
|
||||||
|
|
||||||
|
with_items: $somelist
|
||||||
|
|
||||||
The above would be the equivalent of::
|
The above would be the equivalent of::
|
||||||
|
|
||||||
- name: add user testuser1
|
- name: add user testuser1
|
||||||
|
@ -231,7 +307,7 @@ Selecting Files And Templates Based On Variables
|
||||||
++++++++++++++++++++++++++++++++++++++++++++++++
|
++++++++++++++++++++++++++++++++++++++++++++++++
|
||||||
|
|
||||||
Sometimes a configuration file you want to copy, or a template you will use may depend on a variable.
|
Sometimes a configuration file you want to copy, or a template you will use may depend on a variable.
|
||||||
The following construct (new in 0.4) selects the first available file appropriate for the variables of a given host,
|
The following construct selects the first available file appropriate for the variables of a given host,
|
||||||
which is often much cleaner than putting a lot of if conditionals in a template.
|
which is often much cleaner than putting a lot of if conditionals in a template.
|
||||||
|
|
||||||
The following example shows how to template out a configuration file that was very different between, say,
|
The following example shows how to template out a configuration file that was very different between, say,
|
||||||
|
@ -312,11 +388,21 @@ use the default remote connection type::
|
||||||
hosts: 127.0.0.1
|
hosts: 127.0.0.1
|
||||||
connection: local
|
connection: local
|
||||||
|
|
||||||
|
Turning Off Facts
|
||||||
|
+++++++++++++++++
|
||||||
|
|
||||||
|
If you know you don't need any fact data about your hosts, and know everything about your systems centrally, you
|
||||||
|
can turn off fact gathering. This has advantages in scaling ansible in push mode with very large numbers of
|
||||||
|
systems, mainly, or if you are using Ansible on experimental platforms. In any play, just do this::
|
||||||
|
|
||||||
|
- hosts: whatever
|
||||||
|
gather_facts: False
|
||||||
|
|
||||||
Pull-Mode Playbooks
|
Pull-Mode Playbooks
|
||||||
+++++++++++++++++++
|
+++++++++++++++++++
|
||||||
|
|
||||||
The use of playbooks in local mode (above) is made extremely powerful with the addition of `ansible-pull` in the
|
The use of playbooks in local mode (above) is made extremely powerful with the addition of `ansible-pull`.
|
||||||
0.4 release. A script for setting up ansible-pull is provided in the examples/playbooks directory of the source
|
A script for setting up ansible-pull is provided in the examples/playbooks directory of the source
|
||||||
checkout.
|
checkout.
|
||||||
|
|
||||||
The basic idea is to use Ansible to set up a remote copy of ansible on each managed node, each set to run via
|
The basic idea is to use Ansible to set up a remote copy of ansible on each managed node, each set to run via
|
||||||
|
@ -327,6 +413,12 @@ the cron frequency, logging locations, and parameters to ansible-pull.
|
||||||
This is useful both for extreme scale-out as well as periodic remediation. Usage of the 'fetch' module to retrieve
|
This is useful both for extreme scale-out as well as periodic remediation. Usage of the 'fetch' module to retrieve
|
||||||
logs from ansible-pull runs would be an excellent way to gather and analyze remote logs from ansible-pull.
|
logs from ansible-pull runs would be an excellent way to gather and analyze remote logs from ansible-pull.
|
||||||
|
|
||||||
|
Style Points
|
||||||
|
++++++++++++
|
||||||
|
|
||||||
|
Ansible playbooks are colorized. If you do not like this, set the ANSIBLE_NOCOLOR=1 environment variable.
|
||||||
|
|
||||||
|
Ansible playbooks also look more impressive with cowsay installed, and we encourage installing this package.
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
|
|
||||||
|
|
|
@ -221,7 +221,7 @@ s.parentNode.insertBefore(ga, s);
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
File diff suppressed because one or more lines are too long
|
@ -257,7 +257,7 @@ s.parentNode.insertBefore(ga, s);
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
© Copyright 2012 Michael DeHaan.<br/>
|
© Copyright 2012 Michael DeHaan.<br/>
|
||||||
Last updated on Jul 30, 2012.<br/>
|
Last updated on Jul 31, 2012.<br/>
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
Loading…
Reference in a new issue