Role duplicates docs updates (#72666)

* Change example to use role params to represent the documented outcome. Fixes #68922

* Add notes about how vars vs role params affect variable scoping, and how lazy evaluation and role-deduplicating is affected. Fixes #72650

* link to term
This commit is contained in:
Matt Martz 2020-12-18 10:55:54 -06:00 committed by GitHub
parent b514200126
commit 97765f4ebd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -355,6 +355,14 @@ Running role dependencies multiple times in one playbook
Ansible treats duplicate role dependencies like duplicate roles listed under ``roles:``: Ansible only executes role dependencies once, even if defined multiple times, unless the parameters, tags, or when clause defined on the role are different for each definition. If two roles in a playbook both list a third role as a dependency, Ansible only runs that role dependency once, unless you pass different parameters, tags, when clause, or use ``allow_duplicates: true`` in the dependent (third) role. See :ref:`Galaxy role dependencies <galaxy_dependencies>` for more details. Ansible treats duplicate role dependencies like duplicate roles listed under ``roles:``: Ansible only executes role dependencies once, even if defined multiple times, unless the parameters, tags, or when clause defined on the role are different for each definition. If two roles in a playbook both list a third role as a dependency, Ansible only runs that role dependency once, unless you pass different parameters, tags, when clause, or use ``allow_duplicates: true`` in the dependent (third) role. See :ref:`Galaxy role dependencies <galaxy_dependencies>` for more details.
.. note::
Role deduplication does not consult the invocation signature of parent roles. Additionally, when using ``vars:`` instead of role params, there is a side effect of changing variable scoping. Using ``vars:`` results
in those variables being scoped at the play level. In the below example, using ``vars:`` would cause ``n`` to be defined as ``4`` through the entire play, including roles called before it.
In addition to the above, users should be aware that role de-duplication occurs before variable evaluation. This means that :term:`Lazy Evaluation` may make seemingly different role invocations equivalently the same, preventing the role from running more than once.
For example, a role named ``car`` depends on a role named ``wheel`` as follows: For example, a role named ``car`` depends on a role named ``wheel`` as follows:
.. code-block:: yaml .. code-block:: yaml
@ -362,16 +370,12 @@ For example, a role named ``car`` depends on a role named ``wheel`` as follows:
--- ---
dependencies: dependencies:
- role: wheel - role: wheel
vars:
n: 1 n: 1
- role: wheel - role: wheel
vars:
n: 2 n: 2
- role: wheel - role: wheel
vars:
n: 3 n: 3
- role: wheel - role: wheel
vars:
n: 4 n: 4
And the ``wheel`` role depends on two roles: ``tire`` and ``brake``. The ``meta/main.yml`` for wheel would then contain the following: And the ``wheel`` role depends on two roles: ``tire`` and ``brake``. The ``meta/main.yml`` for wheel would then contain the following: