diff --git a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst index 1b3c2111859..953c1014711 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst @@ -211,4 +211,5 @@ Since Ansible 2.14 :ansplugin:`meta tasks ` are all Limitations ----------- -A handler cannot run ``import_role`` or ``include_role``. +A handler cannot run ``import_role`` nor ``include_role``. +Handlers :ref:`ignore tags `. diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index 98d782c0d2e..89124f01057 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -9,9 +9,13 @@ If you have a large playbook, it may be useful to run only specific parts of it #. Add tags to your tasks, either individually or with tag inheritance from a block, play, role, or import. #. Select or skip tags when you run your playbook. +.. note:: + The ``tags`` keyword is part of 'pre processing' the playbook and has high precedence when deciding what tasks are available to consider for execution. + .. contents:: :local: + Adding tags with the tags keyword ================================= @@ -81,6 +85,14 @@ You can apply the same tag to more than one individual task. This example tags s If you ran these four tasks in a playbook with ``--tags ntp``, Ansible would run the three tasks tagged ``ntp`` and skip the one task that does not have that tag. +.. _tags_on_handlers: + +Adding tags to handlers +^^^^^^^^^^^^^^^^^^^^^^^ + +Handlers are a special case of tasks that only execute when notified, as such they ignore all tags and cannot be selected for nor against. + + .. _tags_on_blocks: Adding tags to blocks @@ -121,6 +133,23 @@ If you want to apply a tag to many, but not all, of the tasks in your play, use tags: filesharing +Be mindful that ``tag`` selection supersedes most other logic, including ``block`` error handling. Setting a tag on a task in a ``block`` but not in the ``rescue`` or ``always`` section will prevent those from triggering if your tags selection does not cover the tasks in those sections. + +.. code-block:: yaml + + - block: + - debug: msg=run with tag, but always fail + failed_when: true + tags: example + + rescue: + - debug: msg=I always run because the block always fails, except if you select to only run 'example' tag + + always: + - debug: msg=I always run, except if you select to only run 'example' tag + +This example runs all 3 tasks if called without specifying ``--tags`` but only runs the first task if you run with ``--tags example``. + .. _tags_on_plays: Adding tags to plays @@ -156,6 +185,8 @@ If all the tasks in a play should get the same tag, you can add the tag at the l tasks: ... +.. note:: + The tasks tagged will include all implicit tasks (like fact gathering) of the play, including those added via roles. .. _tags_on_roles: @@ -192,6 +223,12 @@ or: # using YAML shorthand, this is equivalent to: # - { role: foo, tags: ["bar", "baz"] } + +.. note:: + When adding a tag at the role level, not only are all tasks tagged, but the role's dependencies also have their tasks tagged. + See the tag inheritance section for details. + + .. _tags_on_includes: Adding tags to includes