diff options
| author | Sloane Hertel <19572925+s-hertel@users.noreply.github.com> | 2022-08-31 12:15:58 -0400 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-08-31 12:15:58 -0400 |
| commit | 2464e1e91c0ee1c65ecff450de973c3ce2ed767d (patch) | |
| tree | 85ad95084b0f2d5beef43c321472ba0066ad554d /docs/docsite/rst/dev_guide | |
| parent | f8e24e4a65a0a0d3e5a294d94c774c1ce1ac4152 (diff) | |
| download | ansible-2464e1e91c0ee1c65ecff450de973c3ce2ed767d.tar.gz | |
Fix vars plugin code and documentation mismatch (#78562)
* Add a warning for collections that are attempting to be autoloaded to no effect
* Deprecate REQUIRES_WHITELIST and add support for REQUIRES_ENABLED so the docs are accurate
* Fix documentation
* add more vars plugin tests
* Simplify code and add a FIXME for another bug
* fix precedence
* Make setting the class attr at all a warning, even if it's True
* Add fun parsing for _load_name
* include _load_name in messages
Diffstat (limited to 'docs/docsite/rst/dev_guide')
| -rw-r--r-- | docs/docsite/rst/dev_guide/developing_collections_structure.rst | 4 | ||||
| -rw-r--r-- | docs/docsite/rst/dev_guide/developing_plugins.rst | 4 |
2 files changed, 6 insertions, 2 deletions
diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 51f65685c5..4ec666ce3a 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -94,7 +94,9 @@ plugins directory 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 supported in collections as long as they require being explicitly enabled (using ``REQUIRES_ENABLED``) and they are included using their fully qualified collection name. See :ref:`enable_vars` and :ref:`developing_vars_plugins` for details. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins. +Vars plugins in collections are not loaded automatically, and always require being explicitly enabled by using their fully qualified collection name. See :ref:`enable_vars` for details. + +Cache plugins in collections may be used for fact caching, but are not supported for inventory plugins. .. _collection_module_utils: diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index de02e8d6c4..dbf516ffa9 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -501,7 +501,9 @@ 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. Since Ansible version 2.10, vars plugin execution can be toggled by the user to run when preparing to execute a task or after importing an inventory source. -You can create vars plugins that are not enabled by default using the class variable ``REQUIRES_ENABLED``. If your vars plugin resides in a collection, it cannot be enabled by default. You must use ``REQUIRES_ENABLED`` in all collections-based vars plugins. To require users to enable your plugin, set the class variable ``REQUIRES_ENABLED``: +The user must explicitly enable vars plugins that reside in a collection. See :ref:`enable_vars` for details. + +Legacy vars plugins are always loaded and run by default. You can prevent them from automatically running by setting ``REQUIRES_ENABLED`` to True. .. code-block:: python |