role allow_duplicates behaviour incorrectly described

[torched99]

SUMMARY

allow_duplicates: no for import_role appears to do nothing as there appears to be no way to pass role parameters.

allow_duplicate: no for include_role appears to work for vars: dict passing, and also matches those defined via roles: keyword with vars: dict.

The behaviour between between roles included/imported via the different methods, and ways to pass parameters/vars is not documented, and is not at all clear. parameter passing via play role: keyword or dependencies meta/main.yml entry appear to not match with passing identical via vars: dict.

Below is example play omitting only the meta/main.yml method to pull in role. Assuming role meta/main.yml is empty in this case.

- name: first play
  hosts: bla
  roles:
   # one of these will be actioned
    - { role: role1, testvar: 1 }
    - { role: role1, testvar: 1 }
   # one of these will also be actioned
    - role: role1
      vars:
          testvar: 1
    - role: role1
      vars:
          testvar: 1
   tasks:
    # both of these will be actioned
     - name: import role role1, testvar=1
       include_role:
          name: role1
          allow_duplicates: no
       vars:
           testvar: 1
     - name: import role role1, testvar=1, again
       include_role:
          name: role1
          allow_duplicates: no
       vars:
           testvar: 1
     # none of these will be actioned (due to roles section matching)
     - name: include role role1, testvar=1
       include_role:
           name: role1
           allow_duplicates: no
       vars:
           testvar: 1
     - name: include role role1, testvar=1, again
       include_role:
           name: role1
           allow_duplicates: no
       vars:
           testvar: 1

ISSUE TYPE

• Documentation Report

COMPONENT NAME

roles
include_role
import_role
role dependencies

ANSIBLE VERSION

CONFIGURATION

OS / ENVIRONMENT

Oracle Linux 6

ADDITIONAL INFORMATION

[ansibot]

Hi @torched99, thank you for submitting this issue!

click here for bot help

[ansibot]

Files identified in the description:

• lib/ansible/modules/utilities/logic/import_role.py
• lib/ansible/playbook/role/include.py
• lib/ansible/playbook/role/requirement.py

If these files are inaccurate, please update the component name section of the description or use the !component bot command.

click here for bot help

[acozine]

@torched99 passing different parameters is covered in the docs at https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#role-duplication-and-execution. The default behavior of Ansible is to skip any role that is duplicated in a playbook, so setting allow_duplicates: false should have no effect. We will do some testing on your playbook above and see if we can replicate the behavior you've been seeing.

If you want to achieve something in particular, please add your use case to this ticket.

[ansibot]

Files identified in the description:

• lib/ansible/modules/import_role.py
• lib/ansible/playbook/role/include.py
• lib/ansible/playbook/role/requirement.py

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

[jorhett]

@acozine The default behavior of Ansible is to skip any role that is duplicated in a playbook, so setting allow_duplicates: false should have no effect.

This documentation for include_role says otherwise: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/include_role_module.html#parameter-allow_duplicates

It very explicitly says that the default is yes and this will override any role's specified value.

If you want to achieve something in particular

Wouldn't that be not include a role that has already been included. The docs you quoted tell us how to include again, but have no mention of how to avoid it and as you can see by the DOZENS of open issues on this subject nobody can quite figure it out.

[sivel]

include_role will always ignore allow_duplicates. That is actually a feature of include_role, although the docs are incorrect.

allow_duplicates for include_role was never implemented, nor ever meant to be implemented, but some incorrect documentation snuck in.

[bcoca]

to skip any role that is duplicated in a playbook

this is also incorrect, de-duping is per Play, not playbook.

[jorhett]

And here we are, over two years and 3 major versions of Ansible later, and the docs remain incorrect.

[samccann]

PRs welcome @jorhett :-) Ansible documentation is community created and community maintained so every bit helps us become more accurate.

[jorhett]

PRs welcome @jorhett :-) Ansible documentation is community created and community maintained so every bit helps us become more accurate.

I would do that if I could, but I'm not exactly certain that I know the right answer. Like the others, I've found several wrong statements but I'm not certain what the right statements are and don't have a sufficiently diverse environment to teach every possible combination. I'm just frustrated by running into (or having engineers I support running into) the same docs-aren't-right issue for multiple years.