Ansible Learning Notes - Patterns for Targeting Hosts and Groups

Chinese-English Glossary

English	Chinese	Notes
host	主机
group	（主机）组
pattern	模式
ad hoc	特别命令
playbook	剧本	Ansible proper noun, a complex orchestration piece
inventory	库存	Ansible proper noun
flag	标志
alias	别名

Patterns: Targeting Hosts and Groups

When you execute Ansible through an ad hoc command or run a playbook, you must choose which managed nodes or groups to target. Patterns allow you to run commands and playbooks against specific hosts and/or groups in your inventory. Ansible patterns can reference a single host, an IP address, an inventory group, a set of groups, or all hosts in the inventory. Patterns are highly flexible — you can exclude or require subsets of hosts, use wildcards or regular expressions, and more. Ansible executes on all inventory hosts included in the pattern.

Using Patterns

You use patterns almost every time you execute an ad hoc command or a playbook. The pattern is the only element in an ad hoc command without a flag. It is typically the second element:

ansible <pattern> -m <module_name> -a "<module options>"

For example:

ansible webservers -m service -a "name=httpd state=restarted"

│ ⚠️ Note:
│
│ If your shell is zsh, needs to be enclosed in double quotes, as follows:
│ - ✅ ansible “component*” -m ping
│ - ❌ ansible component* -m ping — this will produce the error: “zsh: no matches found: component*”

In a playbook, the pattern is the content of the hosts: line for each play:

- name: <play_name>
  hosts: <pattern>

For example:

- name: restart webservers
  hosts: webservers

Since you often want to run commands or playbooks against multiple hosts at once, patterns usually reference inventory groups. Both the ad hoc command and the playbook above will execute against all machines in the webservers group.

Common Patterns

This table lists common patterns for targeting inventory hosts and groups.

Description	Pattern	Target
All hosts	all (or )
One host	host1
Multiple hosts	host1:host2 (or host1,host2)
One group	webservers
Multiple groups	webservers:dbservers	All hosts in the webservers group plus all hosts in dbservers
Excluding groups	webservers:!atlanta	All hosts in webservers that are not in the atlanta group
Group intersection	webservers:&staging	All hosts that are in both webservers and staging

│ ✍️ Notes:
│
│ You can use either a comma (,) or a colon (:) to separate host lists. Commas are preferred when dealing with ranges and IPv6 addresses.

Once you know the basic patterns, you can combine them. For example:

webservers:dbservers:&staging:!phoenix

This targets all machines in the “webservers” and “dbservers” groups that are also in the “staging” group, except for machines in the “phoenix” group.

You can use wildcard patterns with FQDNs or IP addresses, as long as the hosts in the inventory are named by FQDN or IP address:

192.0.\*
\*.example.com
\*.com

You can also mix wildcard patterns and groups:

one*.com:dbservers

Pattern Limitations

Patterns depend on the inventory. If a host or group is not listed in your inventory, you cannot use a pattern to target it. If your pattern includes an IP address or hostname that does not appear in the inventory, you will see an error like this:

[WARNING]: No inventory was parsed, only implicit localhost is available
[WARNING]: Could not match supplied host pattern, ignoring: *.not_in_inventory.com

Your pattern must match the inventory syntax. If you define a host as an alias:

atlanta:
  host1:
    http_port: 80
    maxRequestsPerChild: 808
    host: 127.0.0.2

You must use the alias in the pattern. In the example above, you must use host1 in the pattern. If you use the IP address, you will get an error again:

[WARNING]: Could not match supplied host pattern, ignoring: 127.0.0.2

Advanced Pattern Options

The common patterns described above will meet most of your needs, but Ansible offers several other ways to define the hosts and groups you want to target.

Using Variables in Patterns

You can use variables to pass group specifiers to ansible-playbook via the -e argument:

webservers:!{{ excluded }}:&{{ required }}

Using Group Positions in Patterns

You can define a host or a subset of hosts based on their position in a group. For example, given the following group:

[webservers]
cobweb
webbing
weber

You can use subscripts to select individual hosts or ranges within the webservers group:

webservers[0]       # == cobweb
webservers[-1]      # == weber
webservers[0:2]     # == webservers[0],webservers[1]
                    # == cobweb,webbing
webservers[1:]      # == webbing,weber
webservers[:3]      # == cobweb,webbing,weber

Using Regular Expressions in Patterns

You can specify a pattern as a regular expression by starting it with ~:

~(web|db).*\.example\.com

Patterns and ansible-playbook Flags

You can use command-line options to change the behavior of patterns defined in a playbook. For example, you can run a playbook that defines all hosts on a single host by specifying -i 127.0.0.2, (note the trailing comma). This works even if the target host is not defined in your inventory. You can also use the --limit flag to restrict your target hosts:

ansible-playbook site.yml --limit datacenter2

Finally, you can use --limit to read a host list from a file by prefixing the filename with @:

ansible-playbook site.yml --limit @retry_hosts.txt

If RETRY_FILES_ENABLED is set to True, ansible-playbook will create a .retry file after running, containing a list of all failed hosts across all plays. This file is overwritten at the end of each ansible-playbook run.

ansible-playbook site.yml –limit @site.retry

To apply your knowledge of patterns with Ansible commands and playbooks, read the Introduction to ad hoc commands and Introduction to playbooks.