Correct information about plugin enabling (#1760)

* Correct information about plugin enabling * Apply suggestions from code review Co-authored-by: Don Naro <[email protected]> --------- Co-authored-by: Don Naro <[email protected]>
ansible · Sep 11, 2024 · 1500fc2 · 1500fc2
1 parent 08e87b5
commit 1500fc2
Show file tree

Hide file tree

Showing 5 changed files with 9 additions and 4 deletions.
diff --git a/docs/docsite/rst/dev_guide/developing_locally.rst b/docs/docsite/rst/dev_guide/developing_locally.rst
@@ -137,6 +137,10 @@ Ansible automatically loads all plugins from certain directories adjacent to you
 
    Roles contained in collections cannot contain any plugins. All plugins in a collection must live in the collection ``plugins`` directory tree. All plugins in that tree are accessible to all roles in the collection. If you are developing new plugins, we recommend distributing them in :ref:`collections <developing_collections>`, not in roles.
 
+.. warning::
+
+    Some plugin types are needed early during Ansible execution, such as callbacks, inventory, and cache. These plugin types cannot be loaded dynamically and must exist in configured paths or be referenced by FQCN in configuration.
+
 .. _ansible.legacy.custom:
 
 Using ``ansible.legacy`` to access custom versions of an ``ansible.builtin`` module

diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst
@@ -38,7 +38,7 @@ If the cache plugin is in a collection use the fully qualified name:
     [defaults]
     fact_caching = namespace.collection_name.cache_plugin_name
 
-To enable a custom cache plugin, save it in a ``cache_plugins`` directory adjacent to your play, inside a role, or in one of the directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`.
+To enable a custom cache plugin, save it in one of the directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>` or in a collection and then reference it by FQCN.
 
 You 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.
 

diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst
@@ -23,7 +23,7 @@ The :ref:`say <say_callback>` callback responds with a computer-synthesized spee
 Enabling callback plugins
 -------------------------
 
-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 :ref:`ansible.cfg <ansible_configuration_settings>`.
+You can activate a custom callback, depending on it's ``NEEDS_ENABLED`` property,  by either dropping it into one of the callback directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>` or in a collection and referencing it in configuration by FQCN.
 
 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`.
 

diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst
@@ -36,8 +36,9 @@ Or, if it is a local plugin, perhaps stored in the path set by :ref:`DEFAULT_INV
 
    [inventory]
    enable_plugins = host_list, script, auto, yaml, ini, toml, my_plugin
-   
+
 If you use a plugin that supports a YAML configuration source, make sure that the name matches the name provided in the ``plugin`` entry of the inventory source file.
+For other plugins you must either save it in one of the directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>` and enable it or add to a collection and then reference it by FQCN.
 
 .. _using_inventory:
 

diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst
@@ -18,7 +18,7 @@ The :ref:`host_group_vars <host_group_vars_vars>` plugin shipped with Ansible en
 Enabling vars plugins
 ---------------------
 
-You can activate a custom vars plugin 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 :ref:`ansible.cfg <ansible_configuration_settings>`.
+You can activate a custom vars plugin 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 :ref:`ansible.cfg <ansible_configuration_settings>`. For a vars plugin to run during inventory build you cannot enable it in a play or role as these are not loaded until later. If they are only going to run at task execution, there are no limitations on where they are provided.
 
 Most vars plugins are disabled by default. To enable a vars plugin, set ``vars_plugins_enabled`` in the ``defaults`` section of :ref:`ansible.cfg <ansible_configuration_settings>` or set the ``ANSIBLE_VARS_ENABLED`` environment variable to the list of vars plugins you want to execute. By default, the :ref:`host_group_vars <host_group_vars_vars>` plugin shipped with Ansible is enabled.