mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
rebuild
This commit is contained in:
Michael DeHaan
parent
2befb446a3
commit
b721176bdd
6 changed files with 131 additions and 72 deletions
10
api.html
10
api.html
|
|
@ -317,9 +317,13 @@ Welcome, I am templated with a value of a={{ a }}, b={{ b }}, and c={{ c }}</pre
|
|||
<div class="highlight-python"><pre>ansible webserver -m setup
|
||||
ansible webserver -m template -a "src=/tmp/motd.j2 dest=/etc/motd"</pre>
|
||||
</div>
|
||||
<p>Note that the name ‘webserver’ came from cobbler, as did the variables for the config file. You can still
|
||||
pass in your own variables like normal in Ansible, but variables from the external inventory script will
|
||||
override any that have the same name.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">The name ‘webserver’ came from cobbler, as did the variables for
|
||||
the config file. You can still pass in your own variables like
|
||||
normal in Ansible, but variables from the external inventory script
|
||||
will override any that have the same name.</p>
|
||||
</div>
|
||||
<p>So, with the template above (motd.j2), this would result in the following data being written to /etc/motd for system ‘foo’:</p>
|
||||
<div class="highlight-python"><pre>Welcome, I am templated with a value of a=2, b=3, and c=4</pre>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -187,50 +187,45 @@ s.parentNode.insertBefore(ga, s);
|
|||
<p>Here are some tips for making the most of Ansible.</p>
|
||||
<div class="section" id="always-mention-state">
|
||||
<h2>Always Mention State<a class="headerlink" href="#always-mention-state" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The ‘state’ parameter is optional to a lot of modules. Whether state=present or state=absent, it’s always
|
||||
best to leave that parameter in your playbooks to make it clear, especially as some modules support additional
|
||||
states.</p>
|
||||
<p>The ‘state’ parameter is optional to a lot of modules. Whether
|
||||
‘state=present’ or ‘state=absent’, it’s always best to leave that
|
||||
parameter in your playbooks to make it clear, especially as some
|
||||
modules support additional states.</p>
|
||||
</div>
|
||||
<div class="section" id="group-by-roles">
|
||||
<h2>Group By Roles<a class="headerlink" href="#group-by-roles" title="Permalink to this headline">¶</a></h2>
|
||||
<p>A system can be in multiple groups. See <a class="reference internal" href="patterns.html"><em>Inventory & Patterns</em></a>. Having groups named after things like
|
||||
‘webservers’ and ‘dbservers’ is repeated in the examples because it’s a very powerful concept.</p>
|
||||
<em>webservers</em> and <em>dbservers</em> is repeated in the examples because it’s a very powerful concept.</p>
|
||||
<p>This allows playbooks to target machines based on role, as well as to assign role specific variables
|
||||
using the group variable system.</p>
|
||||
</div>
|
||||
<div class="section" id="directory-organization">
|
||||
<h2>Directory Organization<a class="headerlink" href="#directory-organization" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Playbooks should be organized like this:</p>
|
||||
<div class="highlight-python"><pre>(root of source control repository)
|
||||
|
||||
global_vars.yml # variables for all playbooks
|
||||
acme/ # each playbook has a directory
|
||||
|
||||
setup.yml # playbook to manage the service
|
||||
stop.yml # playbook to halt the service (optional)
|
||||
|
||||
files/
|
||||
some_file_path_foo.conf
|
||||
|
||||
templates/
|
||||
etc_acme_conf_acme.conf
|
||||
etc_other_conf_other.conf
|
||||
|
||||
vars/
|
||||
main.yml # variables specific to this playbook
|
||||
|
||||
handlers/
|
||||
main.yml
|
||||
|
||||
tasks/
|
||||
setup.yml
|
||||
stop.yml</pre>
|
||||
<div class="highlight-python"><pre># root of source control repository
|
||||
├── acme/
|
||||
│ ├── setup.yml
|
||||
│ └── stop.yml
|
||||
├── files/
|
||||
│ └── some_file_path_foo.conf
|
||||
├── handlers/
|
||||
│ └── main.yml
|
||||
├── tasks/
|
||||
│ ├── setup.yml
|
||||
│ └── stop.yml
|
||||
├── templates/
|
||||
│ ├── etc_acme_conf_acme.conf
|
||||
│ └── etc_other_conf_other.conf
|
||||
├── vars/
|
||||
│ └── main.yml
|
||||
└── global_vars.yml</pre>
|
||||
</div>
|
||||
<p>Any directories or files not needed can be omitted. Not all modules may require <cite>vars</cite> or <cite>files</cite> sections, though most
|
||||
will require <cite>handlers</cite>, <cite>tasks</cite>, and <cite>templates</cite>. To review what each of these sections do, see <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> and <a class="reference internal" href="playbooks2.html"><em>Advanced Playbooks</em></a>.</p>
|
||||
<p>Any directories or files not needed can be omitted. Not all modules
|
||||
may require ‘vars’ or ‘files’ sections, though most will require
|
||||
‘handlers’, ‘tasks’, and ‘templates’. To review what each of
|
||||
these sections do, see <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> and <a class="reference internal" href="playbooks2.html"><em>Advanced Playbooks</em></a>.</p>
|
||||
<p>The acme/setup.yml playbook would be as simple as:</p>
|
||||
<div class="highlight-python"><pre>----
|
||||
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: webservers
|
||||
user: root
|
||||
|
||||
|
|
@ -246,7 +241,8 @@ will require <cite>handlers</cite>, <cite>tasks</cite>, and <cite>templates</cit
|
|||
are contained in ‘acme/handlers/main.yml’. As a reminder, handlers are mostly just used to notify services to restart
|
||||
when things change, and these are described in <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>.</p>
|
||||
<p>Including more than one setup file or more than one handlers file is of course legal.</p>
|
||||
<p>Having playbooks be able to include other playbooks is coming in a future release. See Issue 538.</p>
|
||||
<p>Having playbooks be able to include other playbooks is coming in a
|
||||
future release. See <a class="reference external" href="https://github.com/ansible/ansible/issues/538">Issue 538</a>.</p>
|
||||
<p>Until then, to manage your entire site, simply execute all of your playbooks together, in the order desired.
|
||||
You don’t have to do this though. It’s fine to select sections of your infrastructure to manage at a single time.
|
||||
You may wish to construct simple shell scripts to wrap calls to ansible-playbook.</p>
|
||||
|
|
@ -262,17 +258,39 @@ keep modules that go with a playbook together.</p>
|
|||
</div>
|
||||
<div class="section" id="miscellaneous-tips">
|
||||
<h2>Miscellaneous Tips<a class="headerlink" href="#miscellaneous-tips" title="Permalink to this headline">¶</a></h2>
|
||||
<p>When you can do something simply, do something simply. Do not reach to use every feature of Ansible together, all
|
||||
at once. Use what works for you. For example, you should probably not need <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">vars_files</span></tt>, <tt class="docutils literal"><span class="pre">vars_prompt</span></tt> and <tt class="docutils literal"><span class="pre">--extra-vars</span></tt> all at once, while also using an external inventory file.</p>
|
||||
<p>Optimize for readability. Whitespace between sections of YAML documents and in between tasks is strongly encouraged,
|
||||
as is usage of YAML comments, which start with “#”. It is also useful to comment at the top of each file the purpose of the individual file and the author, including email address.</p>
|
||||
<p>It is possible to leave off the “name” for a given task, though it is recommended to provide
|
||||
a descriptive comment about why something is being done instead.</p>
|
||||
<p>Use version control. Keep your playbooks and inventory file in git (or another version control system), and commit when you make changes to them.
|
||||
This way you have an audit trail describing when and why you changed the rules automating your infrastructure.</p>
|
||||
<p>Resist the urge to write the same playbooks and configuration files for heterogeneous distributions. While lots of software packages claim to make this easy on you, the configuration files are often quite different, to the point where it would be easier to treat them as different playbooks. This is why, for example, Ansible has a seperate ‘yum’ and ‘apt’ module. Yum and apt have different capabilities, and we don’t want to code for the least common denominator.</p>
|
||||
<p>Use variables for user tunable settings versus having constants in the tasks file or templates, so that it is easy to reconfigure a playbook. Think about this as exposing the knobs to things you would like to tweak.</p>
|
||||
<p>Since a system can be in more than one group, if you have multiple datacenters or sites, consider putting systems into groups by role, but also different groups by geography. This allows you to assign different variables to different geographies.</p>
|
||||
<p>When you can do something simply, do something simply. Do not reach
|
||||
to use every feature of Ansible together, all at once. Use what works
|
||||
for you. For example, you should probably not need ‘vars’,
|
||||
‘vars_files’, ‘vars_prompt’ and ‘–extra-vars’ all at once,
|
||||
while also using an external inventory file.</p>
|
||||
<p>Optimize for readability. Whitespace between sections of YAML
|
||||
documents and in between tasks is strongly encouraged, as is usage of
|
||||
YAML comments, which start with ‘#’. It is also useful to comment
|
||||
at the top of each file the purpose of the individual file and the
|
||||
author, including email address.</p>
|
||||
<p>It is possible to leave off the ‘name’ for a given task, though it
|
||||
is recommended to provide a descriptive comment about why something is
|
||||
being done instead.</p>
|
||||
<p>Use version control. Keep your playbooks and inventory file in git
|
||||
(or another version control system), and commit when you make changes
|
||||
to them. This way you have an audit trail describing when and why you
|
||||
changed the rules automating your infrastructure.</p>
|
||||
<p>Resist the urge to write the same playbooks and configuration files
|
||||
for heterogeneous distributions. While lots of software packages
|
||||
claim to make this easy on you, the configuration files are often
|
||||
quite different, to the point where it would be easier to treat them
|
||||
as different playbooks. This is why, for example, Ansible has a
|
||||
separate <a class="reference internal" href="modules.html#yum"><em>yum</em></a> and <a class="reference internal" href="modules.html#apt"><em>apt</em></a> module. Yum and apt have different
|
||||
capabilities, and we don’t want to code for the least common
|
||||
denominator.</p>
|
||||
<p>Use variables for user tunable settings versus having constants in the
|
||||
tasks file or templates, so that it is easy to reconfigure a playbook.
|
||||
Think about this as exposing the knobs to things you would like to
|
||||
tweak.</p>
|
||||
<p>Since a system can be in more than one group, if you have multiple
|
||||
datacenters or sites, consider putting systems into groups by role,
|
||||
but also different groups by geography. This allows you to assign
|
||||
different variables to different geographies.</p>
|
||||
<div class="admonition-see-also admonition seealso">
|
||||
<p class="first admonition-title">See also</p>
|
||||
<dl class="last docutils">
|
||||
|
|
|
|||
29
modules.html
29
modules.html
|
|
@ -305,6 +305,8 @@ apt pkg=openjdk-6-jdk state=latest install-recommends=no</pre>
|
|||
</div>
|
||||
<div class="section" id="apt-repository">
|
||||
<span id="id2"></span><h2>apt_repository<a class="headerlink" href="#apt-repository" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.7.</span></p>
|
||||
<p>Manages apt repositores</p>
|
||||
<table border="1" class="docutils">
|
||||
<colgroup>
|
||||
|
|
@ -466,9 +468,13 @@ arguments, space delimited.</p>
|
|||
be processed through the shell, so variables like “$HOME” and
|
||||
operations like “<”, “>”, “|”, and “&” will not work. As such, all
|
||||
paths to commands must be fully qualified.</p>
|
||||
<p>NOTE:: If you want to run a command through the shell (say you are using
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">If you want to run a command through the shell (say you are using
|
||||
‘<’, ‘>’, ‘|’, etc), you actually want the ‘shell’ module instead.
|
||||
The ‘command’ module is much more secure as it’s not affected by the user’s environment.</p>
|
||||
The ‘command’ module is much more secure as it’s not affected by
|
||||
the user’s environment.</p>
|
||||
</div>
|
||||
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
||||
<div class="highlight-python"><pre>command /sbin/shutdown -t now</pre>
|
||||
</div>
|
||||
|
|
@ -521,6 +527,8 @@ relative.</td>
|
|||
</div>
|
||||
<div class="section" id="easy-install">
|
||||
<span id="easyinstall"></span><h2>easy_install<a class="headerlink" href="#easy-install" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.7.</span></p>
|
||||
<p>The easy_install module installs Python libraries.</p>
|
||||
<table border="1" class="docutils">
|
||||
<colgroup>
|
||||
|
|
@ -1059,6 +1067,8 @@ from /usr/bin/ansible:</p>
|
|||
</div>
|
||||
<div class="section" id="pip">
|
||||
<span id="id17"></span><h2>pip<a class="headerlink" href="#pip" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.7.</span></p>
|
||||
<p>Manages Python library dependencies.</p>
|
||||
<table border="1" class="docutils">
|
||||
<colgroup>
|
||||
|
|
@ -1415,17 +1425,22 @@ but runs the command through the user’s configured shell on the remote nod
|
|||
</tbody>
|
||||
</table>
|
||||
<p>The given command will be executed on all selected nodes.</p>
|
||||
<p>NOTE:: If you want to execute a command securely and predicably, it may
|
||||
be better to use the ‘command’ module instead. Best practices
|
||||
when writing playbooks will follow the trend of using ‘command’
|
||||
unless ‘shell’ is explicitly required. When running ad-hoc commands,
|
||||
use your best judgement.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">If you want to execute a command securely and predicably, it may be
|
||||
better to use the ‘command’ module instead. Best practices when
|
||||
writing playbooks will follow the trend of using ‘command’ unless
|
||||
‘shell’ is explicitly required. When running ad-hoc commands, use
|
||||
your best judgement.</p>
|
||||
</div>
|
||||
<p>Example action from a playbook:</p>
|
||||
<div class="highlight-python"><pre>shell somescript.sh >> somelog.txt</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="supervisorctl">
|
||||
<span id="id22"></span><h2>supervisorctl<a class="headerlink" href="#supervisorctl" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.7.</span></p>
|
||||
<p>Manage the state of a program or group of programs running via Supervisord</p>
|
||||
<table border="1" class="docutils">
|
||||
<colgroup>
|
||||
|
|
|
|||
|
|
@ -267,12 +267,19 @@ documentation. The <cite>user</cite> is just the name of the user account:</p>
|
|||
<p>If you need to specify a password to sudo, run <cite>ansible-playbook</cite> with <tt class="docutils literal"><span class="pre">--ask-sudo-pass</span></tt> (<cite>-K</cite>).
|
||||
If you run a sudo playbook and the playbook seems to hang, it’s probably stuck at the sudo prompt.
|
||||
Just <cite>Control-C</cite> to kill it and run it again with <cite>-K</cite>.</p>
|
||||
<p>NOTE: When using <cite>sudo_user</cite> to a user other than root, the module arguments are briefly written into
|
||||
a random tempfile in /tmp. These are deleted immediately after the command is executed. This only
|
||||
occurs when sudoing from a user like ‘bob’ to ‘timmy’, not when going from ‘bob’ to ‘root’, or
|
||||
logging in directly as ‘bob’ or ‘root’. If this concerns you that this data is briefly readable
|
||||
(not writeable), avoid transferring uncrypted passwords with <cite>sudo_user</cite> set. In other cases, ‘/tmp’ is not used and
|
||||
this does not come into play. Ansible also takes care to not log password parameters.</p>
|
||||
<div class="admonition important">
|
||||
<p class="first admonition-title">Important</p>
|
||||
<p class="last">When using <cite>sudo_user</cite> to a user other than root, the module
|
||||
arguments are briefly written into a random tempfile in /tmp.
|
||||
These are deleted immediately after the command is executed. This
|
||||
only occurs when sudoing from a user like ‘bob’ to ‘timmy’, not
|
||||
when going from ‘bob’ to ‘root’, or logging in directly as ‘bob’ or
|
||||
‘root’. If this concerns you that this data is briefly readable
|
||||
(not writeable), avoid transferring uncrypted passwords with
|
||||
<cite>sudo_user</cite> set. In other cases, ‘/tmp’ is not used and this does
|
||||
not come into play. Ansible also takes care to not log password
|
||||
parameters.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="vars-section">
|
||||
<h3>Vars section<a class="headerlink" href="#vars-section" title="Permalink to this headline">¶</a></h3>
|
||||
|
|
@ -459,12 +466,16 @@ of a play:</p>
|
|||
- include: handlers/handlers.yml</pre>
|
||||
</div>
|
||||
<p>You can mix in includes along with your regular non-included tasks and handlers.</p>
|
||||
<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
|
||||
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 class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">You can not conditionally path the location to an include file,
|
||||
like you can with ‘vars_files’. If you find yourself needing to do
|
||||
this, consider how you can restructure your playbook to be more
|
||||
class/role oriented. 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">
|
||||
<h2>Executing A Playbook<a class="headerlink" href="#executing-a-playbook" title="Permalink to this headline">¶</a></h2>
|
||||
|
|
|
|||
|
|
@ -274,8 +274,12 @@ that is preferred:</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>
|
||||
<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>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">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>
|
||||
</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="highlight-python"><pre>{% if 'webserver' in group_names %}
|
||||
# some part of a configuration file that only applies to webservers
|
||||
|
|
@ -321,7 +325,11 @@ sharing your playbook source with them.</p>
|
|||
somevar: somevalue
|
||||
password: magic</pre>
|
||||
</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 class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">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">
|
||||
<h2>Prompting For Sensitive Data<a class="headerlink" href="#prompting-for-sensitive-data" title="Permalink to this headline">¶</a></h2>
|
||||
|
|
@ -421,8 +429,11 @@ but it is easily handled with a minimum of syntax in an Ansible Playbook:</p>
|
|||
- name: make sure apache is running
|
||||
action: service name=$apache state=running</pre>
|
||||
</div>
|
||||
<p>Note that a variable (<cite>$facter_operatingsystem</cite>) is being interpolated into the list of
|
||||
filenames being defined for vars_files.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">The variable (<cite>$facter_operatingsystem</cite>) is being interpolated into
|
||||
the list of filenames being defined for vars_files.</p>
|
||||
</div>
|
||||
<p>As a reminder, the various YAML files contain just keys and values:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
# for vars/CentOS.yml
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
Loading…
Reference in a new issue