Conditionals that should have been groups · Ansible

Part XV closes with a design argument rather than a feature.

Here is a task from a real-shaped repository:

Service impact possiblethe thing this lesson is about— Restarts a service on a subset of hosts selected by four conditions. Which hosts those are cannot be determined without running it.

- name: Restart the collector on hosts that need the new agent
ansible.builtin.systemd_service:
  name: metrics-collector
  state: restarted
when:
  - ansible_facts.os_family == 'Debian'
  - ansible_facts.distribution_major_version | int >= 12
  - "'legacy' not in group_names"
  - inventory_hostname not in metrics_collector_exclusions
  - metrics_agent_version is version('2.0', '>=')

Five conditions. It parses, it reviews plausibly, and it restarts a service.

Now answer a question an operator must be able to answer before running it: which hosts does this restart?

You cannot. Not from reading it, not from --list-hosts, not from ansible-inventory. The only way to find out is to run it and read what happened afterwards — which is the wrong order for a task that restarts things.

The problem stated precisely

--limit and host patterns operate on inventory. They can express “the webservers group”, “everything in prod except db”, “hosts matching web*”.

when: operates on evaluation at task time, per host, after the play has already targeted that host, gathered its facts, and started running tasks against it.

So a decision written as when: is invisible to every targeting tool the course has taught you. ansible-playbook --list-hosts shows the hosts the play targets, not the hosts the task will act on. Your pre-flight blast-radius check reports a number that is not the number.

Blast radius you cannot inspect is blast radius you cannot control

This is the course’s organising idea meeting conditionals head-on.

Everything about restricting reach — --limit, host patterns, --list-hosts, serial batching — is built on the inventory. A condition that decides applicability at task time opts out of all of it.

The consequences compound:

You cannot dry-run the target set. --list-hosts overstates it.
You cannot --limit to the affected hosts to do a canary, because you do not know which they are.
serial batches the wrong population. A serial: 5 over 200 hosts where the task applies to 12 gives you batches that mostly do nothing and a rollout with no meaningful staging.
The recap does not tell you either. Skipped hosts and hosts where nothing needed doing look identical.

The refactor

Every condition in that chain answers a question about the host, not about the moment. Which means every one of them can be answered when the inventory is written.

Read-only / Safeinventory/production.yml— The same five decisions, expressed as group membership. Reading this file tells you which hosts are affected.

all:
children:
  metrics_collectors_v2:
    hosts:
      app01.example.com:
      app02.example.com:
      app03.example.com:
  metrics_collectors_legacy:
    hosts:
      app04.example.com:
      app05.example.com:

Service impact possiblethe task afterwards— Restarts a service on the hosts in one group. The affected set is the group, and it can be listed, limited and batched before anything runs.

- name: Restart the collector
hosts: metrics_collectors_v2
serial: 2
tasks:
  - name: Restart the collector
    ansible.builtin.systemd_service:
      name: metrics-collector
      state: restarted

The task now has no when: at all, and every tool works again:

Read-only / Safethe blast radius, before running anything— Prints the hosts the play will act on. With the conditional removed, this number is now the real number.

$ ansible-playbook --list-hosts restart-collectors.yml

playbook: restart-collectors.yml

play #1 (metrics_collectors_v2): Restart the collector	TAGS: []
  pattern: ['metrics_collectors_v2']
  hosts (3):
    app01.example.com
    app02.example.com
    app03.example.com

Read-only / Safeand the same answer from the inventory itself— ansible-inventory reads the inventory without touching any host. This is the authoritative answer to which hosts are in the group.

$ ansible-inventory -i inventory/production.yml --graph metrics_collectors_v2

@metrics_collectors_v2:
|--app01.example.com
|--app02.example.com
|--app03.example.com

Three hosts. Stated before the run, verifiable by two independent tools, and available to --limit and serial.

Where the policy goes

Moving membership to groups leaves the values to group_vars, which is the layering rule from Part XIII doing exactly what it was designed for:

Read-only / Safegroup_vars/metrics_collectors_v2.yml— Policy for the group. A reviewer sees the value, and ansible-inventory --host reports where it came from.

metrics_agent_version: '2.4.1'
metrics_collector_interval: 15
metrics_collector_endpoint: 'https://metrics.example.com/ingest'

Read-only / Safegroup_vars/metrics_collectors_legacy.yml— The other group's policy. Adding a third variant is a new file, not a new branch in a task.

metrics_agent_version: '1.8.9'
metrics_collector_interval: 60
metrics_collector_endpoint: 'https://metrics.example.com/ingest-v1'

The role becomes unconditional. It reads its variables and applies them, and it does not know or care which environment it is in. That is the property that makes a role reusable, and it is why Part XXII treats role interfaces as a design question rather than a filing one.

When `when:` is still right

This is not an argument against conditionals. It is an argument about which kind of decision belongs where.

Keep when: for genuine runtime state. Something only discoverable on the host, at that moment:

- name: Reboot to activate the new kernel
  ansible.builtin.reboot:
  when: reboot_required.stat.exists

Whether a reboot flag file exists is not knowable when the inventory is written. That is a real conditional.

Keep when: for a result you just registered. Lesson 2’s territory. The value came from a task in this run.

Keep when: for a single, stable, mechanical fact. One os_family branch inside a role that must work on both families is fine, and pushing it into inventory would mean every consumer of the role maintaining a debian_hosts group, which is worse.

The test is the same as Part XIV lesson 7’s, applied to conditions rather than values:

Could you have known, before the run started, whether this task applies to this host?

If yes, it is group membership written in the wrong place.

The decision table

Three ways to express “this applies to some hosts and not others”:

	Task `when:`	Inventory group	Separate play
Where the decision is visible	In the task body, at run time	In the inventory, before the run	In the playbook `hosts:` line
Can `--list-hosts` show the affected set?	No	Yes	Yes
Can `--limit` target it?	No	Yes	Yes
Does `serial` batch the right population?	No	Yes	Yes
Cost of adding a variant	A branch in shared code	A file and a group	A play
Right for	Runtime state, registered results	Host properties and policy	Different work, different targets

The third column deserves a word. A separate play is the right answer when the work differs, not just the values — when the Debian path and the RHEL path are genuinely different sequences rather than the same sequence with different parameters. Two plays with clear hosts: lines read better than one play with parallel branches throughout, and each gets its own honest blast radius.

The exclusion list is the worst version of this

when: inventory_hostname not in metrics_collector_exclusions

An exclusion list inside task logic combines every problem in this lesson with one more: it grows and nothing ever prunes it.

Hosts are added during incidents, for reasons recorded in a chat message, by people who intended to remove them the following week. Two years later the list has forty entries, nobody knows why thirty of them are there, and removing one is nobody’s idea of a safe change.

The same information as a group is not automatically better — but it is inspectable. ansible-inventory --graph metrics_excluded lists them, a group_vars file next to it can carry the reason and the ticket, and a survey play can report on the group monthly. Exceptions that can be seen get reviewed; exceptions buried in a when: do not.

Part XIV lesson 4 made the same argument about facts.d exceptions and reached the same conclusion: an exception nobody can see is indistinguishable from a bug.

Doing the refactor safely

The refactor is behaviour-preserving in intent and it is still a change to which hosts get touched, so prove it:

Enumerate the current behaviour. Run the existing play with the conditional replaced by a debug that prints inventory_hostname when the condition is true. That gives you the real affected set, from the current logic, without changing anything.
Build the group from that list. Not from your reading of the condition — from the output of step 1. The two differ more often than you expect, and the difference is the bug you are removing.
Compare. ansible-inventory --graph <newgroup> against the list from step 1. They must match exactly.
Check-mode the new play against a staging inventory and compare the changed set to a check-mode run of the old one.
Delete the conditional and the exclusion variable. Leaving them in place “just in case” gives you two sources of truth, which is the condition you started with.

Step 1 is the one people skip and the one that finds things. A five-condition chain evaluated across 400 hosts frequently turns out to match a different set than anyone believed, and discovering that during a refactor is enormously cheaper than discovering it during an incident.

Under the hood

The asymmetry is structural, not incidental.

Host patterns and --limit are resolved by the inventory manager before the play starts. The result is a concrete host list, which is what --list-hosts prints and what serial slices into batches. All of that happens with no connection to any host.

when: is evaluated by the task executor, per host, per task, after the play has selected that host, connected to it and gathered its facts. By then the host list is fixed and the batching is decided.

So the two mechanisms operate at different times against different data, and no amount of cleverness in a when: can inform a decision that was already made. A conditional cannot shrink a serial batch, cannot change what --list-hosts reported, and cannot make --limit target the affected subset — because all three finished before it ran.

This also explains why group_names and inventory_hostname are readable inside a when: and yet using them there is the anti-pattern: the data is inventory data, available at inventory time, being consumed several stages too late to be useful for targeting.

What happens if a host belongs to two groups with conflicting group_vars?

The variable is resolved by the precedence rules from Part XIII, and you get one value with no warning that there was a contest.

Groups at the same depth merge alphabetically by group name, last one loaded winning. A parent-child relationship is different: the child always beats the parent, regardless of ansible_group_priority.

This is the honest cost of the refactor. Conditionals are explicit about their logic and opaque about their target set; groups are explicit about their target set and can be subtle about which value wins.

The mitigations are the ones Part XIII already prescribed, and they matter more once you are pushing logic into inventory:

One default, in role defaults/. Then a group_vars entry is always an override, never a competing default.
Groups that mean one thing. A host in webservers and metrics_collectors_v2 should get web policy from one and collector policy from the other, with no variable in both. Overlapping groups that both set service_port is a design error.
ansible-inventory --host <name> as a routine check, which reports the resolved inventory contribution for that host and turns a guess into an observation.

Knowledge check

Why this matters

This lesson is where conditionals meet the argument the whole course is organised around.

Ansible gives you excellent tools for restricting reach, and every one of them works on the inventory. A when: chain quietly moves the targeting decision somewhere none of those tools can see, and the cost is not felt on the day it is written. It is felt the first time somebody needs to canary a change, or stage a rollout, or answer “how many hosts will this touch” before a change advisory board, and finds that the honest answer is “we will know afterwards”.

The refactor is not always worth doing and this lesson has been specific about when it is not. But the diagnosis is worth applying every time: if a task needs several conditions to decide whether it applies to a host, that is not complex logic, it is a group that was never created.

Inventory is the blast radius map. Logic that decides which hosts are affected belongs on the map.