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

Slight tweaks to playbook docs + docs rebuild

Browse source
This commit is contained in:
Michael DeHaan 2012-03-13 20:32:55 -04:00
parent 8484fe3147
commit 496686629a
16 changed files with 93 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
YAMLSyntax.html
View file

@ -186,8 +186,8 @@ is used in practice.</p>
</div>
<div class="section" id="yaml-basics">
<h2>YAML Basics<a class="headerlink" href="#yaml-basics" title="Permalink to this headline"></a></h2>
<p>For <cite>ansible</cite>, every YAML file starts with a list of things
to do. Each item in the list is a list of key/value pairs, commonly
<p>For <cite>ansible</cite>, nearly every YAML file starts with a list.
Each item in the list is a list of key/value pairs, commonly
called a &#8220;hash&#8221; or a &#8220;dictionary&#8221;. So, we need to know how
to write lists and dictionaries in YAML.</p>
<p>There&#8217;s another small quirk to YAML. All YAML files (regardless of their association with
@ -260,7 +260,7 @@ languages:
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

2
api.html
View file

@ -244,7 +244,7 @@ command line tools <tt class="docutils literal"><span class="pre">ansible</span>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

2
examples.html
View file

@ -297,7 +297,7 @@ software upgrades only.</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

2
faq.html
View file

@ -346,7 +346,7 @@ tasks &#8211; whether for a QA sytem, build system, or anything you can think of
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

2
genindex.html
View file

@ -173,7 +173,7 @@ alt="Fork me on GitHub"
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

2
gettingstarted.html
View file

@ -288,7 +288,7 @@ you already have a working infrastructure!</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

2
index.html
View file

@ -345,7 +345,7 @@ Puppet Labs, and rPath. Reach Michael by email <a class="reference external" hr
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

2
man.html
View file

@ -191,7 +191,7 @@ examples of these tools in use.</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

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

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-playbook</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-playbook" lang="en"><a id="id320402"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — run an ansible playbook</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible-playbook &lt;filename.yml&gt; … [options]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible playbooks</strong></span> are a configuration and multinode deployment system. Ansible-playbook is the tool
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-playbook</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-playbook" lang="en"><a id="id322382"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — run an ansible playbook</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible-playbook &lt;filename.yml&gt; … [options]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible playbooks</strong></span> are a configuration and multinode deployment system. Ansible-playbook is the tool
used to run them. See the project home page (link below) for more information.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
<span class="strong"><strong>filename.yml</strong></span>
</span></dt><dd>

2
man/ansible.1.html
View file

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id570190"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id503186"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
SSH.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
<span class="strong"><strong>host-pattern</strong></span>
</span></dt><dd>

2
modules.html
View file

@ -380,7 +380,7 @@ arguments just like they would be passed with ansible.</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

2
patterns.html
View file

@ -242,7 +242,7 @@ wildcards:</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

67
playbooks.html
View file

@ -194,6 +194,8 @@ alt="Fork me on GitHub"
<dd>Learn about available modules and writing your own</dd>
<dt><a class="reference internal" href="patterns.html"><em>The Inventory File, Patterns, and Groups</em></a></dt>
<dd>Learn about how to select hosts</dd>
<dt><a class="reference external" href="https://github.com/ansible/ansible/tree/master/examples/playbooks">Github examples directory</a></dt>
<dd>Complete playbook files from the github project source</dd>
</dl>
</div>
<p>Playbooks are a completely different way to use ansible and are
@ -224,7 +226,6 @@ server group, then more commands back on the webservers group, etc.</p>
max_clients: 200
user: root
tasks:
- include: base.yml somevar=3 othervar=4
- name: ensure apache is at the latest version
action: yum pkg=httpd state=latest
- name: write the apache config file
@ -234,7 +235,8 @@ server group, then more commands back on the webservers group, etc.</p>
- name: ensure apache is running
action: service name=httpd state=started
handlers:
- include: handlers.yml</pre>
- name: restart apache
action: service name=apache state=restarted</pre>
</div>
<p>Below, we&#8217;ll break down what the various features of the playbook language are.</p>
</div>
@ -324,7 +326,7 @@ change, but only if the file changes:</p>
action: template src=template.j2 dest=/etc/foo.conf
notify:
- restart memcached
- restart foo</pre>
- restart apache</pre>
</div>
<p>Next up, we&#8217;ll show what a handler looks like.</p>
<div class="admonition note">
@ -341,10 +343,10 @@ of how many things notify a handler, it will run only once, after all
of the tasks complete in a particular play.</p>
<p>Here&#8217;s an example handlers section:</p>
<div class="highlight-python"><pre>handlers:
- name: restart apache
action: service name=apache state=restarted
- name: restart memcached
action: service name=memcached state=restarted</pre>
action: service name=memcached state=restarted
- name: restart apache
action: service name=apache state=restarted</pre>
</div>
<p>Handlers are best used to restart services and trigger reboots. You probably
won&#8217;t need them for much else.</p>
@ -365,7 +367,7 @@ variables file, or files, just like this:</p>
vars:
favcolor: blue
vars_files:
- /path/to/external_vars.yml
- /vars/external_vars.yml
tasks:
- name: this is just a placeholder
action: command /bin/echo foo</pre>
@ -374,6 +376,7 @@ variables file, or files, just like this:</p>
sharing your playbook source with them.</p>
<p>The contents of each variables file is a simple YAML dictionary, like this:</p>
<div class="highlight-python"><pre>---
# in the above example, this would be vars/external_vars.yml
somevar: somevalue
password: magic</pre>
</div>
@ -382,17 +385,32 @@ password: magic</pre>
<h3>Include Files And Reuse<a class="headerlink" href="#include-files-and-reuse" title="Permalink to this headline"></a></h3>
<p>Suppose you want to reuse lists of tasks between plays or playbooks. You can use
include files to do this.</p>
<p>An include file simply contains a list of tasks, like so:</p>
<p>An include file simply contains a flat list of tasks, like so:</p>
<div class="highlight-python"><pre>---
# possibly saved as tasks/foo.yml
- name: placeholder foo
action: command /bin/foo
- name: placeholder bar
action: command /bin/bar</pre>
</div>
<p>Variables passed in can be deferenced too. Assume a variable named &#8216;user&#8217;. Using
<p>Include directives look like this:</p>
<blockquote>
<div><ul>
<li><dl class="first docutils">
<dt>tasks:</dt>
<dd><ul class="first last simple">
<li>include: tasks/foo.yml</li>
</ul>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
<p>Variables passed in can be used in the include files too. Assume a variable named &#8216;user&#8217;. Using
<cite>jinja2</cite> syntax, anywhere in the included file, you can say:</p>
<div class="highlight-python"><pre>{{ user }}</pre>
</div>
<p>I can also pass variables into includes directly. We might call this a &#8216;parameterized include&#8217;.</p>
<p>For instance, if deploying multiple wordpress instances, I could
contain all of my wordpress tasks in a single wordpress.yml file, and use it like so:</p>
<div class="highlight-python"><pre>- tasks:
@ -402,8 +420,8 @@ contain all of my wordpress tasks in a single wordpress.yml file, and use it lik
</div>
<p>In addition to the explicitly passed in parameters, all variables from
the vars section are also available for use here as well. Variables that bubble
up from tools like facter and ohai are not though &#8211; but they ARE available for use
inside &#8216;action&#8217; lines.</p>
up from tools like facter and ohai are not usable here though &#8211; but they ARE available for use
inside &#8216;action&#8217; lines and in templates.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Include statements are only usable from the top level
@ -414,13 +432,14 @@ includes.</p>
want to define how to restart apache, you only have to do that once for all
of your playbooks. You might make a notifiers.yaml that looked like:</p>
<div class="highlight-python"><pre>----
# this might be in a file like handlers/handlers.yml
- name: restart apache
action: service name=apache state=restarted</pre>
</div>
<p>And in your main playbook file, just include it like so, at the bottom
of a play:</p>
<div class="highlight-python"><pre>handlers:
- include: handlers.yml</pre>
- include: handlers/handlers.yml</pre>
</div>
<p>You can mix in includes along with your regular non-included tasks and handlers.</p>
</div>
@ -434,22 +453,24 @@ this, in a list of just a few plays:</p>
vars:
datacenter: atlanta
tasks:
- include: base.yml
- include: webservers.yml database=db.atlanta.com
- include: tasks/base.yml
- include: tasks/webservers.yml database=db.atlanta.com
handlers:
- include: generic-handlers.yml
- include: handlers/common.yml
- hosts: atlanta-dbservers
vars:
datacenter: atlanta
tasks:
- include: base.yml
- include: dbservers.yml
- include: tasks/base.yml
- include: tasks/dbservers.yml
handlers:
- include: generic-handlers.yml</pre>
- include: handlers/common.yml</pre>
</div>
<p>There is one (or more) play defined for each group of systems, and
each play maps each group to several includes. These includes represent
&#8216;class definitions&#8217;, telling the systems what they are supposed to do or be.</p>
&#8216;class definitions&#8217;, telling the systems what they are supposed to do or be.
In the above example, all hosts get the base configuration first and further
customize it depending on what class or nature of machines they are.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Playbooks do not always have to be declarative; you can do something
@ -490,7 +511,7 @@ default.</p>
- hosts: all
user: root
tasks:
- name: simulate long running op (15 sec), wait for up to 45, poll every 5
- name: simulate long running op, allow to run for 45, fire and forget
action: command /bin/sleep 15
async: 45
poll: 0</pre>
@ -514,6 +535,10 @@ tasks even faster. This also increases the efficiency of polling.</p>
Let&#8217;s run a playbook using a parallelism level of 10:</p>
<div class="highlight-python"><pre>ansible-playbook playbook.yml -f 10</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Don&#8217;t forget to check out the <a class="reference external" href="https://github.com/ansible/ansible/tree/master/examples/playbooks">Github examples directory</a> for examples of playbooks in action, so you can see how all of these features can be put together.</p>
</div>
</div>
</div>
@ -524,7 +549,7 @@ Let&#8217;s run a playbook using a parallelism level of 10:</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

46
rst/playbooks.rst
View file

@ -9,6 +9,8 @@ Playbooks
Learn about available modules and writing your own
:doc:`patterns`
Learn about how to select hosts
`Github examples directory <https://github.com/ansible/ansible/tree/master/examples/playbooks>`_
Complete playbook files from the github project source
Playbooks are a completely different way to use ansible and are
@ -49,7 +51,6 @@ For starters, here's a playbook that contains just one play.::
max_clients: 200
user: root
tasks:
- include: base.yml somevar=3 othervar=4
- name: ensure apache is at the latest version
action: yum pkg=httpd state=latest
- name: write the apache config file
@ -59,8 +60,8 @@ For starters, here's a playbook that contains just one play.::
- name: ensure apache is running
action: service name=httpd state=started
handlers:
- include: handlers.yml
- name: restart apache
action: service name=apache state=restarted
Below, we'll break down what the various features of the playbook language are.
@ -220,7 +221,7 @@ variables file, or files, just like this::
vars:
favcolor: blue
vars_files:
- /path/to/external_vars.yml
- /vars/external_vars.yml
tasks:
- name: this is just a placeholder
action: command /bin/echo foo
@ -231,6 +232,7 @@ sharing your playbook source with them.
The contents of each variables file is a simple YAML dictionary, like this::
---
# in the above example, this would be vars/external_vars.yml
somevar: somevalue
password: magic
@ -241,19 +243,27 @@ Include Files And Reuse
Suppose you want to reuse lists of tasks between plays or playbooks. You can use
include files to do this.
An include file simply contains a list of tasks, like so::
An include file simply contains a flat list of tasks, like so::
---
# possibly saved as tasks/foo.yml
- name: placeholder foo
action: command /bin/foo
- name: placeholder bar
action: command /bin/bar
Variables passed in can be deferenced too. Assume a variable named 'user'. Using
Include directives look like this:
- tasks:
- include: tasks/foo.yml
Variables passed in can be used in the include files too. Assume a variable named 'user'. Using
`jinja2` syntax, anywhere in the included file, you can say::
{{ user }}
I can also pass variables into includes directly. We might call this a 'parameterized include'.
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::
@ -264,8 +274,8 @@ contain all of my wordpress tasks in a single wordpress.yml file, and use it lik
In addition to the explicitly passed in parameters, all variables from
the vars section are also available for use here as well. Variables that bubble
up from tools like facter and ohai are not though -- but they ARE available for use
inside 'action' lines.
up from tools like facter and ohai are not usable here though -- but they ARE available for use
inside 'action' lines and in templates.
.. note::
Include statements are only usable from the top level
@ -277,6 +287,7 @@ want to define how to restart apache, you only have to do that once for all
of your playbooks. You might make a notifiers.yaml that looked like::
----
# this might be in a file like handlers/handlers.yml
- name: restart apache
action: service name=apache state=restarted
@ -284,7 +295,7 @@ And in your main playbook file, just include it like so, at the bottom
of a play::
handlers:
- include: handlers.yml
- include: handlers/handlers.yml
You can mix in includes along with your regular non-included tasks and handlers.
@ -301,22 +312,24 @@ this, in a list of just a few plays::
vars:
datacenter: atlanta
tasks:
- include: base.yml
- include: webservers.yml database=db.atlanta.com
- include: tasks/base.yml
- include: tasks/webservers.yml database=db.atlanta.com
handlers:
- include: generic-handlers.yml
- include: handlers/common.yml
- hosts: atlanta-dbservers
vars:
datacenter: atlanta
tasks:
- include: base.yml
- include: dbservers.yml
- include: tasks/base.yml
- include: tasks/dbservers.yml
handlers:
- include: generic-handlers.yml
- include: handlers/common.yml
There is one (or more) play defined for each group of systems, and
each play maps each group to several includes. These includes represent
'class definitions', telling the systems what they are supposed to do or be.
In the above example, all hosts get the base configuration first and further
customize it depending on what class or nature of machines they are.
.. note::
Playbooks do not always have to be declarative; you can do something
@ -383,4 +396,7 @@ Let's run a playbook using a parallelism level of 10::
ansible-playbook playbook.yml -f 10
.. note::
Don't forget to check out the `Github examples directory <https://github.com/ansible/ansible/tree/master/examples/playbooks>`_ for examples of playbooks in action, so you can see how all of these features can be put together.

2
search.html
View file

@ -187,7 +187,7 @@ alt="Fork me on GitHub"
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Mar 12, 2012.<br/>
Last updated on Mar 13, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

2
searchindex.js
View file

File diff suppressed because one or more lines are too long