ansible-documentation
ansible-documentation copied to clipboard
ansible
role allow_duplicates behaviour incorrectly described
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
Hi @torched99, thank you for submitting this issue!
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.
@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.
Files identified in the description:
lib/ansible/modules/import_role.pylib/ansible/playbook/role/include.pylib/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.
@acozine The default behavior of Ansible is to skip any role that is duplicated in a playbook, so setting
allow_duplicates: falseshould 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.
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.
to skip any role that is duplicated in a playbook
this is also incorrect, de-duping is per Play, not playbook.
And here we are, over two years and 3 major versions of Ansible later, and the docs remain incorrect.
PRs welcome @jorhett :-) Ansible documentation is community created and community maintained so every bit helps us become more accurate.
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.