ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-22 12:50:22 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Plugin doc update edits for #30490 (#30889)

Browse source 
* Edit pass 1 for #30490 - command line tools and developing plugins.

* Continuing edit pass for #30490. WIP

* Last round of copy edits for #30490.
This commit is contained in:
scottb 2017-09-25 15:37:33 -07:00 • committed by GitHub
commit 6c732bb670
13 changed files with 147 additions and 179 deletions
Download patch file Download diff file Expand all files Collapse all files

15
docs/docsite/rst/plugins/action.rst
View file

@ -1,18 +1,15 @@
Action Plugins
---------------
These plugins act in conjunction with :doc:`modules <../modules>` to execute the actions required by playbook tasks.
They mostly execute automatically in the background doing prerequisite work for the modules of the same to be able to execute.
Action plugins act in conjunction with :doc:`modules <../modules>` to execute the actions required by playbook tasks.
They usually execute automatically in the background doing prerequisite work before modules execute.
The 'normal' action plugin takes care of modules that do not already have an action plugin.
Enabling Vars Plugins
+++++++++++++++++++++
You can activate a custom action plugins by either dropping it into a ``action_plugins`` directory adjacent to your play or inside a role
or by putting it in one of the action plugin directory sources configured in :doc:`ansible.cfg <../config>`.
The 'normal' action plugin is used for modules that do not already have an action plugin.
Enabling Action Plugins
+++++++++++++++++++++++
You can enable a custom action plugin by either dropping it into the ``action_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the action plugin directory sources configured in :doc:`ansible.cfg <../config>`.
.. seealso::

17
docs/docsite/rst/plugins/cache.rst
View file

@ -4,11 +4,10 @@
Cache Plugins
-------------
This plugin implelents a backend caching mechanism for Ansible to store gathered facts or inventory source data
to avoid the cost of retrieving them from source.
Cache plugin implement a backend caching mechanism that allows Ansible to store gathered facts or inventory source data
without the performance hit of retrieving them from source.
The default plugin is the :doc:`memory <cache/memory>` plugin which will only cache the data for the current execution of Ansible.
Other plugins with persistent storage are available to allow caching the data across runs.
The default cache plugin is the :doc:`memory <cache/memory>` plugin, which only caches the data for the current execution of Ansible. Other plugins with persistent storage are available to allow caching the data across runs.
Enabling Cache Plugins
@ -16,7 +15,7 @@ Enabling Cache Plugins
Only one cache plugin can be active at a time.
You can enable in configuration, either via environment variable:
You can enable a cache plugin in the Ansible configuration, either via environment variable:
.. code-block:: shell
@ -29,14 +28,14 @@ or in the ``ansible.cfg`` file:
[defaults]
fact_caching=redis
You will also need to setup other settings specific to each plugin, you can check the individual plugin documenattion
or the ansible :doc:`configuration <../config>` for more details.
You will also need to configure other settings specific to each plugin. Consult the individual plugin documentation
or the Ansible :doc:`configuration <../config>` for more details.
Plugin List
+++++++++++
You can use ``ansible-doc -t cache -l`` to see the list of available plugins,
use ``ansible-doc -t cache <plugin name>`` to see specific documents and examples.
You can use ``ansible-doc -t cache -l`` to see the list of available plugins.
Use ``ansible-doc -t cache <plugin name>`` to see specific documentation and examples.
.. toctree:: :maxdepth: 1
:glob:

22
docs/docsite/rst/plugins/callback.rst
View file

@ -16,9 +16,7 @@ Example Callback Plugins
The :doc:`log_plays <callback/log_plays>` callback is an example of how to record playbook events to a log file,
and the :doc:`mail callback/mail` callback sends email on playbook failures.
The :doc:`osx_say <callback/oxs_say>` callback provided is particularly entertaining --
it will respond with computer synthesized speech on OS X in relation to playbook events,
and is guaranteed to entertain and/or annoy coworkers.
The :doc:`osx_say <callback/oxs_say>` callback responds with computer synthesized speech on OS X in relation to playbook events.
.. _enabling_callbacks:
@ -26,13 +24,11 @@ and is guaranteed to entertain and/or annoy coworkers.
Enabling Callback Plugins
++++++++++++++++++++++++++
You can activate a custom callback by either dropping it into a ``callback_plugins`` directory adjacent to your play or inside a role
or by putting it in one of the callback directory sources configured in :doc:`ansible.cfg <../config>`.
You can activate a custom callback by either dropping it into a ``callback_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the callback directory sources configured in :doc:`ansible.cfg <../config>`.
Plugins are loaded in alphanumeric order; for example, a plugin implemented in a file named `1_first.py` would run before a plugin file named `2_second.py`.
Plugins are loaded in alphanumeric order. For example, a plugin implemented in a file named `1_first.py` would run before a plugin file named `2_second.py`.
Most callbacks shipped with Ansible are disabled by default and need to be whitelisted in your :doc:`ansible.cfg <../config>` file in order to function.
For example:
Most callbacks shipped with Ansible are disabled by default and need to be whitelisted in your :doc:`ansible.cfg <../config>` file in order to function. For example:
.. code-block:: ini
@ -59,15 +55,15 @@ This only affects :doc:`../ansible-playbook` by default.
Managing AdHoc
``````````````
The :doc:`ansible <../ansible>` AdHoc command speifically uses a different callback plugin for stdout,
so there is an extra setting you need to enable it to use the stdout callback defined above, in :doc:`ansible.cfg <../config>`:
The :doc:`ansible <../ansible>` AdHoc command specifically uses a different callback plugin for stdout,
so there is an extra setting in :doc:`ansible.cfg <../config>` you need to add to use the stdout callback defined above:
.. code-block:: ini
[defaults]
bin_ansible_callbacks=True
or as an environment variable:
You can also set this as an environment variable:
.. code-block:: shell
@ -77,8 +73,8 @@ or as an environment variable:
Plugin List
+++++++++++
You can use ``ansible-doc -t callback -l`` to see the list of available plugins,
use ``ansible-doc -t callback <plugin name>`` to see specific documents and examples.
You can use ``ansible-doc -t callback -l`` to see the list of available plugins.
Use ``ansible-doc -t callback <plugin name>`` to see specific documents and examples.
.. toctree:: :maxdepth: 1

33
docs/docsite/rst/plugins/connection.rst
View file

@ -4,23 +4,21 @@
Connection Plugins
------------------
These plugins are in charge of enabling Ansible to connect to the target hosts so it can execute tasks on them.
Ansible ships we many connection plugins but only one can be used per host at a time.
Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time.
By default, the configuration uses a 'smart' value, which means Ansible will decide to use the 'ssh' or 'paramiko' (python version of ssh client)
depending on what it detects on your system capabilities, it normally chooses 'ssh' if OpenSSH supports ControlPersist.
By default, Ansible ships with several plugins. The most commonly used are the 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection types. All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.
The basics of these connection types are covered in the :doc:`../intro_getting_started` section.
The basics of these connection types are covered in the :doc:`../intro_getting_started` section.
.. contents:: Topics
.. _ssh_plugins:
The ssh Plugins
++++++++++++++++
ssh Plugins
+++++++++++
Since ssh is the default protocol used in system administration it is also the most used and prevalent in Ansible,
so much so that ssh options are included in the command line tools unlike other plugins, see :doc:`../ansible-playbook` for more details.
Because ssh is the default protocol used in system administration and the protocol most used in Ansible, ssh options are included in the command line tools. See :doc:`../ansible-playbook` for more details.
.. _using_connection_plugins:
@ -32,29 +30,30 @@ The transport can be changed via :doc:`configuration <../config>`, in the comman
in your play or by setting the a connection variable (:ref:`ansible_connection`), most often, in your inventory.
For example, for windows machines you might want o use the :doc:`winrm <connection/winrm>` plugin instead.
Most connection plugins can operate with a minimum configuration, by defaul they use the :ref:`inventory_hostname` and defaults to find the target host.
Each plugin documents it's configuration options and how to set, the following are 'connection variables' common to most:
Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory_hostname` and defaults to find the target host.
Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins:
:ref:ansible_host
The name of the host to connect to, if different from the :ref:`inventory_hostname`.
:ref:ansible_port
The ssh port number, for :doc:`ssh <connection/ssh>` and :doc:`paramiko <connection/paramiko>` it defaults to 22.
The ssh port number. For :doc:`ssh <connection/ssh>` and :doc:`paramiko <connection/paramiko>` the default value is 22.
:ref:ansible_user
The default user name to log in as, most plugins defaul to the 'current user running Ansible'
The default user name to use for log in. Most plugins default to the current user running Ansible.
Each plugin might also have a specific version that overrides the general one. i.e :ref:`ansible_ssh_host` for the :doc:`ssh <connection/ssh>` plugin.
Each plugin might also have a specific version of a variable that overrides the general version. For example, :ref:`ansible_ssh_host` for the :doc:`ssh <connection/ssh>` plugin.
Enabling Connection Plugins
+++++++++++++++++++++++++++
Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as dropping a custom plugin
You can extend Ansible to support other transports (such as SNMP or message bus) by dropping a custom plugin
into the ``connection_plugins`` directory.
Plugin List
+++++++++++
You can use ``ansible-doc -t connection -l`` to see the list of available plugins,
use ``ansible-doc -t connection <plugin name>`` to examine detailed documentation and examples.
You can use ``ansible-doc -t connection -l`` to see the list of available plugins.
Use ``ansible-doc -t connection <plugin name>`` to see detailed documentation and examples.
.. toctree:: :maxdepth: 1

13
docs/docsite/rst/plugins/inventory.rst
View file

@ -4,8 +4,7 @@
Inventory Plugins
-----------------
Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target it's tasks.
They control what happens when with ``-i /path/to/file`` and/or ``-i 'host1, host2`` when passed into Ansible (or from other configuration sources).
Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target tasks, either via the ``-i /path/to/file`` and/or ``-i 'host1, host2`` command line parameters or from other configuration sources.
.. _enabling_inventory_plugins:
@ -13,15 +12,15 @@ Enabling Inventory Plugins
++++++++++++++++++++++++++
Most inventory plugins shipped with Ansible are disabled by default and need to be whitelisted in your
:doc:`ansible.cfg <../config>` file in order to function. For example, this is how the default looks like:
:doc:`ansible.cfg <../config>` file in order to function. This is how the default whitelist looks in the
config file that ships with Ansible:
.. code-block:: ini
[inventory]
enable_plugins = host_list, script, yaml, ini
This list also establishes the order in which each plugin tries to parse an inventory source (in the case 2 plugins can use the same source).
Any plugins left out of the list will not be considered, so you can 'optimize' your inventory loading by minimizing it to what you actually use:
This list also establishes the order in which each plugin tries to parse an inventory source. Any plugins left out of the list will not be considered, so you can 'optimize' your inventory loading by minimizing it to what you actually use. For example:
.. code-block:: ini
@ -32,8 +31,8 @@ Any plugins left out of the list will not be considered, so you can 'optimize' y
Plugin List
+++++++++++
You can use ``ansible-doc -t inventory -l`` to see the list of available plugins,
use ``ansible-doc -t inventory <plugin name>`` to see specific documents and examples.
You can use ``ansible-doc -t inventory -l`` to see the list of available plugins.
Use ``ansible-doc -t inventory <plugin name>`` to see plugin-specific documentation and examples.
.. toctree:: :maxdepth: 1
:glob:

15
docs/docsite/rst/plugins/shell.rst
View file

@ -1,20 +1,15 @@
Shell Plugins
-------------
These plugins work behind the scenes making sure the basic commands Ansible runs,
in order to be able to execute a task's action,
are properly formated to work with the target machine.
You normally don't have to wory about these plugins at all,
unless you have a restricted or exotic setup,
in which the default ``/bin/sh`` is not a POSIX compatible shell or not availble for execution.
Shell plugins work transparently to ensure that the basic commands Ansible runs are properly formated to work with the target machine.
Enabling Shell Plugins
++++++++++++++++++++++
You probably never need to do this, but aside from the defaul configuration settings in :doc:`../config`,
you can use a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use,
you will also want to update the :ref:`ansible_executable` to match.
.. warning:: These plugins should not be reconfigured unless you have a restricted or exotic setup
in which the default ``/bin/sh`` is not a POSIX compatible shell or not availble for execution.
In addition to modifying the default configuration settings in :doc:`../config`, you can use a 'connection variable' :ref:`ansible_shell_type` to select a shell plugin, and update the :ref:`ansible_executable` to match.
.. seealso::

16
docs/docsite/rst/plugins/strategy.rst
View file

@ -4,14 +4,14 @@
Strategy Plugins
----------------
Strategy plugins control the flow of play execution, they handle task and host scheduleing.
Strategy plugins control the flow of play execution by handling task and host scheduling.
Enabling Cache Plugins
++++++++++++++++++++++
Enabling Strategy Plugins
+++++++++++++++++++++++++
Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or ansible run.
The default is the :doc:`linear <strategy/linear>` plugin, you can change this default via :doc:`configuration <../config>`:
Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or Ansible run.
The default is the :doc:`linear <strategy/linear>` plugin. You can change this default in Ansible :doc:`configuration <../config>` using an environment variable:
.. code-block:: shell
@ -24,7 +24,7 @@ or in the `ansible.cfg` file:
[defaults]
strategy=linear
Or you can just speicfy the plugin in the play via the :ref:`strategy` keyword::
You can also specify the strategy plugin in the play via the :ref:`strategy` keyword::
- hosts: all
strategy: debug
@ -42,8 +42,8 @@ Or you can just speicfy the plugin in the play via the :ref:`strategy` keyword::
Plugin List
+++++++++++
You can use ``ansible-doc -t strategy -l`` to see the list of available plugins,
use ``ansible-doc -t strategy <plugin name>`` to see specific documents and examples.
You can use ``ansible-doc -t strategy -l`` to see the list of available plugins.
Use ``ansible-doc -t strategy <plugin name>`` to see plugin-specific specific documentation and examples.
.. toctree:: :maxdepth: 1

14
docs/docsite/rst/plugins/vars.rst
View file

@ -4,21 +4,23 @@
Vars Plugins
------------
They inject additional variable data into ansible runs that did not come from an inventory source, playbook, or command line.
The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible provides reading variables from :ref:`host_vars` and :ref:`group_vars`.
Vars plugins inject additional variable data into Ansible runs that did not come from an inventory source, playbook, or command line. Playbook constructs like 'host_vars' and 'group_vars' work using vars plugins.
Vars plugins were partially implented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4.
The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_vars` and :ref:`group_vars`.
Enabling Vars Plugins
+++++++++++++++++++++
You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play or inside a role
or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`.
You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`.
Plugin Lists
++++++++++++
You can use ``ansible-doc -t vars -l`` to see the list of available plugins,
use ``ansible-doc -t vars <plugin name>`` to see specific documents and examples.
You can use ``ansible-doc -t vars -l`` to see the list of available plugins.
Use ``ansible-doc -t vars <plugin name>`` to see specific plugin-specific documentation and examples.
.. toctree:: :maxdepth: 1