mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-07-25 22:30:22 -07:00
Module docs cleanup + rebuild
This commit is contained in:
parent
5d5231c4d0
commit
30f42b9735
3 changed files with 126 additions and 60 deletions
113
modules.html
113
modules.html
|
@ -226,10 +226,9 @@ command/shell modules simply take the string of the command you want to run.</p>
|
||||||
command line or playbooks, you don’t really need to know much about
|
command line or playbooks, you don’t really need to know much about
|
||||||
that. If you’re writing your own module, you care, and this means you do
|
that. If you’re writing your own module, you care, and this means you do
|
||||||
not have to write modules in any particular language – you get to choose.</p>
|
not have to write modules in any particular language – you get to choose.</p>
|
||||||
<p>Most modules other than command are <cite>idempotent</cite>, meaning they will seek
|
<p>Modules are <cite>idempotent</cite>, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible
|
||||||
to avoid changes to the system unless a change needs to be made. When using Ansible
|
playbooks, these modules can trigger ‘change events’ in the form of notifying ‘handlers’
|
||||||
playbooks, these modules can trigger ‘change events’. Unless otherwise
|
to run additional tasks.</p>
|
||||||
noted, any given module does support change hooks.</p>
|
|
||||||
<p>Let’s see what’s available in the Ansible module library, out of the box:</p>
|
<p>Let’s see what’s available in the Ansible module library, out of the box:</p>
|
||||||
<div class="section" id="apt">
|
<div class="section" id="apt">
|
||||||
<span id="id1"></span><h2>apt<a class="headerlink" href="#apt" title="Permalink to this headline">¶</a></h2>
|
<span id="id1"></span><h2>apt<a class="headerlink" href="#apt" title="Permalink to this headline">¶</a></h2>
|
||||||
|
@ -384,24 +383,52 @@ together to produce a destination file. Files are assembled in string sorting o
|
||||||
<span id="id4"></span><h2>command<a class="headerlink" href="#command" title="Permalink to this headline">¶</a></h2>
|
<span id="id4"></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
|
<p>The command module takes the command name followed by a list of
|
||||||
arguments, space delimited.</p>
|
arguments, space delimited.</p>
|
||||||
<p>If you want to run a command through the shell (say you are using
|
<table border="1" class="docutils">
|
||||||
‘<’, ‘>’, ‘|’, etc), you actually want the ‘shell’ module instead.
|
<colgroup>
|
||||||
The ‘command’ module is much more secure as it’s not affected by the user’s environment.</p>
|
<col width="17%" />
|
||||||
|
<col width="9%" />
|
||||||
|
<col width="8%" />
|
||||||
|
<col width="66%" />
|
||||||
|
</colgroup>
|
||||||
|
<thead valign="bottom">
|
||||||
|
<tr><th class="head">parameter</th>
|
||||||
|
<th class="head">required</th>
|
||||||
|
<th class="head">default</th>
|
||||||
|
<th class="head">comments</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody valign="top">
|
||||||
|
<tr><td>(free form)</td>
|
||||||
|
<td>N/A</td>
|
||||||
|
<td>N/A</td>
|
||||||
|
<td>the command module takes a free form command to run</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td>creates</td>
|
||||||
|
<td>no</td>
|
||||||
|
<td> </td>
|
||||||
|
<td>a filename, when it already exists, this step will NOT be run</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td>chdir</td>
|
||||||
|
<td>no</td>
|
||||||
|
<td> </td>
|
||||||
|
<td>cd into this directory before running the command (0.6 and later)</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
<p>The given command will be executed on all selected nodes. It will not
|
<p>The given command will be executed on all selected nodes. It will not
|
||||||
be processed through the shell, so variables like “$HOME” and
|
be processed through the shell, so variables like “$HOME” and
|
||||||
operations like “<”, “>”, “|”, and “&” will not work. As such, all
|
operations like “<”, “>”, “|”, and “&” will not work. As such, all
|
||||||
paths to commands must be fully qualified.</p>
|
paths to commands must be fully qualified.</p>
|
||||||
<p>This module does not support change hooks and returns the return code
|
<p>NOTE:: If you want to run a command through the shell (say you are using
|
||||||
from the program as well as timing information about how long the
|
‘<’, ‘>’, ‘|’, etc), you actually want the ‘shell’ module instead.
|
||||||
command was running.</p>
|
The ‘command’ module is much more secure as it’s not affected by the user’s environment.</p>
|
||||||
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
<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 class="highlight-python"><pre>command /sbin/shutdown -t now</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>If you only want to run a command if a certain file does not exist, you can do the
|
<p>creates and chdir can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, you can do the following:</p>
|
||||||
following:</p>
|
|
||||||
<div class="highlight-python"><pre>command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database</pre>
|
<div class="highlight-python"><pre>command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database</pre>
|
||||||
</div>
|
</div>
|
||||||
<p>The <cite>creates=</cite> option will not be passed to the executable.</p>
|
<p>The <cite>creates=</cite> and <cite>chdir</cite> options will not be passed to the actual executable.</p>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="copy">
|
<div class="section" id="copy">
|
||||||
<span id="id5"></span><h2>copy<a class="headerlink" href="#copy" title="Permalink to this headline">¶</a></h2>
|
<span id="id5"></span><h2>copy<a class="headerlink" href="#copy" title="Permalink to this headline">¶</a></h2>
|
||||||
|
@ -441,7 +468,6 @@ relative.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>This module also returns md5sum and other information about the resultant file.</p>
|
|
||||||
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
||||||
<div class="highlight-python"><pre>copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644</pre>
|
<div class="highlight-python"><pre>copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644</pre>
|
||||||
</div>
|
</div>
|
||||||
|
@ -451,10 +477,11 @@ relative.</td>
|
||||||
<p>Runs the discovery program ‘facter’ on the remote system, returning
|
<p>Runs the discovery program ‘facter’ on the remote system, returning
|
||||||
JSON data that can be useful for inventory purposes.</p>
|
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>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
|
<p>Playbooks do not actually use this module, they use the <a class="reference internal" href="#setup"><em>setup</em></a>
|
||||||
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>
|
module behind the scenes.</p>
|
||||||
|
<p>Example from /usr/bin/ansible:</p>
|
||||||
|
<div class="highlight-python"><pre>ansible foo.example.org -m ohai</pre>
|
||||||
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="fetch">
|
<div class="section" id="fetch">
|
||||||
<span id="id7"></span><h2>fetch<a class="headerlink" href="#fetch" title="Permalink to this headline">¶</a></h2>
|
<span id="id7"></span><h2>fetch<a class="headerlink" href="#fetch" title="Permalink to this headline">¶</a></h2>
|
||||||
|
@ -922,18 +949,19 @@ configured in fstab. ‘absent’, and ‘present’ only deal
|
||||||
<p>Similar to the <a class="reference internal" href="#facter"><em>facter</em></a> module, this returns JSON inventory data.
|
<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>
|
Ohai data is a bit more verbose and nested than facter.</p>
|
||||||
<p>Requires that ‘ohai’ be installed on the remote end.</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
|
<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>
|
<a class="reference internal" href="#setup"><em>setup</em></a> module behind the scenes instead.</p>
|
||||||
|
<p>Example:</p>
|
||||||
|
<div class="highlight-python"><pre>ansible foo.example.org -m ohai</pre>
|
||||||
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="ping">
|
<div class="section" id="ping">
|
||||||
<span id="id15"></span><h2>ping<a class="headerlink" href="#ping" title="Permalink to this headline">¶</a></h2>
|
<span id="id15"></span><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
|
<p>A trivial test module, this module always returns ‘pong’ on
|
||||||
successful contact.</p>
|
successful contact. It does not make sense in playbooks, but is useful
|
||||||
<p>This module does not support change hooks and is informative only - it
|
from /usr/bin/ansible:</p>
|
||||||
takes no parameters & does not support change hooks, nor does it make
|
<div class="highlight-python"><pre>ansible webservers -m ping</pre>
|
||||||
any changes on the system.</p>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="postgresql-db">
|
<div class="section" id="postgresql-db">
|
||||||
<h2>postgresql_db<a class="headerlink" href="#postgresql-db" title="Permalink to this headline">¶</a></h2>
|
<h2>postgresql_db<a class="headerlink" href="#postgresql-db" title="Permalink to this headline">¶</a></h2>
|
||||||
|
@ -1206,15 +1234,44 @@ on your remote systems.</p>
|
||||||
<p>The shell module takes the command name followed by a list of
|
<p>The shell module takes the command name followed by a list of
|
||||||
arguments, space delimited. It is almost exactly like the command module
|
arguments, space delimited. It is almost exactly like the command module
|
||||||
but runs the command through the user’s configured shell on the remote node.</p>
|
but runs the command through the user’s configured shell on the remote node.</p>
|
||||||
|
<table border="1" class="docutils">
|
||||||
|
<colgroup>
|
||||||
|
<col width="17%" />
|
||||||
|
<col width="9%" />
|
||||||
|
<col width="8%" />
|
||||||
|
<col width="66%" />
|
||||||
|
</colgroup>
|
||||||
|
<thead valign="bottom">
|
||||||
|
<tr><th class="head">parameter</th>
|
||||||
|
<th class="head">required</th>
|
||||||
|
<th class="head">default</th>
|
||||||
|
<th class="head">comments</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody valign="top">
|
||||||
|
<tr><td>(free form)</td>
|
||||||
|
<td>N/A</td>
|
||||||
|
<td>N/A</td>
|
||||||
|
<td>the command module takes a free form command to run</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td>creates</td>
|
||||||
|
<td>no</td>
|
||||||
|
<td> </td>
|
||||||
|
<td>a filename, when it already exists, this step will NOT be run</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td>chdir</td>
|
||||||
|
<td>no</td>
|
||||||
|
<td> </td>
|
||||||
|
<td>cd into this directory before running the command (0.6 and later)</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
<p>The given command will be executed on all selected nodes.</p>
|
<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
|
<p>NOTE:: If you want to execute a command securely and predicably, it may
|
||||||
be better to use the ‘command’ module instead. Best practices
|
be better to use the ‘command’ module instead. Best practices
|
||||||
when writing playbooks will follow the trend of using ‘command’
|
when writing playbooks will follow the trend of using ‘command’
|
||||||
unless ‘shell’ is explicitly required. When running ad-hoc commands,
|
unless ‘shell’ is explicitly required. When running ad-hoc commands,
|
||||||
use your best judgement.</p>
|
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.</p>
|
|
||||||
<p>Example action from a playbook:</p>
|
<p>Example action from a playbook:</p>
|
||||||
<div class="highlight-python"><pre>shell somescript.sh >> somelog.txt</pre>
|
<div class="highlight-python"><pre>shell somescript.sh >> somelog.txt</pre>
|
||||||
</div>
|
</div>
|
||||||
|
|
|
@ -27,10 +27,9 @@ command line or playbooks, you don't really need to know much about
|
||||||
that. If you're writing your own module, you care, and this means you do
|
that. If you're writing your own module, you care, and this means you do
|
||||||
not have to write modules in any particular language -- you get to choose.
|
not have to write modules in any particular language -- you get to choose.
|
||||||
|
|
||||||
Most modules other than command are `idempotent`, meaning they will seek
|
Modules are `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible
|
||||||
to avoid changes to the system unless a change needs to be made. When using Ansible
|
playbooks, these modules can trigger 'change events' in the form of notifying 'handlers'
|
||||||
playbooks, these modules can trigger 'change events'. Unless otherwise
|
to run additional tasks.
|
||||||
noted, any given module does support change hooks.
|
|
||||||
|
|
||||||
Let's see what's available in the Ansible module library, out of the box:
|
Let's see what's available in the Ansible module library, out of the box:
|
||||||
|
|
||||||
|
@ -127,29 +126,34 @@ command
|
||||||
The command module takes the command name followed by a list of
|
The command module takes the command name followed by a list of
|
||||||
arguments, space delimited.
|
arguments, space delimited.
|
||||||
|
|
||||||
If you want to run a command through the shell (say you are using
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||||
'<', '>', '|', etc), you actually want the 'shell' module instead.
|
| parameter | required | default | comments |
|
||||||
The 'command' module is much more secure as it's not affected by the user's environment.
|
+====================+==========+=========+============================================================================+
|
||||||
|
| (free form) | N/A | N/A | the command module takes a free form command to run |
|
||||||
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||||
|
| creates | no | | a filename, when it already exists, this step will NOT be run |
|
||||||
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||||
|
| chdir | no | | cd into this directory before running the command (0.6 and later) |
|
||||||
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||||
|
|
||||||
The given command will be executed on all selected nodes. It will not
|
The given command will be executed on all selected nodes. It will not
|
||||||
be processed through the shell, so variables like "$HOME" and
|
be processed through the shell, so variables like "$HOME" and
|
||||||
operations like "<", ">", "|", and "&" will not work. As such, all
|
operations like "<", ">", "|", and "&" will not work. As such, all
|
||||||
paths to commands must be fully qualified.
|
paths to commands must be fully qualified.
|
||||||
|
|
||||||
This module does not support change hooks and returns the return code
|
NOTE:: If you want to run a command through the shell (say you are using
|
||||||
from the program as well as timing information about how long the
|
'<', '>', '|', etc), you actually want the 'shell' module instead.
|
||||||
command was running.
|
The 'command' module is much more secure as it's not affected by the user's environment.
|
||||||
|
|
||||||
Example action from Ansible :doc:`playbooks`::
|
Example action from Ansible :doc:`playbooks`::
|
||||||
|
|
||||||
command /sbin/shutdown -t now
|
command /sbin/shutdown -t now
|
||||||
|
|
||||||
If you only want to run a command if a certain file does not exist, you can do the
|
creates and chdir can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, you can do the following::
|
||||||
following::
|
|
||||||
|
|
||||||
command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
|
command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
|
||||||
|
|
||||||
The `creates=` option will not be passed to the executable.
|
The `creates=` and `chdir` options will not be passed to the actual executable.
|
||||||
|
|
||||||
|
|
||||||
.. _copy:
|
.. _copy:
|
||||||
|
@ -172,8 +176,6 @@ module.
|
||||||
| OTHERS | | | All arguments the file module takes are also supported |
|
| OTHERS | | | All arguments the file module takes are also supported |
|
||||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||||
|
|
||||||
This module also returns md5sum and other information about the resultant file.
|
|
||||||
|
|
||||||
Example action from Ansible :doc:`playbooks`::
|
Example action from Ansible :doc:`playbooks`::
|
||||||
|
|
||||||
copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
|
copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
|
||||||
|
@ -189,10 +191,12 @@ JSON data that can be useful for inventory purposes.
|
||||||
|
|
||||||
Requires that 'facter' and 'ruby-json' be installed on the remote end.
|
Requires that 'facter' and 'ruby-json' be installed on the remote end.
|
||||||
|
|
||||||
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 :ref:`setup`
|
Playbooks do not actually use this module, they use the :ref:`setup`
|
||||||
module behind the scenes.
|
module behind the scenes.
|
||||||
|
|
||||||
|
Example from /usr/bin/ansible::
|
||||||
|
|
||||||
|
ansible foo.example.org -m ohai
|
||||||
|
|
||||||
.. _fetch:
|
.. _fetch:
|
||||||
|
|
||||||
|
@ -452,24 +456,23 @@ Ohai data is a bit more verbose and nested than facter.
|
||||||
|
|
||||||
Requires that 'ohai' be installed on the remote end.
|
Requires that 'ohai' be installed on the remote end.
|
||||||
|
|
||||||
This module is information only - it takes no parameters & does not
|
|
||||||
support change hooks, nor does it make any changes on the system.
|
|
||||||
|
|
||||||
Playbooks should not call the ohai module, playbooks call the
|
Playbooks should not call the ohai module, playbooks call the
|
||||||
:ref:`setup` module behind the scenes instead.
|
:ref:`setup` module behind the scenes instead.
|
||||||
|
|
||||||
|
Example::
|
||||||
|
|
||||||
|
ansible foo.example.org -m ohai
|
||||||
|
|
||||||
.. _ping:
|
.. _ping:
|
||||||
|
|
||||||
ping
|
ping
|
||||||
````
|
````
|
||||||
|
|
||||||
A trivial test module, this module always returns the integer ``1`` on
|
A trivial test module, this module always returns 'pong' on
|
||||||
successful contact.
|
successful contact. It does not make sense in playbooks, but is useful
|
||||||
|
from /usr/bin/ansible::
|
||||||
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.
|
|
||||||
|
|
||||||
|
ansible webservers -m ping
|
||||||
|
|
||||||
.. postgresql_db:
|
.. postgresql_db:
|
||||||
|
|
||||||
|
@ -697,18 +700,24 @@ The shell module takes the command name followed by a list of
|
||||||
arguments, space delimited. It is almost exactly like the command module
|
arguments, space delimited. It is almost exactly like the command module
|
||||||
but runs the command through the user's configured shell on the remote node.
|
but runs the command through the user's configured shell on the remote node.
|
||||||
|
|
||||||
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||||
|
| parameter | required | default | comments |
|
||||||
|
+====================+==========+=========+============================================================================+
|
||||||
|
| (free form) | N/A | N/A | the command module takes a free form command to run |
|
||||||
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||||
|
| creates | no | | a filename, when it already exists, this step will NOT be run |
|
||||||
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||||
|
| chdir | no | | cd into this directory before running the command (0.6 and later) |
|
||||||
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||||
|
|
||||||
The given command will be executed on all selected nodes.
|
The given command will be executed on all selected nodes.
|
||||||
|
|
||||||
If you want to execute a command securely and predicably, it may
|
NOTE:: If you want to execute a command securely and predicably, it may
|
||||||
be better to use the 'command' module instead. Best practices
|
be better to use the 'command' module instead. Best practices
|
||||||
when writing playbooks will follow the trend of using 'command'
|
when writing playbooks will follow the trend of using 'command'
|
||||||
unless 'shell' is explicitly required. When running ad-hoc commands,
|
unless 'shell' is explicitly required. When running ad-hoc commands,
|
||||||
use your best judgement.
|
use your best judgement.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Example action from a playbook::
|
Example action from a playbook::
|
||||||
|
|
||||||
shell somescript.sh >> somelog.txt
|
shell somescript.sh >> somelog.txt
|
||||||
|
|
File diff suppressed because one or more lines are too long
Loading…
Add table
Add a link
Reference in a new issue