Add some documentation about plugins in collections (#62465)

* Add some documentation about using plugins in collections

- FQCN requirements
- Sharing code in collections
- Limitations with inventory caching
This commit is contained in:
Sloane Hertel 2019-09-26 12:00:26 -04:00 committed by Sandra McCann
parent de515522b6
commit d41050b28b
6 changed files with 42 additions and 7 deletions

View file

@ -77,7 +77,9 @@ The ``ansible-doc`` command requires the fully qualified collection name (FQCN)
plugins directory
------------------
Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by any other plugin by using their FQCN. This is a way to distribute modules, lookups, filters, and so on, without having to import a role in every play.
Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on, without having to import a role in every play.
Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins.
module_utils
^^^^^^^^^^^^
@ -114,6 +116,11 @@ In the Python example the ``module_util`` in question is called ``qradar`` such
not_rest_data_keys=['state']
)
Note that importing something from an ``__init__.py`` file requires using the file name:
.. code-block:: python
from ansible_collections.namespace.collection_name.plugins.callback.__init__ import CustomBaseClass
In the PowerShell example the ``module_util`` in question is called ``hyperv`` such that the FCQN is
``ansible_example.community.plugins.module_utils.hyperv``:

View file

@ -74,6 +74,8 @@ The first thing you want to do is use the base class:
NAME = 'myplugin' # used internally by Ansible, it should match the file name but not required
If the inventory plugin is in a collection the NAME should be in the format of 'namespace.collection_name.myplugin'.
This class has a couple of methods each plugin should implement and a few helpers for parsing the inventory source and updating the inventory.
After you have the basic plugin working you might want to to incorporate other features by adding more base classes:

View file

@ -150,7 +150,7 @@ see the source code for the `action plugins included with Ansible Core <https://
Cache plugins
-------------
Cache plugins store gathered facts and data retrieved by inventory plugins.
Cache plugins store gathered facts and data retrieved by inventory plugins. Only fact caching is currently supported by cache plugins in collections.
Import cache plugins using the cache_loader so you can use ``self.set_options()`` and ``self.get_option(<option_name>)``. If you import a cache plugin directly in the code base, you can only access options via ``ansible.constants``, and you break the cache plugin's ability to be used by an inventory plugin.
@ -246,7 +246,7 @@ but with an extra option so you can see how configuration works in Ansible versi
"""
CALLBACK_VERSION = 2.0
CALLBACK_TYPE = 'aggregate'
CALLBACK_NAME = 'timer'
CALLBACK_NAME = 'namespace.collection_name.timer'
# only needed if you ship it and don't want to enable by default
CALLBACK_NEEDS_WHITELIST = True
@ -389,7 +389,7 @@ The following is an example of how this lookup is called::
---
- hosts: all
vars:
contents: "{{ lookup('file', '/etc/foo.txt') }}"
contents: "{{ lookup('namespace.collection_name.file', '/etc/foo.txt') }}"
tasks:
@ -418,7 +418,7 @@ 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.
Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4.
Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4. Vars plugins are unsupported by collections.
Older plugins used a ``run`` method as their main body/work:

View file

@ -34,6 +34,13 @@ or in the ``ansible.cfg`` file:
[defaults]
fact_caching=redis
If the cache plugin is in a collection use the fully qualified name:
.. code-block:: ini
[defaults]
fact_caching = namespace.collection_name.cache_plugin_name
You will also need to configure other settings specific to each plugin. Consult the individual plugin documentation
or the Ansible :ref:`configuration <ansible_configuration_settings>` for more details.
@ -43,7 +50,7 @@ A custom cache plugin is enabled by dropping it into a ``cache_plugins`` directo
Enabling Inventory Cache Plugins
--------------------------------
Inventory may be cached using a file-based cache plugin (like jsonfile). Check the specific inventory plugin to see if it supports caching.
Inventory may be cached using a file-based cache plugin (like jsonfile). Check the specific inventory plugin to see if it supports caching. Cache plugins inside a collection are not supported for caching inventory.
If an inventory-specific cache plugin is not specified Ansible will fall back to caching inventory with the fact cache plugin options.
The inventory cache is disabled by default. You may enable it via environment variable:

View file

@ -34,7 +34,7 @@ Most callbacks shipped with Ansible are disabled by default and need to be white
.. code-block:: ini
#callback_whitelist = timer, mail, profile_roles
#callback_whitelist = timer, mail, profile_roles, collection_namespace.collection_name.custom_callback
Setting a callback plugin for ``ansible-playbook``
--------------------------------------------------

View file

@ -31,6 +31,15 @@ This list also establishes the order in which each plugin tries to parse an inve
[inventory]
enable_plugins = advanced_host_list, constructed, yaml
The ``auto`` inventory plugin can be used to automatically determines which inventory plugin to use for a YAML configuration file. It can also be used for inventory plugins in a collection.
To whitelist specific inventory plugins in a collection you need to use the fully qualified name:
.. code-block:: ini
[inventory]
enable_plugins = namespace.collection_name.inventory_plugin_name
.. _using_inventory:
@ -55,6 +64,12 @@ Or for the openstack plugin the file has to be called ``clouds.yml`` or ``openst
# clouds.yml or openstack.(yml|yaml)
plugin: openstack
To use a plugin in a collection provide the fully qualified name:
.. code-block:: yaml
plugin: namespace.collection_name.inventory_plugin_name
The ``auto`` inventory plugin is enabled by default and works by using the ``plugin`` field to indicate the plugin that should attempt to parse it. You can configure the whitelist/precedence of inventory plugins used to parse source using the `ansible.cfg` ['inventory'] ``enable_plugins`` list. After enabling the plugin and providing any required options, you can view the populated inventory with ``ansible-inventory -i demo.aws_ec2.yml --graph``:
.. code-block:: text
@ -65,6 +80,8 @@ The ``auto`` inventory plugin is enabled by default and works by using the ``plu
| |--ec2-98-765-432-10.compute-1.amazonaws.com
|--@ungrouped:
If you are using an inventory plugin in a playbook-adjacent collection and want to test your setup with ``ansible-inventory``, you will need to use the ``--playbook-dir`` flag.
You can set the default inventory path (via ``inventory`` in the `ansible.cfg` [defaults] section or the :envvar:`ANSIBLE_INVENTORY` environment variable) to your inventory source(s). Now running ``ansible-inventory --graph`` should yield the same output as when you passed your YAML configuration source(s) directly. You can add custom inventory plugins to your plugin path to use in the same way.
Your inventory source might be a directory of inventory configuration files. The constructed inventory plugin only operates on those hosts already in inventory, so you may want the constructed inventory configuration parsed at a particular point (such as last). Ansible parses the directory recursively, alphabetically. You cannot configure the parsing approach, so name your files to make it work predictably. Inventory plugins that extend constructed features directly can work around that restriction by adding constructed options in addition to the inventory plugin options. Otherwise, you can use ``-i`` with multiple sources to impose a specific order, e.g. ``-i demo.aws_ec2.yml -i clouds.yml -i constructed.yml``.
@ -135,6 +152,8 @@ Here is an example of setting inventory caching with some fact caching defaults
cache = yes
cache_connection = /tmp/ansible_inventory
Besides cache plugins shipped with Ansible, cache plugins eligible for caching inventory can also reside in a custom cache plugin path. Cache plugins in collections are not supported yet for inventory.
.. _inventory_plugin_list:
Plugin List