c1f1b2029c
* Move var plugins handling to a separate file
* Allow var plugins to require whitelisting
* Add global configuration ('demand', 'start') for users to control when they execute
* Add 'stage' configuration ('all', 'task', 'inventory') for users to control on a per-plugin basis when they execute
* Update ansible-inventory and InventoryManager to the global and stage configuration
* Update host_group_vars to use stage configuration and whitelisting
* Add documentation for using new options and to the developer's guide
* Add integration tests to exercise whitelisting and the new configuration options, using vars plugins in collections, and maintain backward compatibility
* Changelog
Co-Authored-By: Brian Coca <brian.coca+git@gmail.com>
Co-Authored-By: Sandra McCann <samccann@redhat.com>
84 lines
3.6 KiB
ReStructuredText
84 lines
3.6 KiB
ReStructuredText
.. _vars_plugins:
|
|
|
|
Vars Plugins
|
|
============
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 2
|
|
|
|
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.
|
|
|
|
The :ref:`host_group_vars <host_group_vars_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_variables` and :ref:`group_variables`.
|
|
|
|
|
|
.. _enable_vars:
|
|
|
|
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>`.
|
|
|
|
Starting in Ansible 2.10, vars plugins can require whitelisting rather than running by default. To enable a plugin that requires whitelisting 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 whitelisted.
|
|
|
|
Starting in Ansible 2.10, you can use vars plugins in collections. All vars plugins in collections require whitelisting and need to use the fully qualified collection name in the format ``namespace.collection_name.vars_plugin_name``.
|
|
|
|
.. code-block:: yaml
|
|
|
|
[defaults]
|
|
vars_plugins_enabled = host_group_vars,namespace.collection_name.vars_plugin_name
|
|
|
|
.. _using_vars:
|
|
|
|
Using vars plugins
|
|
------------------
|
|
|
|
By default, vars plugins are used on demand automatically after they are enabled.
|
|
|
|
Starting in Ansible 2.10, vars plugins can be made to run at specific times.
|
|
|
|
The global setting ``RUN_VARS_PLUGINS`` can be set in ``ansible.cfg`` using ``run_vars_plugins`` in the ``defaults`` section or by the ``ANSIBLE_RUN_VARS_PLUGINS`` environment variable. The default option, ``demand``, runs any enabled vars plugins relative to inventory sources whenever variables are demanded by tasks. You can use the option ``start`` to run any enabled vars plugins relative to inventory sources after importing that inventory source instead.
|
|
|
|
You can also control vars plugin execution on a per-plugin basis for vars plugins that support the ``stage`` option. To run the :ref:`host_group_vars <host_group_vars_vars>` plugin after importing inventory you can add the following to :ref:`ansible.cfg <ansible_configuration_settings>`:
|
|
|
|
.. code-block:: ini
|
|
|
|
[vars_host_group_vars]
|
|
stage = inventory
|
|
|
|
.. _vars_plugin_list:
|
|
|
|
Plugin Lists
|
|
------------
|
|
|
|
You can use ``ansible-doc -t vars -l`` to see the list of available plugins.
|
|
Use ``ansible-doc -t vars <plugin name>`` to see specific plugin-specific documentation and examples.
|
|
|
|
|
|
.. toctree:: :maxdepth: 1
|
|
:glob:
|
|
|
|
vars/*
|
|
|
|
.. seealso::
|
|
|
|
:ref:`action_plugins`
|
|
Ansible Action plugins
|
|
:ref:`cache_plugins`
|
|
Ansible Cache plugins
|
|
:ref:`callback_plugins`
|
|
Ansible callback plugins
|
|
:ref:`connection_plugins`
|
|
Ansible connection plugins
|
|
:ref:`inventory_plugins`
|
|
Ansible inventory plugins
|
|
:ref:`shell_plugins`
|
|
Ansible Shell plugins
|
|
:ref:`strategy_plugins`
|
|
Ansible Strategy plugins
|
|
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
|
Have a question? Stop by the google group!
|
|
`irc.freenode.net <http://irc.freenode.net>`_
|
|
#ansible IRC chat channel
|