How Ansible evaluates a pattern · Ansible

A pattern with three operators looks like an expression, and expressions usually evaluate left to right. This one does not, and the difference is the reason exclusions can be trusted.

A pattern is evaluated in three phases: every plain term is unioned, then every & term is intersected, then every ! term is removed. The order the terms appear in the string is irrelevant.

That last clause is the surprising half, and it has a direct safety consequence: !do_not_automate protects those hosts no matter where in the pattern it appears and no matter what appears after it.

The demonstration

One target set, six ways of writing the same three terms — web, minus the canary group, intersected with us_east:

Read-only / Safesix permutations, one answer— Real output from ansible-core 2.21.3, one line per pattern. Every permutation of the same three terms produces the same three hosts.

$ for p in 'web:!canary:&us_east' '&us_east:web:!canary' '!canary:&us_east:web' 'web:&us_east:!canary' '!canary:web:&us_east' '&us_east:!canary:web'; do ansible -i inventory/hosts.yml "$p" --list-hosts; done

web:!canary:&us_east    ->  hosts (3): web02 web03 web04
&us_east:web:!canary    ->  hosts (3): web02 web03 web04
!canary:&us_east:web    ->  hosts (3): web02 web03 web04
web:&us_east:!canary    ->  hosts (3): web02 web03 web04
!canary:web:&us_east    ->  hosts (3): web02 web03 web04
&us_east:!canary:web    ->  hosts (3): web02 web03 web04

Note the third and fifth: a pattern that begins with ! is legal and works. There is no requirement that a positive term come first, because the positive terms are gathered independently of where they sit.

Working the phases by hand on the first form:

Read-only / Safeweb:!canary:&us_east, phase by phase

phase 1, union of plain terms
web            -> web01, web02, web03, web04

phase 2, intersect with every & term
&us_east       -> us_east is web02, web03, web04, db02
                  intersection -> web02, web03, web04

phase 3, remove every ! term
!canary        -> canary is web01
                  web01 is already gone; no change
                  result -> web02, web03, web04

And on &us_east:!canary:web, which reads as though it starts with an intersection against nothing:

Read-only / Safe&us_east:!canary:web, phase by phase

phase 1, union of plain terms
web            -> web01, web02, web03, web04     (the only plain term)

phase 2, intersect
&us_east       -> web02, web03, web04

phase 3, remove
!canary        -> no change

result -> web02, web03, web04     (identical)

The phases are what make them equal. There is no point at which “the current set” is empty because an & came first, because & terms are not applied until every plain term has been collected.

An exclusion cannot be cancelled

This is the property to remember, and it is worth proving rather than asserting.

Read-only / Safenaming the excluded host again does not re-add it— Real output from ansible-core 2.21.3. web01 is in canary. Naming it explicitly as a union term after the exclusion does not bring it back - three hosts, not four.

$ ansible -i inventory/hosts.yml 'web:!canary:web01.example.com' --list-hosts

  hosts (3):
  web02.example.com
  web03.example.com
  web04.example.com

Read-only / Safenor does naming the group again— Real output from ansible-core 2.21.3. Same three hosts. The union phase added web01 twice and the exclusion phase removed it once, which is enough.

$ ansible -i inventory/hosts.yml 'web:!canary:canary' --list-hosts

  hosts (3):
  web02.example.com
  web03.example.com
  web04.example.com

The corollary: you cannot express “except, but include”

The same property has a cost, and it is worth knowing before you spend twenty minutes trying to write around it.

There is no way, within a single pattern, to say “all the staging hosts except the database ones, but do include stage-db01 specifically”. Once db_stage is excluded, stage-db01 is gone, and adding it back as a union term does nothing.

Three ways out, in order of preference:

Fix the inventory. If you routinely need "db_stage except one host", that host belongs in its own group. A pattern working around inventory structure is a sign the structure is wrong.
Use two plays. One targeting the broad set with the exclusion, one targeting the exception, with the tasks factored into a role so they do not diverge.
Use --limit with an explicit host list, or a limit file. The pattern stays honest and the narrowing happens at invocation time, where a reviewer can see it.

The first is the right answer surprisingly often. A pattern that needs an exception is usually describing a group that the inventory does not have a name for yet, and naming it is both cheaper and more readable than a clever expression nobody can parse six months later.

Under the hood

The implementation is a small loop, and knowing its shape explains several behaviours at once.

Ansible splits the pattern string on : and ,, then classifies each term by its first character — &, !, or neither. It resolves every term to a set of hosts. Then it walks the terms and, for each one, either adds to the accumulating set, intersects the accumulating set with it, or subtracts it.

The reason position does not matter is that intersection and subtraction are both applied against the accumulated union, and because a set intersection is commutative, the sequence of & operations does not change the result either. Subtraction last is the only ordering guarantee that has to be built in deliberately, and it is.

Two consequences worth naming:

A term that resolves to nothing is not neutral in the same way for each operator. An unmatched plain term contributes nothing to the union — harmless, the run does less than asked. An unmatched ! term subtracts nothing — dangerous, the run does more than asked. An unmatched & term intersects against nothing and empties the result entirely, so web:&nosuchgroup is zero hosts. All three produce the same “Could not match supplied host pattern” warning and the same exit code, and only the second one enlarges the target set — which is why the previous lesson singled it out.

Duplicate hosts are collapsed. The result is a set, so a host appearing via three different group terms appears once. This is why web:web:web is four hosts and not twelve, and why unioning overlapping groups is always safe to do.

What happens if the intersection is empty?

You get zero hosts, one warning, and exit 0 — and importantly a different warning from the typo case, which is a useful diagnostic.

Read-only / Safean intersection with no overlap— Real output from ansible-core 2.21.3. Both web and db exist and both have members. There is simply no host in both. One warning line, not two.

$ ansible -i inventory/hosts.yml 'web:&db' --list-hosts

[WARNING]: No hosts matched, nothing to do
hosts (0):

Compare that with a pattern containing a name that does not exist:

Read-only / Safea name that does not exist— Real output from ansible-core 2.21.3. Two warnings: one naming the unmatched term, one saying nothing matched overall.

$ ansible -i inventory/hosts.yml 'nosuchgroup' --list-hosts

[WARNING]: Could not match supplied host pattern, ignoring: nosuchgroup
[WARNING]: No hosts matched, nothing to do
hosts (0):

Two warnings means a term did not resolve — a typo, or a group that was renamed. One warning means every term resolved and the set arithmetic produced nothing — a genuine empty intersection, or an exclusion that removed everything.

That distinction is worth internalising because it tells you which direction to investigate. ansible-inventory --graph settles it in either case: check whether the group exists at all, then check its members.

Both cases exit 0, which is a separate problem and the subject of lesson 6.

Knowledge check

Why this matters

Patterns get edited. Somebody adds a region, somebody appends a group, somebody copies a pattern from one playbook into another and extends it. If evaluation were left to right, every one of those edits could silently undo an exclusion written months earlier by somebody who understood why it was there.

It is not, so they cannot. The exclusion clause in a pattern is the one part that later hands cannot weaken, and that is a property worth relying on deliberately: put :!do_not_automate on every broad-target play and it stays effective through every subsequent edit to that line.

Everything else in the evaluation model follows from the same three phases — including the diagnostic in this lesson, where one warning and two warnings mean genuinely different things, and the fact that an exception to an exclusion is not expressible and should be a group instead.