mirror of
https://github.com/ansible-collections/community.general.git
synced 2026-05-06 13:22:48 +00:00
rewrite of the developer guide, part 1 (#45179)
* rewrite of the developer guide, part 1
This commit is contained in:
Alicia Cozine
GitHub
@@ -1,23 +1,30 @@
|
||||
.. _developing_plugins:
|
||||
.. _plugin_guidelines:
|
||||
|
||||
Developing Plugins
|
||||
==================
|
||||
******************
|
||||
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 Ansible plugins and how to implement them.
|
||||
Plugins augment Ansible's core functionality with logic and features that are accessible to all modules. Ansible ships with a number of handy plugins, and you can easily write your own. All plugins must:
|
||||
|
||||
.. _plugin_guidelines:
|
||||
* be written in Python
|
||||
* raise errors
|
||||
* return strings in unicode
|
||||
* conform to Ansible's configuration and documentation standards
|
||||
|
||||
General Guidelines
|
||||
------------------
|
||||
Once you've reviewed these general guidelines, you can skip to the particular type of plugin you want to develop.
|
||||
|
||||
This section lists some things that should apply to any type of plugin you develop.
|
||||
Writing plugins in Python
|
||||
=========================
|
||||
|
||||
Raising Errors
|
||||
^^^^^^^^^^^^^^
|
||||
You must write your plugin in Python so it can be loaded by the ``PluginLoader`` and returned as a Python object that any module can use. Since your plugin will execute on the controller, you must write it in a :ref:`compatible version of Python <control_machine_requirements>`.
|
||||
|
||||
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 compatibility across Python versions:
|
||||
Raising errors
|
||||
==============
|
||||
|
||||
You should return errors encountered during plugin execution by raising ``AnsibleError()`` or a 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 compatibility across Python versions:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@@ -28,40 +35,53 @@ In general, errors encountered during execution should be returned by raising An
|
||||
except Exception as e:
|
||||
raise AnsibleError('Something happened, this was original exception: %s' % to_native(e))
|
||||
|
||||
Check the different AnsibleError objects and see which one applies the best to your situation.
|
||||
Check the different `AnsibleError objects <https://github.com/ansible/ansible/blob/devel/lib/ansible/errors/__init__.py>`_ and see which one applies best to your situation.
|
||||
|
||||
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:
|
||||
String encoding
|
||||
===============
|
||||
|
||||
You must convert any strings returned by your plugin into Python's unicode type. Converting to unicode ensures that these strings can run through Jinja2. To convert strings:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from ansible.module_utils._text import to_text
|
||||
result_string = to_text(result_string)
|
||||
|
||||
Plugin Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
Plugin configuration & documentation standards
|
||||
==============================================
|
||||
|
||||
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.
|
||||
To define configurable options for your plugin, describe them in the ``DOCUMENTATION`` section of the python file. Callback and connection plugins have declared configuration requirements this way since Ansible version 2.4; most plugin types now do the same. This approach ensures that the documentation of your plugin's options will always be correct and up-to-date. To add a configurable option to your plugin, define it in this format:
|
||||
|
||||
Most plugins will be able to use ``self.get_option(<optionname>)`` to access the settings.
|
||||
These are pre-populated by a ``self.set_options()`` call, for most plugin types this is done by the controller,
|
||||
but for some types you might need to do this explicitly.
|
||||
Of course, if you don't have any configurable options, you can ignore this.
|
||||
.. code-block:: yaml
|
||||
|
||||
Plugins that support embedded documentation (see :ref:`ansible-doc` for the list) must now include well-formed doc strings to be considered for merge into the Ansible repo. This documentation also doubles as 'configuration definition' so they will never be out of sync.
|
||||
options:
|
||||
option_name:
|
||||
description: describe this config option
|
||||
default: default value for this config option
|
||||
env:
|
||||
- name: NAME_OF_ENV_VAR
|
||||
ini:
|
||||
- section: section_of_ansible.cfg_where_this_config_option_is_defined
|
||||
key: key_used_in_ansible.cfg
|
||||
required: True/False
|
||||
type: boolean/float/integer/list/none/path/pathlist/pathspec/string/tmppath
|
||||
version_added: X.x
|
||||
|
||||
If you inherit from a plugin, you must document the options it takes, either via a documentation fragment or as a copy.
|
||||
To access the configuration settings in your plugin, use ``self.get_option(<option_name>)``. For most plugin types, the controller pre-populates the settings. If you need to populate settings explicitly, use a ``self.set_options()`` call.
|
||||
|
||||
Plugins that support embedded documentation (see :ref:`ansible-doc` for the list) must include 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. See :ref:`module_documenting` for more information on correct documentation. Thorough documentation is a good idea even if you're developing a plugin for local use.
|
||||
|
||||
Developing particular plugin types
|
||||
==================================
|
||||
|
||||
.. _developing_callbacks:
|
||||
|
||||
Callback Plugins
|
||||
Callback plugins
|
||||
----------------
|
||||
|
||||
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 add 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:
|
||||
To create a callback plugin, create a new class with the Base(Callbacks) class as the parent:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@@ -75,7 +95,6 @@ For plugins intended for use with Ansible version 2.0 and later, you should only
|
||||
For a complete list of methods that you can override, please see ``__init__.py`` in the
|
||||
`lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ directory.
|
||||
|
||||
|
||||
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:
|
||||
|
||||
@@ -144,41 +163,49 @@ but with an extra option so you can see how configuration works in Ansible versi
|
||||
# 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 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.
|
||||
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.
|
||||
|
||||
For example callback plugins, see the source code for the `callback plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_
|
||||
|
||||
.. _developing_connection_plugins:
|
||||
|
||||
Connection Plugins
|
||||
Connection plugins
|
||||
------------------
|
||||
|
||||
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.
|
||||
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. The most commonly used connection plugins 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 connect to remote machines.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
The basics of these connection types are covered in the :ref:`intro_getting_started` section.
|
||||
To create a new connection plugin (for example, to support SNMP, Message bus, or other transports), copy the format of one of the existing connection plugins and drop it into the ``connection_plugins`` directory.
|
||||
|
||||
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.
|
||||
For example connection plugins, see the source code for the `connection plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_.
|
||||
|
||||
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.
|
||||
.. _developing_filter_plugins:
|
||||
|
||||
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>`_.
|
||||
Filter plugins
|
||||
--------------
|
||||
|
||||
Filter plugins manipulate data. They are a feature of Jinja2 and are also available in Jinja2 templates used by the ``template`` module. As with all plugins, they can be easily extended, but instead of having a file for each one you can have several per file. Most of the filter plugins shipped with Ansible reside in a ``core.py``.
|
||||
|
||||
Filter plugins do not use the standard configuration and documentation system described above.
|
||||
|
||||
For example filter plugins, see the source code for the `filter plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/filter>`_.
|
||||
|
||||
.. _developing_inventory_plugins:
|
||||
|
||||
Inventory Plugins
|
||||
Inventory plugins
|
||||
-----------------
|
||||
|
||||
Inventory plugins were added in Ansible version 2.4. Inventory plugins parse inventory sources and form an in memory representation of the inventory.
|
||||
Inventory plugins parse inventory sources and form an in-memory representation of the inventory. Inventory plugins were added in Ansible version 2.4.
|
||||
|
||||
You can see the details for inventory plugins in the :ref:`developing_inventory` page.
|
||||
|
||||
.. _developing_lookup_plugins:
|
||||
|
||||
Lookup Plugins
|
||||
Lookup plugins
|
||||
--------------
|
||||
|
||||
Lookup plugins are used to pull in data from external data stores. Lookup plugins can be used within playbooks both for looping --- playbook language constructs like ``with_fileglob`` and ``with_items`` are implemented via lookup plugins --- and to return values into a variable or parameter.
|
||||
Lookup plugins pull in data from external data stores. Lookup plugins can be used within playbooks both for looping --- playbook language constructs like ``with_fileglob`` and ``with_items`` are implemented via lookup plugins --- and to return values into a variable or parameter.
|
||||
|
||||
Lookup plugins are very flexible, allowing you to retrieve and return any type of data. When writing lookup plugins, always return data of a consistent type that can be easily consumed in a playbook. Avoid parameters that change the returned data type. If there is a need to return a single value sometimes and a complex dictionary other times, write two different lookup plugins.
|
||||
|
||||
@@ -261,13 +288,24 @@ The following is an example of how this lookup is called::
|
||||
- debug:
|
||||
msg: the value of foo.txt is {{ contents }} as seen today {{ lookup('pipe', 'date +"%Y-%m-%d"') }}
|
||||
|
||||
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 example lookup plugins, see the source code for the `lookup plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_.
|
||||
|
||||
For more usage examples of lookup plugins, see :ref:`Using Lookups<playbooks_lookups>`.
|
||||
|
||||
.. _developing_test_plugins:
|
||||
|
||||
Test plugins
|
||||
------------
|
||||
|
||||
Test plugins verify data. They are a feature of Jinja2 and are also available in Jinja2 templates used by the ``template`` module. As with all plugins, they can be easily extended, but instead of having a file for each one you can have several per file. Most of the test plugins shipped with Ansible reside in a ``core.py``. These are specially useful in conjunction with some filter plugins like ``map`` and ``select``; they are also available for conditional directives like ``when:``.
|
||||
|
||||
Test plugins do not use the standard configuration and documentation system described above.
|
||||
|
||||
For example test plugins, see the source code for the `test plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/test>`_.
|
||||
|
||||
.. _developing_vars_plugins:
|
||||
|
||||
Vars Plugins
|
||||
Vars plugins
|
||||
------------
|
||||
|
||||
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.
|
||||
@@ -292,7 +330,7 @@ Most of the work now happens in the ``get_vars`` method which is called from th
|
||||
|
||||
The parameters are:
|
||||
|
||||
* loader: Ansible's DataLoader. The DataLoader can read files, auto load JSON/YAML and decrypt vaulted data, and cache read files.
|
||||
* 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.
|
||||
|
||||
@@ -300,51 +338,8 @@ This ``get vars`` method just needs to return a dictionary structure with the va
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
Filter Plugins
|
||||
--------------
|
||||
|
||||
Filter plugins are used for manipulating data. They are a feature of Jinja2 and are also available in Jinja2 templates used by the ``template`` module. As with all plugins, they can be easily extended, but instead of having a file for each one you can have several per file. Most of the filter plugins shipped with Ansible reside in a ``core.py``.
|
||||
|
||||
See `lib/ansible/plugins/filter <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/filter>`_ for details.
|
||||
|
||||
.. _developing_test_plugins:
|
||||
|
||||
Test Plugins
|
||||
------------
|
||||
|
||||
Test plugins are for verifying data. They are a feature of Jinja2 and are also available in Jinja2 templates used by the ``template`` module. As with all plugins, they can be easily extended, but instead of having a file for each one you can have several per file. Most of the test plugins shipped with Ansible reside in a ``core.py``. These are specially useful in conjunction with some filter plugins like ``map`` and ``select``; they are also available for conditional directives like ``when:``.
|
||||
|
||||
See `lib/ansible/plugins/test <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/test>`_ for details.
|
||||
|
||||
.. _distributing_plugins:
|
||||
|
||||
Distributing Plugins
|
||||
--------------------
|
||||
|
||||
Plugins are loaded from the library installed path and the configured plugins directory (check your `ansible.cfg`).
|
||||
The location can vary depending on how you installed Ansible (pip, rpm, deb, etc) or by the OS/Distribution/Packager.
|
||||
Plugins are automatically loaded when you have one of the following subfolders adjacent to your playbook or inside a role:
|
||||
|
||||
* action_plugins
|
||||
* lookup_plugins
|
||||
* callback_plugins
|
||||
* connection_plugins
|
||||
* inventory_plugins
|
||||
* filter_plugins
|
||||
* strategy_plugins
|
||||
* cache_plugins
|
||||
* test_plugins
|
||||
* shell_plugins
|
||||
* vars_plugins
|
||||
|
||||
|
||||
When shipped as part of a role, the plugin will be available as soon as the role is called in the play.
|
||||
For example vars plugins, see the source code for the `vars plugins included with Ansible Core
|
||||
<https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
||||
Reference in New Issue
Block a user