mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
266 lines
No EOL
13 KiB
HTML
266 lines
No EOL
13 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 v0.0.1 documentation</title>
|
|
<link rel="stylesheet" href="_static/default.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: '',
|
|
VERSION: '0.0.1',
|
|
COLLAPSE_INDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</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>
|
|
<link rel="top" title="Ansible v0.0.1 documentation" href="index.html" />
|
|
<link rel="next" title="YAML Format" href="YAMLScripts.html" />
|
|
<link rel="prev" title="Command Line Examples" href="examples.html" />
|
|
</head>
|
|
<body>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
accesskey="I">index</a></li>
|
|
<li class="right" >
|
|
<a href="YAMLScripts.html" title="YAML Format"
|
|
accesskey="N">next</a> |</li>
|
|
<li class="right" >
|
|
<a href="examples.html" title="Command Line Examples"
|
|
accesskey="P">previous</a> |</li>
|
|
<li><a href="index.html">Ansible v0.0.1 documentation</a> »</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="document">
|
|
<div class="documentwrapper">
|
|
<div class="bodywrapper">
|
|
<div class="body">
|
|
|
|
<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: Ansible for Deployment, Configuration Management, and Orchestration</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 key=value parameters. Some modules take no parameters, and the command
|
|
module just takes arguments for the command you want to run.</p>
|
|
<p>All modules return JSON format data, thoug 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">
|
|
<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.
|
|
This is the only module that does not use key=value style parameters.</p>
|
|
<p>Example usage:</p>
|
|
<div class="highlight-python"><pre>/sbin/shutdown -t now</pre>
|
|
</div>
|
|
<p>The given shell command will be executed on all selected nodes.</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">
|
|
<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>
|
|
<p>Local path to a file to copy to the remote server. This can be an absolute or relative path.</p>
|
|
<p><em>dest</em>:</p>
|
|
<p>Remote absolute path where the file should end up.</p>
|
|
<p>This module also returns md5sum information about the resultant file.</p>
|
|
</div>
|
|
<div class="section" id="facter">
|
|
<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 ‘setup’ 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>
|
|
<p>git or http protocol address of the repo to checkout</p>
|
|
<p><em>dest</em>:</p>
|
|
<p>where to check it out, an absolute directory path</p>
|
|
<p><em>version</em>:</p>
|
|
<p>what version to check out – either the git SHA, the literal string ‘HEAD’, or a tag name</p>
|
|
</div>
|
|
<div class="section" id="ohai">
|
|
<h2>ohai<a class="headerlink" href="#ohai" title="Permalink to this headline">¶</a></h2>
|
|
<p>Similar to the facter 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 ‘setup’
|
|
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 ‘1’ 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>
|
|
<p>Values are ‘started’, ‘stopped’, or ‘restarted’. Started/stopped
|
|
are idempotent actions that will not run commands unless neccessary.
|
|
‘restarted’ will always bounce the service</p>
|
|
<p><em>name</em></p>
|
|
<p>The name of the service</p>
|
|
</div>
|
|
<div class="section" id="setup">
|
|
<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 template modules. Playbooks will
|
|
execute this module automatically as the first step in each play using
|
|
the variables section, so it is unneccessary 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 ‘<a class="reference internal" href="#facter">facter</a>‘ and ‘<a class="reference internal" href="#ohai">ohai</a>” so it’s easy to tell their source.
|
|
All variables are then bubbled up to the caller.</p>
|
|
<p><em>anything</em></p>
|
|
<p>any other parameters can be named basically anything, and set a key=value
|
|
pair in the JSON file for use in templating.</p>
|
|
</div>
|
|
<div class="section" id="template">
|
|
<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 setup module prior to usage.</p>
|
|
<p><em>src</em></p>
|
|
<p>path of a Jinja2 formatted template on the local server. This can be a relative
|
|
or absolute path.</p>
|
|
<p><em>dest</em></p>
|
|
<p>location to render the template on the remote server</p>
|
|
<p>This module also returns md5sum information about the resultant file.</p>
|
|
</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 ‘failure’
|
|
element with a True value, and a ‘msg’ element describing the nature of the failure.
|
|
Other return values are up to the module.</p>
|
|
<blockquote>
|
|
<div><dl class="docutils">
|
|
<dt>{</dt>
|
|
<dd>‘failure’ : True,
|
|
‘msg’ : “here is what happened...”</dd>
|
|
</dl>
|
|
<p>}</p>
|
|
</div></blockquote>
|
|
<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>
|
|
</div>
|
|
</div>
|
|
<div class="sphinxsidebar">
|
|
<div class="sphinxsidebarwrapper">
|
|
<h3><a href="index.html">Table Of Contents</a></h3>
|
|
<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="#template">template</a></li>
|
|
<li><a class="reference internal" href="#writing-your-own-modules">Writing your own modules</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Previous topic</h4>
|
|
<p class="topless"><a href="examples.html"
|
|
title="previous chapter">Command Line Examples</a></p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless"><a href="YAMLScripts.html"
|
|
title="next chapter">YAML Format</a></p>
|
|
<h3>This Page</h3>
|
|
<ul class="this-page-menu">
|
|
<li><a href="_sources/modules.txt"
|
|
rel="nofollow">Show Source</a></li>
|
|
</ul>
|
|
<div id="searchbox" style="display: none">
|
|
<h3>Quick search</h3>
|
|
<form class="search" action="search.html" method="get">
|
|
<input type="text" name="q" />
|
|
<input type="submit" value="Go" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
<p class="searchtip" style="font-size: 90%">
|
|
Enter search terms or a module, class or function name.
|
|
</p>
|
|
</div>
|
|
<script type="text/javascript">$('#searchbox').show(0);</script>
|
|
</div>
|
|
</div>
|
|
<div class="clearer"></div>
|
|
</div>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
>index</a></li>
|
|
<li class="right" >
|
|
<a href="YAMLScripts.html" title="YAML Format"
|
|
>next</a> |</li>
|
|
<li class="right" >
|
|
<a href="examples.html" title="Command Line Examples"
|
|
>previous</a> |</li>
|
|
<li><a href="index.html">Ansible v0.0.1 documentation</a> »</li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer">
|
|
© Copyright 2012 Michael DeHaan.
|
|
Last updated on Mar 09, 2012.
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.
|
|
</div>
|
|
</body>
|
|
</html> |