ansible_parent_role_name/path variables for when a role is being included by another role

[Xaroth]

SUMMARY

Currently it is not possible for roles to detect when they are being directly included by another role.

This PR does the following:

• When a role is being included, set the ansible_parent_role_name to the name of the role that included this role.
• When a role is being included, set the ansible_parent_role_path to the path of the role that included this role.
• Document the role_name magic variable. It existed, but there was no existing documentation. Its companion role_path was already documented.

The main rationale for this is that we currently have a large set of roles that, in addition of providing with a state that is being managed, also expose a set of extra callable task files to allow other roles to easily perform tasks related to that role, without having to duplicate logic several dozen times.

During these includes, it is often required to send an identifier along, so that comments can indicate which role/feature requested these actions. Currently this is done by passing variables to each include_role action, but this proves to be prone to error.
The role_name variable already exists, but since this only stores the current executing role, it doesn't help trace down the source if the role was included otherwise.

The proposed new magic variables do specifically that; letting the included roles know who included them, so that it's easier to build conditions that only run (or should never run) when tasks are being included, and to be able to better debug the source of configuration.

ISSUE TYPE

• Feature Pull Request

COMPONENT NAME

Magic Variables

ANSIBLE VERSION

ansible 2.7.0

but this affects all versions.

ADDITIONAL INFORMATION

[ansibot]

@Xaroth: thank you for submitting this pull-request!

cc @acozine
click here for bot help

[Xaroth]

From what I can see the fails in the CI are not related to the code.

[webknjaz]

Hi @Xaroth,

It looks like an architectural change, which I believe requires a broader discussion.
Could you please go ahead and create a proposal in https://github.com/ansible/proposals/issues/new pointing to this PR as a reference implementation?

Thanks in advance!

[Xaroth]

@webknjaz Thanks, proposal sent in.

[gundalow]

Would be good to add some tests to defend this functionality

[bcoca]

i would make this a list so you can trace back the full stack, not just the immediate parent

[Xaroth]

@bcoca I updated the PR with your comments. I also added tests as per the request of @gundalow

[Xaroth]

I added an extra test case to ensure that include_tasks and import_tasks does not affect the ansible_parent_role_names vars.

[jamescassell]

shipit

This will bring very useful functionality, and appears to be well tested and documented. For bonus points, the code change itself is trivial.

[Xaroth]

Added changes requested by @samdoran:

• Make documentation reflect that both include_role as well as import_role cause this behavior.
• Add links to the include_role and import_role modules from that documentation, so that it's easier to find those module specifics
• Added tests for ansible_parent_role_paths. Currently only checking for lenght equality to ansible_parent_role_names as the tempdirs created by ansible-test make it difficult to fully check path values.
• Added tests to ensure that both ansible_parent_role_names and ansible_parent_role_paths are undefined prior to roles being included/imported, and after they have been included/imported.
• Added tests to ensure that the values reset to their original values after importing/including a role.

These changes add a lot of tests to the mix (around 50 new actions for the special_vars tests), but this shouldn't affect test runtime by much.

[samdoran]

I'll merge this for 2.9 after we create a branch for 2.8.