From 97765f4ebd2e06746a0700b48b01d3d8e067150f Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Fri, 18 Dec 2020 10:55:54 -0600 Subject: [PATCH] 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 --- .../rst/user_guide/playbooks_reuse_roles.rst | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst index 6def0132bc9..1c6e7e17880 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst @@ -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 ` 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: .. code-block:: yaml @@ -362,17 +370,13 @@ For example, a role named ``car`` depends on a role named ``wheel`` as follows: --- dependencies: - role: wheel - vars: - n: 1 + n: 1 - role: wheel - vars: - n: 2 + n: 2 - role: wheel - vars: - n: 3 + n: 3 - 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: