mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
413 lines
No EOL
19 KiB
HTML
413 lines
No EOL
19 KiB
HTML
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
|
|
<title>Ansible Modules — Ansible - SSH-Based Configuration Management & Deployment</title>
|
|
<link rel="stylesheet" href="_static/default.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/bootstrap.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: '',
|
|
VERSION: '0.01',
|
|
COLLAPSE_INDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: false
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
<script type="text/javascript" src="_static/bootstrap-dropdown.js"></script>
|
|
<script type="text/javascript" src="_static/bootstrap-scrollspy.js"></script>
|
|
<link rel="top" title="Ansible - SSH-Based Configuration Management & Deployment" href="index.html" />
|
|
<link rel="next" title="YAML Syntax" href="YAMLSyntax.html" />
|
|
<link rel="prev" title="Command Line Examples" href="examples.html" />
|
|
<script type="text/javascript">
|
|
(function () {
|
|
/**
|
|
* Patch TOC list.
|
|
*
|
|
* Will mutate the underlying span to have a correct ul for nav.
|
|
*
|
|
* @param $span: Span containing nested UL's to mutate.
|
|
* @param minLevel: Starting level for nested lists. (1: global, 2: local).
|
|
*/
|
|
var patchToc = function ($span, minLevel) {
|
|
var $tocList = $("<ul/>").attr('class', "dropdown-menu"),
|
|
findA;
|
|
|
|
// Find all a "internal" tags, traversing recursively.
|
|
findA = function ($elem, level) {
|
|
var level = level || 0,
|
|
$items = $elem.find("> li > a.internal, > ul, > li > ul");
|
|
|
|
// Iterate everything in order.
|
|
$items.each(function (index, item) {
|
|
var $item = $(item),
|
|
tag = item.tagName.toLowerCase(),
|
|
pad = 10 + ((level - minLevel) * 10);
|
|
|
|
if (tag === 'a' && level >= minLevel) {
|
|
// Add to existing padding.
|
|
$item.css('padding-left', pad + "px");
|
|
// Add list element.
|
|
$tocList.append($("<li/>").append($item));
|
|
} else if (tag === 'ul') {
|
|
// Recurse.
|
|
findA($item, level + 1);
|
|
}
|
|
});
|
|
};
|
|
|
|
// Start construction and return.
|
|
findA($span);
|
|
|
|
// Wipe out old list and patch in new one.
|
|
return $span.empty("ul").append($tocList);
|
|
};
|
|
|
|
$(document).ready(function () {
|
|
// Patch the global and local TOC's to be bootstrap-compliant.
|
|
patchToc($("span.globaltoc"), 1);
|
|
patchToc($("span.localtoc"), 2);
|
|
|
|
// Activate.
|
|
$('#topbar').dropdown();
|
|
});
|
|
}());
|
|
</script>
|
|
<script type="text/javascript">
|
|
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-29861888-1']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type =
|
|
'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
|
|
'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0];
|
|
s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
|
|
</script>
|
|
|
|
</head>
|
|
<body>
|
|
<div class="topbar" data-scrollspy="scrollspy" >
|
|
<div class="topbar-inner">
|
|
<div class="container">
|
|
<a class="brand" href="index.html">Ansible</a>
|
|
<ul class="nav">
|
|
|
|
<li class="dropdown" data-dropdown="dropdown">
|
|
<a href="index.html"
|
|
class="dropdown-toggle">Site</a>
|
|
<span class="globaltoc"><ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Downloads & Getting Started</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="patterns.html">The Inventory File, Patterns, and Groups</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples</a></li>
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="">Ansible Modules</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
|
|
</ul>
|
|
</span>
|
|
</li>
|
|
<li class="dropdown" data-dropdown="dropdown">
|
|
<a href="#"
|
|
class="dropdown-toggle">Page</a>
|
|
<span class="localtoc"><ul>
|
|
<li><a class="reference internal" href="#">Ansible Modules</a><ul>
|
|
<li><a class="reference internal" href="#command">command</a></li>
|
|
<li><a class="reference internal" href="#copy">copy</a></li>
|
|
<li><a class="reference internal" href="#facter">facter</a></li>
|
|
<li><a class="reference internal" href="#git">git</a></li>
|
|
<li><a class="reference internal" href="#ohai">ohai</a></li>
|
|
<li><a class="reference internal" href="#ping">ping</a></li>
|
|
<li><a class="reference internal" href="#service">service</a></li>
|
|
<li><a class="reference internal" href="#setup">setup</a></li>
|
|
<li><a class="reference internal" href="#shell">shell</a></li>
|
|
<li><a class="reference internal" href="#template">template</a></li>
|
|
<li><a class="reference internal" href="#yum">yum</a></li>
|
|
<li><a class="reference internal" href="#writing-your-own-modules">Writing your own modules</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</span>
|
|
</li>
|
|
|
|
|
|
|
|
<li><a href="examples.html"
|
|
title="previous chapter">« Command Line Examples</a></li>
|
|
<li><a href="YAMLSyntax.html"
|
|
title="next chapter">YAML Syntax »</a></li>
|
|
|
|
|
|
|
|
|
|
</ul>
|
|
<ul class="nav secondary-nav">
|
|
|
|
|
|
<form class="pull-left" action="search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<a href="https://github.com/ansible/ansible"><img
|
|
style="position: absolute; top: 40px; right: 0; border: 0;"
|
|
src="https://a248.e.akamai.net/assets.github.com/img/71eeaab9d563c2b3c590319b398dd35683265e85/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677261795f3664366436642e706e67"
|
|
alt="Fork me on GitHub"
|
|
alt="Fork me on GitHub"></a>
|
|
<div class="container">
|
|
|
|
<div class="section" id="ansible-modules">
|
|
<h1>Ansible Modules<a class="headerlink" href="#ansible-modules" title="Permalink to this headline">¶</a></h1>
|
|
<p>Ansible ships with a number of modules that can be executed directly
|
|
on remote hosts or through ansible playbooks.</p>
|
|
<div class="admonition-see-also admonition seealso">
|
|
<p class="first admonition-title">See also</p>
|
|
<dl class="last docutils">
|
|
<dt><a class="reference internal" href="examples.html"><em>Command Line Examples</em></a></dt>
|
|
<dd>Examples of using modules in /usr/bin/ansible</dd>
|
|
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
|
|
<dd>Examples of using modules with /usr/bin/ansible-playbook</dd>
|
|
<dt><a class="reference internal" href="api.html"><em>Using the Python API</em></a></dt>
|
|
<dd>Examples of using modules with the Python API</dd>
|
|
</dl>
|
|
</div>
|
|
<p>Nearly all modules take <tt class="docutils literal"><span class="pre">key=value</span></tt> parameters, space delimited. Some modules take
|
|
no parameters, and the command/shell modules simply take the string
|
|
of the command you want to run.</p>
|
|
<p>All modules return JSON format data, though if you are using the
|
|
command line or playbooks, you don’t really need to know much about
|
|
that.</p>
|
|
<p>Most modules other than command are idempotent, meaning they will seek
|
|
to avoid changes unless a change needs to be made. When using ansible
|
|
playbooks, these modules can trigger change events. Unless otherwise
|
|
noted, all modules support change hooks.</p>
|
|
<p>Stock modules:</p>
|
|
<div class="section" id="command">
|
|
<span id="id1"></span><h2>command<a class="headerlink" href="#command" title="Permalink to this headline">¶</a></h2>
|
|
<p>The command module takes the command name followed by a list of
|
|
arguments, space delimited.</p>
|
|
<p>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>
|
|
<p>Example usage:</p>
|
|
<div class="highlight-python"><pre>/sbin/shutdown -t now</pre>
|
|
</div>
|
|
<p>The given command will be executed on all selected nodes. It will not
|
|
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>This module does not support change hooks and returns the return code
|
|
from the program as well as timing information about how long the
|
|
command was running for.</p>
|
|
</div>
|
|
<div class="section" id="copy">
|
|
<span id="id2"></span><h2>copy<a class="headerlink" href="#copy" title="Permalink to this headline">¶</a></h2>
|
|
<p>The copy module moves a file on the local box to remote locations.</p>
|
|
<p><em>src</em>:</p>
|
|
<ul class="simple">
|
|
<li>Local path to a file to copy to the remote server. This can be an
|
|
absolute or relative path.</li>
|
|
</ul>
|
|
<p><em>dest</em>:</p>
|
|
<ul class="simple">
|
|
<li>Remote absolute path where the file should end up.</li>
|
|
</ul>
|
|
<p>This module also returns md5sum information about the resultant file.</p>
|
|
</div>
|
|
<div class="section" id="facter">
|
|
<span id="id3"></span><h2>facter<a class="headerlink" href="#facter" title="Permalink to this headline">¶</a></h2>
|
|
<p>Runs the discovery program ‘facter’ on the remote system, returning
|
|
JSON data that can be useful for inventory purposes.</p>
|
|
<p>Requires that ‘facter’ and ‘ruby-json’ be installed on the remote end.</p>
|
|
<p>This module is informative only - it takes no parameters & does not
|
|
support change hooks, nor does it make any changes on the system.
|
|
Playbooks do not actually use this module, they use the <a class="reference internal" href="#setup"><em>setup</em></a>
|
|
module behind the scenes.</p>
|
|
</div>
|
|
<div class="section" id="git">
|
|
<h2>git<a class="headerlink" href="#git" title="Permalink to this headline">¶</a></h2>
|
|
<p>Deploys software (or files) from git checkouts.</p>
|
|
<p><em>repo</em>:</p>
|
|
<ul class="simple">
|
|
<li>git or http protocol address of the repo to checkout.</li>
|
|
</ul>
|
|
<p><em>dest</em>:</p>
|
|
<ul class="simple">
|
|
<li>Where to check it out, an absolute directory path.</li>
|
|
</ul>
|
|
<p><em>version</em>:</p>
|
|
<ul class="simple">
|
|
<li>What version to check out – either the git SHA, the literal string
|
|
<tt class="docutils literal"><span class="pre">HEAD</span></tt>, or a tag name.</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="ohai">
|
|
<h2>ohai<a class="headerlink" href="#ohai" title="Permalink to this headline">¶</a></h2>
|
|
<p>Similar to the <a class="reference internal" href="#facter"><em>facter</em></a> module, this returns JSON inventory data.
|
|
Ohai data is a bit more verbose and nested than facter.</p>
|
|
<p>Requires that ‘ohai’ be installed on the remote end.</p>
|
|
<p>This module is information only - it takes no parameters & does not
|
|
support change hooks, nor does it make any changes on the system.</p>
|
|
<p>Playbooks should not call the ohai module, playbooks call the
|
|
<a class="reference internal" href="#setup"><em>setup</em></a> module behind the scenes instead.</p>
|
|
</div>
|
|
<div class="section" id="ping">
|
|
<h2>ping<a class="headerlink" href="#ping" title="Permalink to this headline">¶</a></h2>
|
|
<p>A trivial test module, this module always returns the integer <tt class="docutils literal"><span class="pre">1</span></tt> on
|
|
successful contact.</p>
|
|
<p>This module does not support change hooks and is informative only - it
|
|
takes no parameters & does not support change hooks, nor does it make
|
|
any changes on the system.</p>
|
|
</div>
|
|
<div class="section" id="service">
|
|
<h2>service<a class="headerlink" href="#service" title="Permalink to this headline">¶</a></h2>
|
|
<p>Controls services on remote machines.</p>
|
|
<p><em>state</em>:</p>
|
|
<ul class="simple">
|
|
<li>Values are <tt class="docutils literal"><span class="pre">started</span></tt>, <tt class="docutils literal"><span class="pre">stopped</span></tt>, or <tt class="docutils literal"><span class="pre">restarted</span></tt>.
|
|
Started/stopped are idempotent actions that will not run commands
|
|
unless necessary. <tt class="docutils literal"><span class="pre">restarted</span></tt> will always bounce the service.</li>
|
|
</ul>
|
|
<p><em>name</em>:</p>
|
|
<ul class="simple">
|
|
<li>The name of the service.</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="setup">
|
|
<span id="id4"></span><h2>setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2>
|
|
<p>Writes a JSON file containing key/value data, for use in templating.
|
|
Call this once before using the <a class="reference internal" href="#template"><em>template</em></a> module. Playbooks
|
|
will execute this module automatically as the first step in each play
|
|
using the variables section, so it is unnecessary to make explicit
|
|
calls to setup within a playbook.</p>
|
|
<p>If facter or ohai are installed, variables from these programs will
|
|
also be snapshotted into the JSON file for usage in templating. These
|
|
variables are prefixed with <tt class="docutils literal"><span class="pre">facter_</span></tt> and <tt class="docutils literal"><span class="pre">ohai_</span></tt> so it’s easy to
|
|
tell their source. All variables are then bubbled up to the caller.</p>
|
|
<p><em>anything</em>:</p>
|
|
<blockquote>
|
|
<div><ul class="simple">
|
|
<li>Any other parameters can be named basically anything, and set a
|
|
<tt class="docutils literal"><span class="pre">key=value</span></tt> pair in the JSON file for use in templating.</li>
|
|
</ul>
|
|
</div></blockquote>
|
|
</div>
|
|
<div class="section" id="shell">
|
|
<span id="id5"></span><h2>shell<a class="headerlink" href="#shell" title="Permalink to this headline">¶</a></h2>
|
|
<p>The shell module takes the command name followed by a list of
|
|
arguments, space delimited. It is almost exactly like the command module
|
|
but runs the command through the shell rather than directly.</p>
|
|
<p>Example usage:</p>
|
|
<div class="highlight-python"><pre>find . | grep *.txt</pre>
|
|
</div>
|
|
<p>The given command will be executed on all selected nodes.</p>
|
|
<p>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>
|
|
<p>This module does not support change hooks and returns the return code
|
|
from the program as well as timing information about how long the
|
|
command was running for.</p>
|
|
</div>
|
|
<div class="section" id="template">
|
|
<span id="id6"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline">¶</a></h2>
|
|
<p>Templates a file out to a remote server. Call the <a class="reference internal" href="#setup"><em>setup</em></a> module
|
|
prior to usage if you are not running from a playbook.</p>
|
|
<p><em>src</em>:</p>
|
|
<ul class="simple">
|
|
<li>Path of a Jinja2 formatted template on the local server. This can
|
|
be a relative or absolute path.</li>
|
|
</ul>
|
|
<p><em>dest</em>:</p>
|
|
<ul class="simple">
|
|
<li>Location to render the template on the remote server.</li>
|
|
</ul>
|
|
<p>This module also returns md5sum information about the resultant file.</p>
|
|
</div>
|
|
<div class="section" id="yum">
|
|
<span id="id7"></span><h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline">¶</a></h2>
|
|
<p>Will install, upgrade, remove, and list packages with the yum package manager.</p>
|
|
<p><em>pkg</em>:</p>
|
|
<ul class="simple">
|
|
<li>A package name or package specifier with version, like name-1.0</li>
|
|
</ul>
|
|
<p><em>state</em>:</p>
|
|
<ul class="simple">
|
|
<li>Can be either ‘installed’, ‘latest’, or ‘removed’</li>
|
|
</ul>
|
|
<p><em>list</em>:</p>
|
|
<ul class="simple">
|
|
<li>When ‘list’ is supplied instead of ‘state’, the yum module can list
|
|
various configuration attributes. Values include ‘installed’, ‘updates’,
|
|
‘available’, ‘repos’, or any package specifier.</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="writing-your-own-modules">
|
|
<h2>Writing your own modules<a class="headerlink" href="#writing-your-own-modules" title="Permalink to this headline">¶</a></h2>
|
|
<p>To write your own modules, simply follow the convention of those
|
|
already available in /usr/share/ansible. Modules must return JSON but
|
|
can be written in any language. Modules should return hashes, but
|
|
hashes can be nested.</p>
|
|
<p>To support change hooks, modules should return hashes with a changed:
|
|
True/False element at the top level:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="s">'changed'</span> <span class="p">:</span> <span class="bp">True</span><span class="p">,</span>
|
|
<span class="s">'something'</span> <span class="p">:</span> <span class="mi">42</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Modules can also choose to indicate a failure scenario by returning a
|
|
top level <tt class="docutils literal"><span class="pre">failure</span></tt> element with a True value, and a <tt class="docutils literal"><span class="pre">msg</span></tt> element
|
|
describing the nature of the failure. Other return values are up to
|
|
the module:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
|
|
<span class="s">'failure'</span> <span class="p">:</span> <span class="bp">True</span><span class="p">,</span>
|
|
<span class="s">'msg'</span> <span class="p">:</span> <span class="s">"here is what happened..."</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>When shipping modules, drop them in /usr/share/ansible, or specify the
|
|
module path to the command line tool or API. It is easy to test
|
|
modules by running them directly on the command line, passing them
|
|
arguments just like they would be passed with ansible.</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
<footer class="footer">
|
|
<div class="container">
|
|
<p class="pull-right"><a href="#">Back to top</a></p>
|
|
<p>
|
|
© Copyright 2012 Michael DeHaan.<br/>
|
|
Last updated on Mar 14, 2012.<br/>
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
|
|
</p>
|
|
</div>
|
|
</footer>
|
|
</body>
|
|
</html> |