diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index e25ba639101..5a6bc4d0e02 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -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``: diff --git a/docs/docsite/rst/dev_guide/developing_inventory.rst b/docs/docsite/rst/dev_guide/developing_inventory.rst index 13c880f1847..e93787014f8 100644 --- a/docs/docsite/rst/dev_guide/developing_inventory.rst +++ b/docs/docsite/rst/dev_guide/developing_inventory.rst @@ -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: diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index caffdf50f71..3c8c19d3339 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -150,7 +150,7 @@ see the source code for the `action plugins included with Ansible Core )``. 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: diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index 66ffbc30e59..e6cad2b895d 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -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 ` 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: diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index 0614a0c9b66..3160eb120fc 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -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`` -------------------------------------------------- diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index 0576b35c541..d9984627d15 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -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