Update tags documentation to explain newer tags behavior (#44274)

docs/docsite/rst/user_guide/playbooks_tags.rst

@@ -1,16 +1,20 @@
 Tags
 ====
 
-If you have a large playbook it may become useful to be able to run a specific part of the configuration without running the whole playbook.
+If you have a large playbook, it may become useful to be able to run only
+a specific part of it rather than running *everything* in the playbook.
+Ansible supports a "tags:" attribute for this reason.
 
-Both plays and tasks support a "tags:" attribute for this reason.
-You can **ONLY** filter tasks based on tags from the command line with ``--tags`` or ``--skip-tags``.
-Adding "tags:" in any part of a play (including roles) adds those tags to the contained tasks.
+When you execute a playbook, you can filter tasks based on tags in two ways:
 
-Example::
+- On the command line, with the ``--tags`` or ``--skip-tags`` options
+- In Ansible configuration settings, with the ``TAGS_RUN`` and ``TAGS_SKIP`` options
+
+Tags can be applied to *many* structures in Ansible (see "tag inheritance",
+below), but its simplest use is with indivdual tasks. Here is an example
+that tags two tasks with different tags::
 
     tasks:
-
         - yum:
             name: "{{ item }}"
             state: installed
@@ -26,23 +30,24 @@ Example::
           tags:
              - configuration
 
-If you wanted to just run the "configuration" and "packages" part of a very long playbook, you could do this::
+If you wanted to just run the "configuration" and "packages" part of a very long playbook, you can use the ``--tags`` option on the command line::
 
     ansible-playbook example.yml --tags "configuration,packages"
 
-On the other hand, if you want to run a playbook *without* certain tasks, you could do this::
+On the other hand, if you want to run a playbook *without* certain tagged
+tasks, you can use the ``--skip-tags`` command-line option::
 
-    ansible-playbook example.yml --skip-tags "notification"
+    ansible-playbook example.yml --skip-tags "packages"
 
 
 .. _tag_reuse:
 
 Tag Reuse
 ```````````````
-You can apply the same tag name to more than one task, in the same file
-or included files. This will run all tasks with that tag.
+You can apply the same tag to more than one task. When a play is run using
+the ``--tags`` command-line option, all tasks with that tag name will be run.
 
-Example::
+This example tags several tasks with one tag, "ntp"::
 
     ---
     # file: roles/common/tasks/main.yml
@@ -73,7 +78,18 @@ Example::
 Tag Inheritance
 ```````````````
 
-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::
+Adding ``tags:`` to a play, or to statically imported tasks and roles, adds
+those tags to all of the contained tasks. This is referred to as *tag
+inheritance*. Tag inheritance is *not* applicable to dynamic inclusions
+such as ``include_role`` and ``include_tasks``.
+
+When you apply ``tags:`` attributes to structures other than tasks,
+Ansible processes the tag attribute to apply ONLY to the tasks they contain.
+Applying tags anywhere other than tasks is just a convenience so you don't
+have to tag tasks indivdually.
+
+This example tags all tasks in the two plays. The first play has all its tasks
+tagged with 'bar', and the second has all its tasks tagged with 'foo'::
 
     - hosts: all
       tags:
@@ -86,7 +102,7 @@ You can apply tags to more than tasks, but they ONLY affect the tasks themselves
       tasks:
         ...
 
-You may also apply tags to the tasks imported by roles::
+You may also apply tags to the tasks imported by ``roles``::
 
     roles:
       - role: webserver
@@ -94,24 +110,64 @@ You may also apply tags to the tasks imported by roles::
           port: 5000
         tags: [ 'web', 'foo' ]
 
-And import statements::
+And to ``import_role:`` and ``import_tasks:`` statements::
+
+    - import_role:
+        name: myrole
+      tags: [web,foo]
 
     - import_tasks: foo.yml
       tags: [web,foo]
 
+
 All of these apply the specified tags to EACH task inside the play, imported
 file, or role, so that these tasks can be selectively run when the playbook
 is invoked with the corresponding tags.
 
+Tags are applied *down* the dependency chain. In order for a tag to be
+inherited to a dependent role's tasks, the tag should be applied to the
+role declaration or static import, not to all the tasks within the role.
+
 There is no way to 'import only these tags'; you probably want to split into smaller roles/includes if you find yourself looking for such a feature.
 
 The above information does not apply to `include_tasks` or other dynamic includes,
 as the attributes applied to an include, only affect the include itself.
 
-Tags are inherited *down* the dependency chain. In order for tags to be applied to a role and all its dependencies,
-the tag should be applied to the role, not to all the tasks within a role.
+You can see which tags are applied to tasks, roles, and static imports 
+by running ``ansible-playbook`` with the ``--list-tasks`` option. You can
+display all tags applied to the tasks with the ``--list-tags`` option.
+
+.. note::
+    The above information does not apply to `include_tasks`, `include_roles`,
+    or other dynamic includes. Tags applied to either of these only tag the
+    include itself.
+
+To use tags with tasks and roles intended for dynamic inclusions,
+all needed tasks should be explicitly tagged at the task level; or
+``block:`` may be used to tag more than one task at once. The include
+itself should also be tagged.
+
+Here is an example of tagging role tasks with the tag ``mytag``, using a
+``block`` statement, to then be used with a dynamic include:
+
+Playbook file::
+
+    - hosts: all
+      tasks:
+      - include_role:
+          name: myrole
+        tags: mytag  
+
+Role tasks file::
+
+    - block:
+        - name: First task to run
+        ...
+        - name: Second task to run
+        ...
+      tags:
+        - mytag
 
-You can see which tags are applied to tasks by running ``ansible-playbook`` with the ``--list-tasks`` option. You can display all tags using the ``--list-tags`` option.
 
 .. _special_tags:
 

lib/ansible/config/base.yml

@@ -1602,6 +1602,7 @@ TAGS_RUN:
   env: [{name: ANSIBLE_RUN_TAGS}]
   ini:
   - {key: run, section: tags}
+  version_added: "2.5"
 TAGS_SKIP:
   name: Skip Tags
   default: []
@@ -1610,6 +1611,7 @@ TAGS_SKIP:
   env: [{name: ANSIBLE_SKIP_TAGS}]
   ini:
   - {key: skip, section: tags}
+  version_added: "2.5"
 USE_PERSISTENT_CONNECTIONS:
   name: Persistence
   default: False