Tags as an operational control · Ansible

Tags get introduced as an organisational feature — a way to label tasks so you can find them. That framing produces the tag schemes that cause incidents.

Tags are a blast-radius control. --tags certificates is a statement that this run will touch certificate configuration and nothing else, on hosts that may be serving traffic. Every property that matters follows from treating them that way: the selection has to be verifiable before the run, it has to be the same tomorrow as today, and a selection that matches nothing must not look like a selection that worked.

That last one is where Ansible will not help you, and it is the reason this lesson exists.

Where tags can go

ansible-doc -t keyword tags states the scope exactly:

Read-only / Safethe tags keyword— Executed against ansible-core 2.21.3. Reads local plugin documentation; no connection.

$ ansible-doc -t keyword tags

tags:
applies_to:
- Play
- Role
- Block
- Task
- Handler
description: Tags applied to the task or included tasks, this allows selecting subsets
  of tasks from the command line.
priority: 0
template: explicit
type: list

Tags combine downward and additively. A tag on a play applies to every task in it; a task’s own tags are added rather than replacing:

Read-only / Safea play-level tag plus a task-level tag— Executed. The play carries playwide; the second task also declares inner. Both appear on that task.

$ ansible-playbook -i inventory.ini playtags.yml --list-tasks

playbook: playtags.yml

play #1 (local): tagged play	TAGS: [playwide]
  tasks:
    task in tagged play	TAGS: [playwide]
    task with its own tag	TAGS: [inner, playwide]

The same additive inheritance runs through import_role, import_tasks, the roles: keyword and meta/main.yml dependencies — Part XXII lessons 5 and 6 show each of those executed. The one place it does not flow is through a dynamic include, which is Part XXIII lesson 3 and is a large enough problem to get its own lesson.

Selecting

Two options, and a rule people get backwards.

--tags certificates            run only tasks carrying this tag
--tags certificates,nginx      run tasks carrying either
--skip-tags migrations         run everything except tasks carrying this

--skip-tags always wins. A task carrying both a selected tag and a skipped one is skipped:

Read-only / Safeskip beats select— Executed. The role is imported with tags: [patch], so both its tasks carry patch. One of them also carries alpha_inner. Selecting patch and skipping alpha_inner runs only the other task.

$ ansible-playbook -i inventory.ini import-local.yml --tags patch --skip-tags alpha_inner

TASK [alpha : alpha task two] **************************************************
ok: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

This is the safe direction for the rule to run. --skip-tags is how an operator excludes something they know is dangerous right now — the database migration, the reboot — and an exclusion that could be overridden by a selection would be useless as a safety control.

The failure: a tag that selected nothing

Ansible does not warn when --tags matches no tasks. The run completes, the recap is clean, and the exit code is zero:

Read-only / Safe--tags with a tag that does not exist anywhere— Executed on 2.21.3. The playbook has tasks tagged routine, destroy and never, and one tagged always. Selecting a tag that appears nowhere runs only the always task and exits 0.

$ ansible-playbook -i inventory.ini specialtags.yml --tags no_such_tag

TASK [always task] *************************************************************
ok: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

No warning. No error. Exit code 0.

Now put that in a pipeline. A CI job runs ansible-playbook site.yml --tags deploy, somebody renames the tag to deployment in a refactor, and the job keeps passing. Every build reports a successful deployment. Nothing has been deployed since the rename.

The defence is one command, and it is the reason --list-tags exists:

Read-only / Safewhat tags does this playbook actually have— Parse-time only. Prints the tag surface without connecting to anything.

ansible-playbook -i inventory/production.ini site.yml --list-tags

Read-only / Safewhat would this selection actually run— Combines tag selection with the task listing, so you see the selected tasks by name before running them. Parse-time only.

ansible-playbook -i inventory/production.ini site.yml --list-tasks --tags certificates

The second one is the pre-flight check to build a habit around. An empty task list is the answer to “did my tag select anything”, delivered before the run rather than inferred from a suspiciously quiet recap afterwards.

Make a mistyped tag fail in CI

--list-tasks --tags X prints a header and no tasks when nothing matched, so a pipeline can assert on it:

selected=$(ansible-playbook -i inventory/production.ini site.yml \
  --list-tasks --tags deploy | grep -cE '^ {6}\S.*TAGS:')
if [ "$selected" -eq 0 ]; then
  echo "tag deploy selected no tasks - refusing to run" >&2
  exit 1
fi

The six-space anchor matters. Task lines are indented six spaces; the play header also contains TAGS: and would be counted by a looser pattern, giving every empty selection a count of one and defeating the check.

Ten lines that convert a silent no-op into a failed build. Worth it for any tag a scheduled job depends on.

Designing a tag scheme that survives

Three properties, in order of how often they are missing.

Tags name work, not files. certificates, packages, firewall, migrations. Not step2, not webapp_role, not phase_a. The name has to mean something to the operator who types it at 03:00 without reading the playbook.

A tag selects a subset of the full run, not a different run. This is the constraint that keeps tags testable. If --tags foo executes tasks that the untagged run does not — because a when reads the tag selection, or because a task is tagged never and pulled in — then --tags foo is a separate code path with its own untested behaviour. Nobody can say what it does without running it, and running it is the thing they were trying to be careful about.

Every tag appears in --list-tags. Which means: no tags that exist only inside dynamic includes. Lesson 3.

Under the hood

Tag evaluation happens against the parse-time task tree, before execution and independently per task. Each task ends up with a set of tags — its own, plus every tag inherited from the block, role, import and play containing it — and the selection is set arithmetic on that set:

If the task’s tags intersect the --skip-tags set, skip it.
Otherwise, if --tags was given and the task’s tags do not intersect it, skip it.
Otherwise run it.

Rule 1 preceding rule 2 is the entire “skip always wins” behaviour; there is no tiebreak because the skip check never reaches the selection check.

Two consequences follow from evaluation being per-task rather than per-run.

First, there is nothing to warn about when a selection matches nothing. Ansible does not compute the set of tags in the playbook and compare it against what you asked for — it walks tasks and asks each one whether it is selected. A run where every task answers “no” is indistinguishable from a run of a playbook with no tasks.

Second, tags are resolved before any host is contacted, which is what makes --list-tasks --tags X free and exact for static content. The tree it prints is the tree the executor will walk.

What happens to a notified handler under a tag selection?

It runs. On ansible-core 2.21.3 a notified handler executes regardless of the tag selection, including when its own tags are named in --skip-tags.

Verified three ways against a play whose only task is tagged certificates and whose handler is tagged services:

--tags certificates                       RUNNING HANDLER [restart proxy]
--skip-tags services                      RUNNING HANDLER [restart proxy]
--tags certificates --skip-tags services  RUNNING HANDLER [restart proxy]

This is the reassuring direction — a partial run cannot leave new configuration on disk under an old process because the restart got filtered out — and it is worth knowing precisely, because the tags keyword lists Handler in its applies_to, which reads like a promise that tags gate handlers. They do not gate a handler that has been notified.

The corollary is that you cannot use --skip-tags to suppress a restart. An operator who wants the config written now and the service bounced later needs the change task itself excluded, or a variable the handler checks — not a tag on the handler.

Handlers also never appear in --list-tasks output at all, so for any tag scheme where a restart matters, confirm the behaviour on a scratch host by running the selection for real and reading the RUNNING HANDLER lines.

Where tags can go

Selecting

The failure: a tag that selected nothing

Designing a tag scheme that survives

Knowledge check