Anti-pattern: encoding the inventory in when · Ansible

Ansible gives you two places to express “which hosts get what”: the inventory, and conditionals in the play. The inventory is declarative, inspectable and reviewable. Conditionals are none of those, and they are always closer to hand.

So the logic migrates. One when: at a time, each perfectly reasonable in isolation.

What it looks like

Service impact possiblethe anti-pattern - a real shape from a real repository— SERVICE-IMPACT: writes configuration and restarts a service. Which hosts each task touches is not determinable by reading.

- name: Configure the application
hosts: all
tasks:
  - name: Set the worker count
    ansible.builtin.template:
      src: app.conf.j2
      dest: /etc/app/app.conf
    vars:
      workers: "{{ 16 if inventory_hostname is match('web(0[1-9]|1[0-2])\\..*')
                   else 4 }}"
    when:
      - inventory_hostname is match('^(web|api)')
      - inventory_hostname not in ['web07.example.com', 'api03.example.com']
      - ansible_facts['distribution_major_version'] | int >= 9
      - not (inventory_hostname is match('.*-canary$') and skip_canary | default(false))

  - name: Apply the legacy tuning
    ansible.builtin.template:
      src: legacy-tuning.conf.j2
      dest: /etc/sysctl.d/99-app.conf
    when: inventory_hostname in ['web03.example.com', 'web04.example.com',
                                 'db01.example.com']
    notify: Restart app

Every line arrived for a reason. web07 had an incident. Version 8 hosts need different handling. The canary needed an escape hatch during a rollout that finished eighteen months ago.

The failure: nobody can answer the targeting question

The question this course opens with — which hosts does this change touch? — is unanswerable here without running the play.

--list-hosts does not help. It reports the play’s host pattern, which is all. It knows nothing about task-level conditionals.

--check on one host proves nothing about the others. The conditional depends on the hostname and on facts, so a successful check against web01 tells you nothing about web07, api03 or the version-8 hosts. Verifying the change means check-running the whole fleet and reading three hundred results.

Review is not possible. A reviewer would have to evaluate four conditions against three hundred hostnames and their facts, in their head. They will approve it instead.

The exclusion list is unmaintainable. web07 is excluded. Why? The commit message says “fix web07”. The person who wrote it has left. Is the reason still true? Nobody will ever remove it, and it will silently stop applying when web07 is rebuilt with a different name.

The corrected form

Move the logic into the inventory, where it is data.

Read-only / Safeinventory/hosts.yml - the conditions become groups— Read-only: file contents. Group membership is inspectable with ansible-inventory before anything runs.

all:
children:
  app_tier:
    children:
      web:
        hosts:
          web[01:12].example.com:
      api:
        hosts:
          api[01:04].example.com:
  high_capacity:
    hosts:
      web[01:12].example.com:
  legacy_tuning:
    hosts:
      web03.example.com:
      web04.example.com:
      db01.example.com:
  excluded_from_app_config:
    # web07: hardware fault under investigation, ticket OPS-4412,
    # review 2026-09-01. api03: pending decommission.
    hosts:
      web07.example.com:
      api03.example.com:

Read-only / Safegroup_vars, and a play that reads— Read-only: file contents. The play now states what it does; the inventory states who it does it to.

# group_vars/app_tier.yml
workers: 4

# group_vars/high_capacity.yml
workers: 16

# site.yml
- name: Configure the application
hosts: 'app_tier:!excluded_from_app_config'
tasks:
  - name: Set the worker count
    ansible.builtin.template:
      src: app.conf.j2
      dest: /etc/app/app.conf

- name: Apply the legacy tuning
hosts: legacy_tuning
tasks:
  - name: Install the sysctl drop-in
    ansible.builtin.template:
      src: legacy-tuning.conf.j2
      dest: /etc/sysctl.d/99-app.conf
    notify: Restart app

Now the question has an answer, before anything runs:

Read-only / Safethe targeting question, answered by a read-only command— READ-ONLY: both commands parse the inventory and print. Neither connects to anything.

# Which hosts are in each group?
ansible-inventory -i inventory/ --graph

# Exactly who does this play target, with the exclusion applied?
ansible-playbook site.yml --list-hosts

# What does a specific host resolve to?
ansible-inventory -i inventory/ --host web03.example.com

The exclusion is now a group with a comment carrying a ticket number and a review date. It is still an exception — but it is a documented, greppable, reviewable one, which is the whole difference.

Three structural failures that travel with it

One monolithic playbook, no roles

A 900-line site.yml with no roles has the same reviewability problem at a different scale: no unit of the automation has a name, an interface, defaults or a boundary, so nothing can be reasoned about, tested or reused in isolation. Part XXII covers the refactor.

Hundreds of trivial roles

The overcorrection, and it is genuinely worse in one respect. A role per task — install-nginx, start-nginx, configure-nginx — gives you all the ceremony of roles with none of the encapsulation, plus a dependency graph nobody can hold in their head and a requirements.yml with two hundred entries.

The heuristic that separates them: a role should own a service or a concern, and should be usable on its own. nginx is a role. start-nginx is a task.

`-e` overriding everything

Extra-vars sit at the top of the precedence order and cannot be overridden by anything. That makes -e the universal fix for a variable that resolved wrongly — and the reason nobody can predict what a value will be.

Service impact possiblethe invocation that defeats every layer below it— SERVICE-IMPACT: runs against production with overridden values. Nothing in the repository records that these values were used.

ansible-playbook site.yml -e workers=32 -e app_version=2.1.0   -e skip_canary=true -e max_hosts=9999

The failure. The run happened with values that exist only in one person’s shell history. The repository does not describe what was deployed. A rerun without the same flags produces a different result, which means the run is not reproducible — and when somebody reruns it to recover from an incident, they get the un-overridden values.

The corrected form. Put the value where its precedence layer belongs: a group variable if it is a property of those hosts, a play vars: if it is a property of that play, a role default if it is an interface. Reserve -e for genuinely per-invocation values — a version being deployed, an acknowledgement flag — and pass them from a file that is committed:

Service impact possiblean override that leaves a record— SERVICE-IMPACT: still a real run. The difference is that the values are in a file the repository holds, so the run is reproducible and reviewable.

# releases/2026-08-11-app-2.1.0.yml holds the values, and is committed.
ansible-playbook site.yml --limit app_prod   -e @releases/2026-08-11-app-2.1.0.yml

Part XIII covers precedence in full, including the incident lesson on what happens when it is misused.

Under the hood

Why does inventory logic reviewed as data behave so differently from the same logic reviewed as conditionals?

Because of when it is evaluated, and what is available at that moment.

Inventory is resolved before the play starts. ansible-inventory and --list-hosts can produce the complete answer without connecting to anything, because group membership is a function of the inventory files alone. That is what makes it inspectable: the answer exists as a value you can print.

A task-level when: is evaluated per host, at the moment the task reaches that host, against that host’s full variable context — including facts gathered from the machine seconds earlier. There is no point before execution at which the answer exists, because part of the input does not exist yet. --list-tasks shows the tasks; it cannot show which hosts will run them.

This also explains the check-mode asymmetry. A check run does evaluate conditionals, so it does tell you what would happen — but only for the hosts you ran it against, and only with the facts they had at that moment. Checking one host from a group of three hundred proves something about one host. When targeting is expressed as group membership, checking one host from a group tells you about the group, because membership was determined by the same data for all of them.

The general principle underneath: push decisions as early in the pipeline as they can be made. A decision made in the inventory is visible to --list-hosts, to review, to a diff and to a grep. The same decision made at task-execution time is visible only to the run itself, and only afterwards.

What happens if the condition genuinely depends on a fact, not on a decision?

Then it is a conditional, and it is correct. when: ansible_facts['distribution_major_version'] | int >= 9 is a real runtime property that the inventory cannot know.

Three things still improve it.

Name the condition. A set_fact with a meaningful name turns an expression into a documented concept:

- name: Determine whether this host supports the new config format
  ansible.builtin.set_fact:
    supports_new_format: >-
      {{ ansible_facts['distribution_major_version'] | int >= 9 }}

Then when: supports_new_format reads as intent rather than as arithmetic, and there is one place to change it.

Consider a constructed group. The constructed inventory plugin builds groups from facts, so distribution_major_version >= 9 can become membership of an os_modern group — which puts a fact-derived decision back into the inspectable layer. It requires cached facts to be useful before a run, which is Part XXXIV’s subject, and it is the strongest version of the fix.

Check the mixture. The anti-pattern is rarely a pure fact condition; it is a fact condition with three hostname exclusions bolted on. Split them: the fact part stays a when:, the decision part becomes group membership. That single split usually removes most of the unreviewable surface, because the fact conditions are typically one clause and the decisions are the other three.

Knowledge check

Why this matters

This course has one organising question and it is a targeting question: which hosts does this change touch? Every control it teaches — --limit, --list-hosts, serial, canaries, guardrails — assumes that question can be answered before the run.

Inventory logic in conditionals removes the answer. Not by making it wrong, but by making it computable only by execution, which means --list-hosts reports the play pattern rather than the effect, a check against one host generalises to nothing, and the reviewer approves a change they could not have evaluated.

Everything downstream degrades quietly. The canary is no longer representative, because it may not match the same conditions as the rest. The guardrail counts hosts in the play, not hosts the task will touch. The change record says hosts: all and means something else.

The fix is not more sophisticated. It is less: put the decisions in the inventory as data, where a command can print them and a diff can show them, and leave the conditionals for things that are genuinely discovered at run time. The playbook then says what it does, the inventory says who it does it to, and the question this course is built around has an answer again.