Host pattern syntax · Ansible

Pattern syntax is the most confidently misremembered part of Ansible. People are sure web[:3] works, sure that a slice is exclusive at the upper bound like Python’s, and sure that an IP glob matches by address. None of those is true in ansible-core 2.21.

So everything below was run. The inventory is ten hosts in overlapping groups, using documentation-reserved addresses, and every output is the real thing:

Read-only / Safeinventory/hosts.yml - the inventory every example uses

all:
children:
  production:
    children:
      web:
        hosts:
          web01.example.com: {ansible_host: 192.0.2.11}
          web02.example.com: {ansible_host: 192.0.2.12}
          web03.example.com: {ansible_host: 192.0.2.13}
          web04.example.com: {ansible_host: 192.0.2.14}
      db:
        hosts:
          db01.example.com: {ansible_host: 192.0.2.21}
          db02.example.com: {ansible_host: 192.0.2.22}
      cache:
        hosts:
          cache01.example.com: {ansible_host: 192.0.2.31}
  staging:
    children:
      web_stage:
        hosts:
          stage-web01.example.com: {ansible_host: 198.51.100.11}
          stage-web02.example.com: {ansible_host: 198.51.100.12}
      db_stage:
        hosts:
          stage-db01.example.com: {ansible_host: 198.51.100.21}
  eu_west:
    hosts: {web01.example.com: , db01.example.com: , cache01.example.com: }
  us_east:
    hosts: {web02.example.com: , web03.example.com: , web04.example.com: , db02.example.com: }
  canary:
    hosts: {web01.example.com: }
  do_not_automate:
    hosts: {db01.example.com: }

Verify anything here yourself with ansible -i inventory/hosts.yml '<pattern>' --list-hosts, which connects to nothing and is the safest command in the course.

The complete vocabulary

Form	Meaning	Example
`all` or `*`	Every host in the inventory	`all`
name	One host, or one group	`web01.example.com`, `web`
`:` or `,`	Union — add	`web:db`
`:&`	Intersection — and	`web:&eu_west`
`:!`	Exclusion — remove	`web:!canary`
`*` inside a name	Glob, over host and group names	`web*`
`~` prefix	Regular expression	`~web0[13]`
`name[n]`	The nth member of a group, zero-based	`web[0]`
`name[n:m]`	Members n to m inclusive	`web[0:2]`
`name[n:]`	From n to the end	`web[1:]`
`name[-1]`	The last member	`web[-1]`

, and : are interchangeable for union. Prefer , when the pattern contains an IPv6 address, since : is ambiguous there; prefer : otherwise for consistency with :& and :!.

Union, intersection, exclusion

The three operators, each against the same inventory.

Read-only / Safeunion - everything in either group— Real output from ansible-core 2.21.3. Four web hosts plus two db hosts. web,db produces exactly the same set.

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

  hosts (6):
  web01.example.com
  web02.example.com
  web03.example.com
  web04.example.com
  db01.example.com
  db02.example.com

Read-only / Safeintersection - in both groups— Real output from ansible-core 2.21.3. Four web hosts, three eu_west hosts, one host in both. This is how you target a role within a region without inventing a combined group.

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

  hosts (1):
  web01.example.com

Read-only / Safeexclusion - everything except— Real output from ansible-core 2.21.3. The canary group holds web01, so web:!canary is the other three. This is the form that keeps a do-not-touch list out of a broad run.

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

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

They combine, and the result does not depend on where in the string each term appears:

Read-only / Safeall three at once— Real output from ansible-core 2.21.3. web, minus the canary, intersected with us_east. The next lesson proves that reordering the terms produces the same answer.

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

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

Globs match group names too

This is the trap that catches experienced people, and it is entirely logical once seen.

Read-only / Safeweb* reaches staging— Real output from ansible-core 2.21.3. Six hosts, not four. stage-web01 and stage-web02 do not match web* by name - but the group web_stage does, and matching a group pulls in its members.

$ ansible -i inventory/hosts.yml 'web*' --list-hosts

  hosts (6):
  web01.example.com
  web02.example.com
  web03.example.com
  web04.example.com
  stage-web01.example.com
  stage-web02.example.com

A pattern is matched against every host name and every group name in the inventory. web* matched the four web*.example.com hosts by name and the web_stage group by name, and a group match contributes all its members.

The operational consequence is direct: a glob you wrote to mean “the web servers” reached staging, and would equally reach production if the groups were named the other way round. Group naming conventions and glob patterns interact, and the interaction is invisible until you print the host list.

Regular expressions

Prefix with ~ and the rest is a Python regular expression:

Read-only / Safea regex over host names— Real output from ansible-core 2.21.3. Two hosts, selected by a character class the glob syntax cannot express.

$ ansible -i inventory/hosts.yml '~web0[13]' --list-hosts

  hosts (2):
  web01.example.com
  web03.example.com

Note what that implies about anchoring. ~web0[13] matched web01.example.com, which the expression does not describe in full — so the match is applied at the start of the name and does not have to consume all of it. The mirror test confirms it:

Read-only / Safea regex that only matches in the middle— Real output from ansible-core 2.21.3. Every host name contains 'example', and none matched - because the expression is anchored at the start. Write ~.*example if you mean a substring.

$ ansible -i inventory/hosts.yml '~example' --list-hosts

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

Read-only / Safean explicit start anchor behaves identically— Real output from ansible-core 2.21.3. ~^web matches six hosts, the same six as the web* glob - because it also matches the web_stage group name. Regex does not exempt you from the group-name rule.

$ ansible -i inventory/hosts.yml '~^web' --list-hosts

  hosts (6):
  web01.example.com
  web02.example.com
  web03.example.com
  web04.example.com
  stage-web01.example.com
  stage-web02.example.com

Indexing and slicing a group

Useful for canaries: “the first host of this group”, without hardcoding which host that is.

Read-only / Safeone member by index— Real output from ansible-core 2.21.3. Zero-based, and the order is inventory order unless the play sets order:.

$ ansible -i inventory/hosts.yml 'web[0]' --list-hosts

  hosts (1):
  web01.example.com

Read-only / Safea slice - and the count is the surprise— Real output from ansible-core 2.21.3. web[0:2] is THREE hosts, not two. Ansible's slice bounds are inclusive at both ends, unlike Python's.

$ ansible -i inventory/hosts.yml 'web[0:2]' --list-hosts

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

An open-ended upper bound works, and behaves as you would expect:

Read-only / Safefrom an index to the end— Real output from ansible-core 2.21.3. web[1:] is everything after the first, which is the natural companion to a web[0] canary.

$ ansible -i inventory/hosts.yml 'web[1:]' --list-hosts

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

Read-only / Safea negative index— Real output from ansible-core 2.21.3. web[-1] is the last member in inventory order.

$ ansible -i inventory/hosts.yml 'web[-1]' --list-hosts

  hosts (1):
  web04.example.com

The forms that are not supported

Verified, because “it looked like it should work” is how these get into production scripts.

Read-only / Safean omitted lower bound is not a pattern— Real output from ansible-core 2.21.3. web[:3] matches nothing at all - not the first three hosts, not an error, just a warning and zero hosts. Write web[0:2] for the first three.

$ ansible -i inventory/hosts.yml 'web[:3]' --list-hosts

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

Read-only / Safenegative slices are not supported either— Real output from ansible-core 2.21.3. web[-2:] and web[-2:-1] both match nothing. A single negative index works; a slice containing one does not.

$ ansible -i inventory/hosts.yml 'web[-2:]' --list-hosts

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

Read-only / Safepatterns match names, not addresses— Real output from ansible-core 2.21.3. Every host in this inventory has an ansible_host in 192.0.2.0/24, and the glob matches none of them - because ansible_host is a connection variable, not the inventory name. An IP glob only works when the inventory names are literally addresses.

$ ansible -i inventory/hosts.yml '192.0.2.*' --list-hosts

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

Read-only / Safematching is case sensitive— Real output from ansible-core 2.21.3. WEB does not match the group web. Worth knowing before somebody types a group name in the case their ticket used.

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

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

Under the hood

Patterns can contain variables, and that is both useful and the sharpest edge in this lesson.

A play can be written hosts: "{{ target_group }}" and invoked with -e target_group=web. It works, and it is how a single playbook serves several tiers.

What makes it sharp is that the variable is resolved before pattern matching, so the safety of the run now depends on a variable’s value. Undefined is handled well:

Read-only / Safean undefined targeting variable stops the run— Real output from ansible-core 2.21.3, with exit code 4. This is the behaviour you want: no value, no run.

$ ansible-playbook -i inventory/hosts.yml var.yml --list-hosts

[ERROR]: Error processing keyword 'hosts': 'target_group' is undefined
Origin: playbooks/var.yml:2:10

1 - name: Variable target
2   hosts: "{{ target_group }}"
         ^ column 10

And then somebody, trying to make the playbook convenient, adds a default:

Read-only / Safethe same playbook with default('all')— Real output from ansible-core 2.21.3, abbreviated. Ten hosts - the entire inventory - because the flag was forgotten. No error, no warning, exit 0.

$ ansible-playbook -i inventory/hosts.yml var2.yml --list-hosts

  play #1 (all): Variable target with default all	TAGS: []
  pattern: ['all']
  hosts (10):

The rule worth adopting: never default a targeting variable to anything, and least of all to all. If the variable is the blast radius, an undefined variable should be a stopped run. mandatory is the filter that says so explicitly:

hosts: "{{ target_group | mandatory }}"

The same reasoning applies to --limit values assembled by a script. The next two lessons deal with limits specifically, and the underlying principle does not change: an expression that decides which machines are touched should fail rather than guess.

What happens if one term in a union has a typo?

The typo is ignored and the rest of the pattern proceeds — which is mostly harmless in a union, and dangerous in an exclusion.

Read-only / Safea typo in a union term— Real output from ansible-core 2.21.3. The bad term is named in a warning and dropped; the good term still resolves. The run does less than you asked, which is the safe direction.

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

[WARNING]: Could not match supplied host pattern, ignoring: nosuchgroup
hosts (4):
  web01.example.com
  web02.example.com
  web03.example.com
  web04.example.com

Now the same typo in an exclusion:

Read-only / Safea typo in an exclusion term— Real output from ansible-core 2.21.3. Identical warning, identical exit code, and all four hosts - because the exclusion excluded nothing. If that term was your do-not-automate list, it just stopped protecting anything.

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

[WARNING]: Could not match supplied host pattern, ignoring: nosuchgroup
hosts (4):
  web01.example.com
  web02.example.com
  web03.example.com
  web04.example.com

This is the one place in the pattern language where a typo fails open. A misspelled :!do_not_automat silently protects nothing, warns in a line nobody reads, and exits 0.

Two defences, and they are cheap. Verify the count — the excluded hosts should be missing, and if the count equals the unexcluded count the exclusion did not fire. And assert the exclusion inside the play, by checking that ansible_play_hosts_all and the protected group do not intersect, which is lesson 8.

Knowledge check

Why this matters

Pattern syntax is the vocabulary in which blast radius is expressed. A run touches the hosts a pattern resolves to, and every misunderstanding in this lesson turns into a difference between what somebody meant and what happened.

Three of them are worth carrying away specifically. A slice is inclusive at both ends, so your canary batch is one host larger than you think. A glob matches group names, so a pattern can reach an environment you never named. And an exclusion with a typo protects nothing while looking exactly like one that works.

All three are invisible in the syntax and obvious in the output. Which is the argument the next three lessons make in different ways: the question “which hosts does this reach” has a command-line answer, and believing you know is not the same as having asked.