inconsistent documentation for tags on dynamic-include tasks

[thinkmassive]

ISSUE TYPE

• Bug Report
• Documentation Report

COMPONENT NAME

• include_role
• include_tasks

ANSIBLE VERSION

ansible 2.4.2.0
  config file = /home/alexander/workspace/Ansible-adhoc/ansible.cfg
  configured module search path = [u'/usr/share/ansible', u'/home/alexander/workspace/Ansible-adhoc/library']
  ansible python module location = /usr/lib/python2.7/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 2.7.14 (default, Dec 11 2017, 16:08:01) [GCC 7.2.1 20170915 (Red Hat 7.2.1-2)]

CONFIGURATION

N/A

OS / ENVIRONMENT

Fedora 26 (probably N/A)

SUMMARY

The Creating Reusable Playbooks doc states:

If you use any include* Task (include_tasks, include_role, etc.), it will be dynamic.
...
When it comes to Ansible task options like tags and conditional statements (when:):
For static imports, the parent task options will be copied to all child tasks contained within the import.
For dynamic includes, the task options will only apply to the dynamic task as it is evaluated, and will not be copied to child tasks.

The Tags doc, under Tag Inheritance states:

You can apply tags to more than tasks, but they ONLY affect the tasks themselves. Applying tags anywhere else is just a convenience so you don’t have to write it on every task:
...

- include_tasks: foo.yml
  tags: [web,foo]

All of these apply the specified tags to EACH task inside the play, included file, or role, so that these tasks can be selectively run when the playbook is invoked with the corresponding tags.

Documentation discrepancy

• According to "Creating Reusable Playbooks" the tags on an include_* task should only determine whether the include_* task itself is executed, and the tags should not propagate into the included role.
• According to "Tag Inheritance" the tags an any include_* or import_* are inherited by each task within the role.

Personal opinion

The behavior described in "Creating Reusable Playbooks" seems most desirable. Actual behavior (described below) seems to be a combination of the two, and it doesn't offer much flexibility over the previous include functionality. This makes it impossible to run a subset of included tasks with a simple --tag, and instead requires a much more complicated combination of --tag+--skip-tags.

STEPS TO REPRODUCE

site.yml:

---
- hosts: all
  tasks:
    - include_role: name=role1
      tags: [ role1, include-role ]
    - include_tasks: name=tasks.yml
      tags: [ tasks1, include-tasks ]

roles/role1/tasks/main.yml:

---
- debug:
    msg: "include_role | tag: always"
  tags: always
- debug: 
    msg: "include_role | tag: role1"
  tags: role1
- debug: 
    msg: "include_role | tag: tag1"
  tags: tag1

tasks.yml:

---
- debug:
    msg: "include_tasks | tag: always"
  tags: always
- debug: 
    msg: "include_tasks | tag: tasks1"
  tags: tasks1
- debug: 
    msg: "include_tasks | tag: tag1"
  tags: tag1

hosts:

[all]
host1 ansible_connection=local

EXPECTED RESULTS

Summary

• Dynamic include tasks with a matching tag(s) are executed, and each inside-task is executed only if it has a specified tag (or no tags were specified), behaving according to the "Creating Reusable Playbooks" description
• Dynamic include tasks with no matching tags are skipped entirely (unless no tags are specified), behaving according to the "Creating Reusable Playbooks" description

Detail

1. ansible-playbook site.yml -i hosts -t role1
   i. role1 should run only the tasks tagged: always, role1
   ii. tasks.yml should be skipped

2. ansible-playbook site.yml -i hosts -t include-role
   i. role1 should run only the task tagged: always
   ii. tasks.yml should be skipped

3. ansible-playbook site.yml -i hosts -t include-role,tag1
   i. role1 should run only the tasks tagged: always, tag1
   ii. tasks.yml should be skipped

4. ansible-playbook site.yml -i hosts -t include-tasks
   i. role1 should be skipped
   ii. tasks.yml should run only the tasks tagged: always

5. ansible-playbook site.yml -i hosts -t include-tasks,tag1
   i. role1 should be skipped
   ii. tasks.yml should run only the tasks tagged: always, tag1

6. ansible-playbook site.yml -i hosts -t tag1
   i. role1 should be skipped
   ii. tasks.yml should be skipped

ACTUAL RESULTS

Summary

• Dynamic include tasks with a matching tag(s) are executed, and all inside-tasks have the tag(s) applied, behaving according to the "Tag Inheritance" description (bad)
• Dynamic include tasks with no matching tags are skipped entirely (unless no tags are specified), behaving according to the "Creating Reusable Playbooks" description (good)

Detail

1. ansible-playbook site.yml -i hosts -t role1
   i. (fail) role1 ran all tasks, including tag1
   ii. (pass) tasks.yml was skipped

2. ansible-playbook site.yml -i hosts -t include-role
   i. (fail) role1 ran all tasks, including role, tag1
   ii. (pass) tasks.yml was skipped

3. ansible-playbook site.yml -i hosts -t include-role,tag1
   i. (fail) role1 ran all tasks, including role1
   ii. (pass) tasks.yml was skipped

4. ansible-playbook site.yml -i hosts -t include-tasks
   i. (pass) role1 was skipped
   ii. (fail) tasks.yml ran all tasks, including tasks1, tag1

5. ansible-playbook site.yml -i hosts -t include-tasks,tag1
   i. (pass) role1 was skipped
   ii. (fail) tasks.yml ran all tasks, including tasks1

6. ansible-playbook site.yml -i hosts -t tag1
   i. (pass) role1 was skipped
   ii. (pass) tasks.yml was skipped

[ansibot]

Files identified in the description:

• lib/ansible/modules/utilities/logic/include_role.py
• lib/ansible/modules/utilities/logic/include_tasks.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

[bcoca]

coincidentally i was just updating those docs #37844

[ansibot]

Files identified in the description:

• lib/ansible/modules/include_role.py
• lib/ansible/modules/include_tasks.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

[bcoca]

closing as per above