Make role 'parameters' formally have pure function parameter scope

[torched99]

SUMMARY

Currently 'parameters' for roles are mentioned in the documentation, but are not effectively anything more than normal ansible variables, subject to the now very complex and confusing ansible scoping rules. For the use case where we create a re-usable role that is designed to behave in a similar manner as an ansible task module, there will be a bunch of variables that form the parameters (or arguments) of the role - some of which may be optional etc, and should ideally pick up defaults from the role's vars/main.yml or defaults/main.yml or simply remain undefined for conditional logic. At present to achieve this behaviour can be done in an unsatisfactory manner by:

1. using deliberately role specific variable names to minimise the chance of a role execution inadvertently using a value defined in some other place, e.g.
   <param_name>:- p__<role_name>__<param_name>
   which makes for horribly long and ugly parameter passing yaml
2. specifying the parameter values to the role for example via the vars: keyword at the include_role, import_role, roles list level (or via other roles parameter passing methods).
3. hoping nested calls will have scoping issues for parameters not-provided in inner-nested calls.

What would be much cleaner and would help with scope issues in general would be to flag certain role variables as parameters, so that their values then ONLY be set from the call to 'include' the role, or from within the role action itself. In other words the similar behaviour as stack based standard function arguments in C for example. Then we can use simple (potentially common) short names, e.g. owner, group, mode, hostname, file, src, dest, etc for these parameter variable names and not worry about scope leakage.

ISSUE TYPE

• Feature Idea

COMPONENT NAME

roles

ADDITIONAL INFORMATION

Example illustrating proposed via hypothetical params keyword in meta/main.yml.

---
# file: playbook.yml
- name: play calling module_oriented_role1 for file 'file.txt'
  hosts: localhost
  gather_facts: no
  tasks:
    - name: include_role module_oriented_role1
      include_role:
        name: module_oriented_role1
      vars:
        file: 'file.txt'
        owner: 'file_owner'

---
# file: roles/module_oriented_role1/tasks/main.yml
# Contrived role wrapper example with 2 tasks, to generate file, and then run some 
# command that uses that file as input
- name:  file update
  template:
    src: template1.j2
    dest: "{{ file }}"
    owner: "{{ owner | default(omit) }}"
    group: "{{ group | default(omit) }}"
    mode: "{{ module_oriented_role1_file_mode }}"

# invoke command with file as input
- name: file apply
  command:
  args:
    argv:
      - "{{ module_oriented_role1_prog }}"
      - "-f"
      - "{{ file }}"

---
# file: roles/module_oriented_role1/meta/main.yml
# Hypothetical keyword defined by meta to flag some variables to use parameter scope.
# These vars may not be set/overridden via previous play set_fact task, 
#   nor via outermost vars: keyword to the role inclusion, 
#   nor via other roles/play/include_tasks vars definitions etc
#   but can be set via current role call's vars: or its defaults/main.yml, 
#   or its vars/main.yml (and of course via playbook extra vars)
params:
   - file
   - owner
   - group  

---
# file: roles/module_oriented_role1/vars/main.yml
# These vars may be overridden potentially via previous play set_fact task, 
# or via outermost vars: keyword to the role inclusion (or of course via or playbook extra vars) 
module_oriented_role1_prog: /bla/prog
module_oriented_role1_file_mode : '0640'

[ansibot]

Hi @torched99, thank you for submitting this issue!

click here for bot help

[ansibot]

Files identified in the description:

• lib/ansible/galaxy/data/apb/tasks/main.yml.j2
• lib/ansible/modules/clustering/etcd3.py
• lib/ansible/modules/commands/command.py
• lib/ansible/modules/files/file.py
• lib/ansible/modules/files/template.py
• lib/ansible/modules/net_tools/nsupdate.py
• lib/ansible/modules/system/group.py
• lib/ansible/modules/utilities/logic/include_role.py
• lib/ansible/playbook/role/include.py
• lib/ansible/plugins/lookup/vars.py
• test/integration/targets/args/aliases

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

[ansibot]

cc @sfromm
click here for bot help

[jborean93]

cc @alikins

[ansibot]

cc @evrardjp @nerzhul
click here for bot help

[ansibot]

Files identified in the description:

• lib/ansible/playbook/role

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

[samdoran]

Fixed by #69040