cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

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
parent 5175bd8ebd
commit 6c732bb670
13 changed files with 147 additions and 179 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/docsite/rst/command_line_tools.rst
View file

@ -2,7 +2,7 @@ Command Line Tools
==================
Most users are familiar with `ansible` and `ansible-playbook`, but those are not the only utilities Ansible provides.
Below you have the complate list, each page has the detailed swtiches and options that each tool supports and a short description of their purpose.
Below you is a complete list of Ansible utilities. Each page contains a description of the utility and a listing of supported parameters.
.. toctree:: :maxdepth: 1
:glob:

124
docs/docsite/rst/dev_guide/developing_plugins.rst
View file

@ -3,22 +3,19 @@ Developing Plugins
.. contents:: Topics
Plugins are pieces of code that augment Ansible's core functionality. Ansible ships with a number of handy plugins, and you can easily write your own.
This section describes the various types of plugins and how to implement them.
Plugins are pieces of code that augment Ansible's core functionality. Ansible ships with a number of handy plugins, and you can easily write your own. This section describes the various types of Ansible plugins and how to implement them.
.. _plugin_guidelines:
General Guidelines
------------------
Some things that should apply to any type of plugin you develop.
This section lists some things that should apply to any type of plugin you develop.
Raising Errors
``````````````
In general, errors encountered during execution should be returned by raising AnsibleError() or similar class with a message describing the error.
When wrapping other exceptions into error messages you should always use the `to_text` Ansible function to ensure proper string compatiblity across
Python versions:
In general, errors encountered during execution should be returned by raising AnsibleError() or similar class with a message describing the error. When wrapping other exceptions into error messages, you should always use the `to_text` Ansible function to ensure proper string compatiblity across Python versions:
.. code-block:: python
@ -31,35 +28,32 @@ Python versions:
Check the different AnsibleError objects and see which one applies the best to your situation.
String encoding
String Encoding
```````````````
Any strings returned by your plugin that could ever contain non-ASCII characters must be converted into Python's unicode type
because the strings will be run through jinja2. To do this, you can use:
Any strings returned by your plugin that could ever contain non-ASCII characters must be converted into Python's unicode type because the strings will be run through jinja2. To do this, you can use:
.. code-block:: python
from ansible.module_utils._text import to_text
result_string = to_text(result_string)
Plugin configuration
Plugin Configuration
````````````````````
Starting in 2.4 and going forward, we are unifying how each plugin type is configured and how they get those settings, plugins will be able to 'declare'
their needs and have Ansible provide them with the 'resolved' configuration. As of 2.4 both Callback and Connection type plugins can use this system,
most plugins will be able to use `self._options[<optionname>]` to access the settings, except callbacks that due to prexisting collsion
use `self._plugin_optoins[<optionname>]`.
Starting with Ansible version 2.4, we are unifying how each plugin type is configured and how they get those settings. Plugins will be able to declare their requirements and have Ansible provide them with a resolved'configuration. Starting with Ansible 2.4 both callback and connection type plugins can use this system.
Plugins that supprot docs (see `ansible-doc` for the list) are now required to provide documentation to be considered for merge into the Ansible repo.
Most plugins will be able to use `self._options[<optionname>]` to access the settings, except callbacks that use `self._plugin_options[<optionname>]`.
Also be aware that if you inherit from a plugin you must ALSO document the optoins it takes, either via a documentation fragment or as a copy.
Plugins that support embedded documentation (see `ansible-doc` for the list) are now required to provide well-formed doc strings to be considered for merge into the Ansible repo.
If you inherit from a plugin, you must document the options it takes, either via a documentation fragment or as a copy.
.. _developing_callbacks:
Callback Plugins
----------------
See :doc: plugins/callback as to what they are and how to use them. This section explains how to use them.
Callback plugins enable adding new behaviors to Ansible when responding to events. By default, callback plugins control most of the output you see when running the command line programs.
Callback plugins are created by creating a new class with the Base(Callbacks) class as the parent:
@ -76,8 +70,8 @@ For a complete list of methods that you can override, please see ``__init__.py``
`lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ directory.
The following example shows a modified example Ansible's timer plugin is implemented,
but with an extra option so you can see how configuration works in Ansible >= 2.4:
The following is a modified example of how Ansible's timer plugin is implemented,
but with an extra option so you can see how configuration works in Ansible version 2.4 and later:
.. code-block:: python
@ -135,67 +129,68 @@ but with an extra option so you can see how configuration works in Ansible >= 2.
r_seconds = runtime.seconds - (minutes * 60)
return runtime.days, runtime.seconds // 3600, minutes, r_seconds
# this is only event we care about for display, when the play shows it's summary stats, the rest are ignored by the base class
# this is only event we care about for display, when the play shows its summary stats; the rest are ignored by the base class
def v2_playbook_on_stats(self, stats):
end_time = datetime.now()
runtime = end_time - self.start_time
# Shows the usage of a config option declared in the DOCUMENTATION variable, Ansible will have set it when it loads the plugin.
# Also note the use of the display object to print to screen, available to all callbacks, you should prefer this over printing yoruself
# Shows the usage of a config option declared in the DOCUMENTATION variable. Ansible will have set it when it loads the plugin.
# Also note the use of the display object to print to screen. This is available to all callbacks, and you should use this over printing yourself
self._display.display(self._plugin_options['format_string'] % (self._days_hours_minutes_seconds(runtime)))
Note that the CALLBACK_VERSION and CALLBACK_NAME definitions are required for properly functioning plugins for Ansible >=2.0.
CALLBACK_TYPE is mostly needed to distinguish 'stout' plugins from the rest, as you can only load one of that type.
Note that the CALLBACK_VERSION and CALLBACK_NAME definitions are required for properly functioning plugins for Ansible version 2.0 and later. CALLBACK_TYPE is mostly needed to distinguish 'stdout' plugins from the rest, since you can only load one plugin that writes to stdout.
.. _developing_connection_plugins:
Connection Plugins
------------------
By default, Ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), 'local' connection type, and there are also some minor players like 'chroot' and 'jail'. 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. Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
directory. The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 and later. Previous versions did not support 'smart'.
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.
More documentation on writing connection plugins is pending, though you can jump into
`lib/ansible/plugins/connection <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_ and figure things out pretty easily.
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.
Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins directory.
Ansible version 2.1 introduced the 'smart' connection plugin. The 'smart' connection type allows Ansible to automatically select either the 'paramiko' or 'openssh' connection plugin based on system capabilities, or the 'ssh' connection plugin if OpenSSH supports ControlPersist.
For examples on how to implement a connection plug in, see the source code here:
`lib/ansible/plugins/connection <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_.
.. _developing_inventory_plugins:
Inventory Plugins
-----------------
Added in Ansible 2.4 they are in charge of parsing inventory sources and forming the 'in memory' representation of the Inventory.
Inventory plugins were added in Ansible version 2.4. Inventory plugins parse inventory sources and form an in memory representation of the inventory.
They are invoked via the InventoryManager and are given access to any existing inventory data added previouslly,
they are given an 'inventory source' as supplied to Ansible (via config/optoins/defaults/etc), which they can ignore
(return false from the `verify_file` method), or attempt to parse (via `parse` method) and return an `AnsibleParserError` on failure.
Inventory plugins are invoked via the InventoryManager and are given access to any existing inventory data. They are given an 'inventory source' as supplied to Ansible (via config/options/defaults/etc), which they can either ignore
by returning false from the `verify_file` method, or attempting to parse (with the `parse` method) and return an `AnsibleParserError` on failure.
.. code-block:: python
def parse(self, inventory, loader, path, cache=True):
pass # your code goes here
The parameters are:
Inventory plugins take the following parameters:
* inventory: inventory object with existing data and the methods to add hosts/groups/variables to inventory
* loader: Ansible's DataLoader, it can read files, auto load JSON/YAML and decrypt vaulted data, it also caches read filesh.
* path: string with inventory source (normally a path, but not required)
* cache: hint to the plugin if it should use or avoid caches (Cache plugin and/or loader)
* loader: Ansible's DataLoader. The DataLoader can read files, auto load JSON/YAML and decrypt vaulted data, and cache read files.
* path: string with inventory source (this is usually a path, but is not required)
* cache: indicates whether the plugin should use or avoid caches (cache plugin and/or loader)
Inventory sources are strings, most of the time they correspond to a file path, but can also be a comma separated list,
a uri or anything your plugin can use as input.
The 'inventory source' provided can be either a string (`host_list` plugin), a data file (like consumed by the `yaml` and `ini` plugins),
a configuration file (see `virtualbox` and `constructed`) or even a script or executable (the `script` uses those) which is how 'inventory scripts' work.
Inventory sources are strings. They usually correspond to a file path, but they can also be a comma separated list,
a URI, or anything your plugin can use as input.
The 'inventory source' provided can be either a string (`host_list` plugin), a data file (like consumed by the `yaml` and `ini` plugins), a configuration file (see `virtualbox` and `constructed`) or even a script or executable (the `script` uses those).
Inventory plugins can also use the configured Cache plugin to store and retrieve data to avoid costly external calls,
of course this only works if using a 'persistent' cache (i.e not the memory one).
When using the 'persistent' cache, inventory plugins can also use the configured cache plugin to store and retrieve data to avoid costly external calls.
Be aware that inventory plugins normally only execute at the start of the run, before playbooks/plays and roles are found,
Inventory plugins normally only execute at the start of a run, before playbooks/plays and roles are found,
but they can be 're-executed' via the `meta: refresh_inventory` task, which will clear out the existing inventory and rebuild it.
More documentation on writing inventory plugins is pending, though you can jump into
`lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory>`_ and figure things out pretty easily.
For examples on how to implement a connection plug in, see the source code here:
`lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory>`_.
.. _developing_lookup_plugins:
@ -208,7 +203,7 @@ Here's a simple lookup plugin implementation - this lookup returns the contents
.. code-block:: python
# python 3ish headers, required if submitting to Ansible
# python 3 headers, required if submitting to Ansible
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
@ -225,7 +220,7 @@ Here's a simple lookup plugin implementation - this lookup returns the contents
required: True
notes:
- if read in variable context, the file can be interpreted as YAML if the content is valid to the parser.
- this lookup does not understand 'globing', use the fileglob lookup instead.
- this lookup does not understand 'globing' - use the fileglob lookup instead.
"""
from ansible.errors import AnsibleError, AnsibleParserError
from ansible.plugins.lookup import LookupBase
@ -269,7 +264,7 @@ Here's a simple lookup plugin implementation - this lookup returns the contents
return ret
An example of how this lookup is called::
The following is an example of how this lookup is called::
---
- hosts: all
@ -282,19 +277,18 @@ An example of how this lookup is called::
For more example lookup plugins, check out the source code for the lookup plugins that are included with Ansible here: `lib/ansible/plugins/lookup <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_.
For usage examples of lookup plugins, see `Using Lookups <http://docs.ansible.com/ansible/playbooks_lookups.html>`_.
For more usage examples of lookup plugins, see `Using Lookups <http://docs.ansible.com/ansible/playbooks_lookups.html>`_.
.. _developing_vars_plugins:
Vars Plugins
------------
Playbook constructs like 'host_vars' and 'group_vars' work via 'vars' plugins.
They inject additional variable data into ansible runs that did not come from an inventory source, playbook, or command line.
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 got rewritten in 2.4 and had been semi-functional since 2.0.
Vars plugins were partially implented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4.
Older pugins used a `run` method as their main body/work:
Older plugins used a `run` method as their main body/work:
.. code-block:: python
@ -302,7 +296,7 @@ Older pugins used a `run` method as their main body/work:
pass # your code goes here
But Ansible 2.0 did not pass passwords to them so vaults were unavilable.
Ansible 2.0 did not pass passwords to older plugins, so vaults were unavilable.
Most of the work now happens in the `get_vars` method which is called from the VariableManager when needed.
.. code-block:: python
@ -312,18 +306,16 @@ Most of the work now happens in the `get_vars` method which is called from the
The parameters are:
* loader: Ansible's DataLoader, it can read files, auto load JSON/YAML and decrypt vaulted data, it also caches read filesh.
* path: this is 'directory data' for every inventory source and the current play's playbook directory, so they can search for data
in reference to them, `get_vars` will be called at least once per available path.
* entities: these are host or group names that are pertinent to the variables needed, the plugin will get called once for hosts and again for groups.
* loader: Ansible's DataLoader. The DataLoader can read files, auto load JSON/YAML and decrypt vaulted data, and cache read files.
* path: this is 'directory data' for every inventory source and the current play's playbook directory, so they can search for data in reference to them. `get_vars` will be called at least once per available path.
* entities: these are host or group names that are pertinent to the variables needed. The plugin will get called once for hosts and again for groups.
This method just needs to return a dictionary structure with the pertinent variables.
This `get vars` method just needs to return a dictionary structure with the variables.
Since Ansible 2.4, vars plugins execute as needed when preparing to execute a task, this avoids the costly 'always execute' that used
to happend during inventory construction.
Since Ansible version 2.4, vars plugins only execute as needed when preparing to execute a task. This avoids the costly 'always execute' behavior that occurred during inventory construction in older versions of Ansible.
More documentation on writing vars plugins is pending, though you can jump into
`lib/ansible/plugins/vars <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_ and figure things out pretty easily.
For implementation examples of vars plugins, check out the source code for the vars plugins that are included with Ansible:
`lib/ansible/plugins/vars <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_ .
.. _developing_filter_plugins:

15
docs/docsite/rst/intro_configuration.rst
View file

@ -4,7 +4,7 @@ Configuration
.. contents:: Topics
There are several ways to control Ansible settings, this is a brief descriptoin of them.
This topic describes how to control Ansible settings.
.. _the_configuration_file:
@ -20,16 +20,15 @@ The stock configuration should be sufficient for most users, but there may be re
Getting the latest configuration
````````````````````````````````
If installing ansible from a package manager, the latest ansible.cfg should be present in /etc/ansible, possibly
If installing Ansible from a package manager, the latest ansible.cfg file should be present in /etc/ansible, possibly
as a ".rpmnew" file (or other) as appropriate in the case of updates.
If you have installed from pip or from source, however, you may want to create this file in order to override
If you installed Ansible from pip or from source, you may want to create this file in order to override
default settings in Ansible.
An example file is availble `ansible.cfg in source control <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_
An `example file is available on Github <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_.
For more details and a full listing of available configurations go to :doc:configuration or (starting at Ansible 2.4)
you can use the :doc:`ansible-config` command line utility to list your available options and inspect the current values.
For more details and a full listing of available configurations go to :doc:configuration. Starting with Ansible version 2.4, you can use the :doc:`ansible-config` command line utility to list your available options and inspect the current values.
For in depth details you check out :doc:`config`.
@ -37,10 +36,10 @@ For in depth details you check out :doc:`config`.
Environmental configuration
+++++++++++++++++++++++++++
Ansible also allows configuration of settings via environment variables.
Ansible also allows configuration of settings using environment variables.
If these environment variables are set, they will override any setting loaded from the configuration file.
You can get a full listing of available variables from :doc:`config`.
You can get a full listing of available environment variables from :doc:`config`.
.. _command_line_configuration:

32
docs/docsite/rst/playbooks_lookups.rst
View file

@ -1,17 +1,13 @@
Lookups
-------
Lookup plugins allow access of data in Ansible from outside sources. Like all templating, these plugins are evaluated on the Ansible control
machine, and can include reading the filesystem but also contacting external datastores and services.
These values are then made available using the standard templating system in Ansible,
and are typically used to load variables or templates with information from those systems.
Lookup plugins allow access to outside data sources. Like all templating, these plugins are evaluated on the Ansible control machine, and can include reading the filesystem as well as contacting external datastores and services. This data is then made available using the standard templating system in Ansible.
.. note::
- Lookups occur on the local computer, not on the remote computer.
- They are executed with a cwd relative to the role or play, as opposed to local tasks which are executed with the cwd of the executed script.
- Since 1.9 you can pass wantlist=True to lookups to use in jinja2 template "for" loops.
- This is considered an advanced feature, you should try to feel comfortable with Ansible plays before incorporating them.
- They are executed with in the directory containing the role or play, as opposed to local tasks which are executed with the directory of the executed script.
- Since Ansible version 1.9, you can pass wantlist=True to lookups to use in jinja2 template "for" loops.
- Lookups are an advanced feature. You should have a good working knowledge of Ansible plays before incorporating them.
.. warning:: Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the `|quote` filter to ensure safe usage.
@ -24,7 +20,7 @@ Intro to Lookups: Getting File Contents
The file lookup is the most basic lookup type.
Contents can be read off the filesystem as follows::
Contents can be read from the filesystem as follows::
---
- hosts: all
@ -42,18 +38,14 @@ The Password Lookup
.. note::
A great alternative to the password lookup plugin, if you don't need to generate random passwords on a per-host basis, would be to use :doc:`playbooks_vault`. Read the documentation there and consider using it first, it will be more desirable for most applications.
We recommend using :doc:`playbooks_vault` instead of the password lookup plugin if you don't need to generate random passwords on a per-host basis.
``password`` generates a random plaintext password and stores it in
The ``password lookup`` plugin generates a random plaintext password and stores it in
a file at a given filepath.
(Docs about crypted save modes are pending)
If the file already exists, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set up random passwords per host (which simplifies password management in 'host_vars' variables).
If the file exists previously, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set
up random passwords per host (which simplifies password management in 'host_vars' variables).
A special case is using ``/dev/null`` as a path. The password lookup will generate a new random password each time, but will not write it to ``/dev/null``. This can be used when you need a password
without storing it on the controller.
A special case is using ``/dev/null`` as a path. The password lookup will generate a new random password each time, but will not write it to ``/dev/null``. This can be used when you need a password without storing it on the controller.
Generated passwords contain a random mix of upper and lowercase ASCII letters, the
numbers 0-9 and punctuation (". , : - _"). The default length of a generated password is 20 characters.
@ -74,9 +66,9 @@ This length can be changed by passing an extra parameter::
.. note:: If the file already exists, no data will be written to it. If the file has contents, those contents will be read in as the password. Empty files cause the password to return as an empty string.
Caution: Since this runs on the ansible host as the user running the playbook, and "become" does not apply, the target file must be readable by the playbook user, or, if it does not exist, the playbook user must have sufficient privileges to create it. (So, for example, attempts to write into areas such as /etc will fail unless the entire playbook is being run as root).
.. warning:: Since the password lookup runs on the Ansible host as the user running the playbook, and "become" does not apply, the target file must be readable by the playbook user, or, if it does not exist, the playbook user must have sufficient privileges to create it. Attempts to write into areas such as /etc will fail unless the entire playbook is being run as root.
Starting in version 1.4, password accepts a "chars" parameter to allow defining a custom character set in the generated passwords. It accepts comma separated list of names that are either string module attributes (ascii_letters,digits, etc) or are used literally::
Starting in Ansible version 1.4, password accepts a "chars" parameter to allow defining a custom character set in the generated passwords. It accepts comma separated list of names that are either string module attributes (such as ascii_letters or digits) or are used literally::
---
- hosts: all
@ -100,7 +92,7 @@ Starting in version 1.4, password accepts a "chars" parameter to allow defining
# (...)
To enter comma use two commas ',,' somewhere - preferably at the end. Quotes and double quotes are not supported.
To enter a comma use two commas ',,' somewhere - preferably at the end. Quotes and double quotes are not supported.
.. _passwordstore_lookup:

8
docs/docsite/rst/plugins.rst
View file

@ -1,11 +1,11 @@
Plugins
=======
Ansible uses a plugin architecture to enable a rich, flexible and expandible feature set.
They are pieces of code that augment Ansible's core functionality.
Plugins are pieces of code that augment Ansible's core functionality. Ansible uses a plugin architecture to enable a rich, flexible and expandible feature set.
Ansible ships with a number of handy plugins, and you can easily write your own.
There are many types of plugins, these are the most relevant ones:
This section covers the various types of plugins that are included with Ansible:
.. toctree:: :maxdepth: 1
:glob:
@ -14,8 +14,6 @@ There are many types of plugins, these are the most relevant ones:
playbooks_filters
playbooks_tests
Most of the time you are using them without having to know about them, but when you want to change certain behaviours you need to know how to enable,
activate or trigger each type.
.. seealso::

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