wbrawner/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clarify behavior of --skip-tags, --list-tasks, and --list-tags. (#60492)

Browse source
This commit is contained in:
Jered Sutton 2019-08-13 09:47:28 -05:00 committed by Alicia Cozine
parent ba81084a49
commit 6915ea96f1
1 changed files with 30 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
docs/docsite/rst/user_guide/playbooks_tags.rst
View file

@ -5,11 +5,6 @@ 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. a specific part of it rather than running *everything* in the playbook.
Ansible supports a "tags:" attribute for this reason. Ansible supports a "tags:" attribute for this reason.
When you execute a playbook, you can filter tasks based on tags in two ways:
- 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", Tags can be applied to *many* structures in Ansible (see "tag inheritance",
below), but its simplest use is with individual tasks. Here is an example below), but its simplest use is with individual tasks. Here is an example
that tags two tasks with different tags:: that tags two tasks with different tags::
@ -29,7 +24,14 @@ that tags two tasks with different tags::
tags: tags:
- configuration - configuration
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:: When you execute a playbook, you can filter tasks based on tags in two ways:
- On the command line, with the ``--tags`` or ``--skip-tags`` options
- In Ansible configuration settings, with the ``TAGS_RUN``
and ``TAGS_SKIP`` options
For example, 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" ansible-playbook example.yml --tags "configuration,packages"
@ -38,8 +40,15 @@ tasks, you can use the ``--skip-tags`` command-line option::
ansible-playbook example.yml --skip-tags "packages" ansible-playbook example.yml --skip-tags "packages"
You can see which tasks will be executed with ``--tags`` or ``--skip-tags`` by
combining it with ``--list-tasks``::
ansible-playbook example.yml --tags "configuration,packages" --list-tasks
.. warning:: .. warning::
* Fact gathering is tagged with 'always' by default. It is ONLY skipped if you apply a tag and then use a different tag in ``--tags`` or the same tag in ``--skip-tags``. * Fact gathering is tagged with 'always' by default. It is ONLY skipped if
you apply a tag and then use a different tag in ``--tags`` or the same
tag in ``--skip-tags``.
.. _tag_reuse: .. _tag_reuse:
@ -129,14 +138,16 @@ 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 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. 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. 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, The above information does not apply to `include_tasks` or other dynamic
as the attributes applied to an include, only affect the include itself. includes, as the attributes applied to an include, only affect the include
itself.
You can see which tags are applied to tasks, roles, and static imports You can see which tags are applied to tasks, roles, and static imports
by running ``ansible-playbook`` with the ``--list-tasks`` option. You can by running ``ansible-playbook`` with the ``--list-tasks`` option. You can
display all tags applied to the tasks with the ``--list-tags`` option. display all tags available with the ``--list-tags`` option.
.. note:: .. note::
The above information does not apply to `include_tasks`, `include_roles`, The above information does not apply to `include_tasks`, `include_roles`,
@ -175,7 +186,8 @@ Role tasks file::
Special Tags Special Tags
```````````` ````````````
There is a special ``always`` tag that will always run a task, unless specifically skipped (``--skip-tags always``) There is a special ``always`` tag that will always run a task, unless
specifically skipped (``--skip-tags always``)
Example:: Example::
@ -192,7 +204,8 @@ Example::
.. versionadded:: 2.5 .. versionadded:: 2.5
Another special tag is ``never``, which will prevent a task from running unless a tag is specifically requested. Another special tag is ``never``, which will prevent a task from running unless
a tag is specifically requested.
Example:: Example::
@ -200,10 +213,12 @@ Example::
- debug: msg="{{ showmevar }}" - debug: msg="{{ showmevar }}"
tags: [ never, debug ] tags: [ never, debug ]
In this example, the task will only run when the ``debug`` or ``never`` tag is explicitly requested. In this example, the task will only run when the ``debug`` or ``never`` tag
is explicitly requested.
There are another 3 special keywords for tags: ``tagged``, ``untagged`` and ``all``, which run only tagged, only untagged There are another 3 special keywords for tags: ``tagged``, ``untagged`` and
``all``, which run only tagged, only untagged
and all tasks respectively. and all tasks respectively.
By default, Ansible runs as if ``--tags all`` had been specified. By default, Ansible runs as if ``--tags all`` had been specified.