Verifying the effective host list before you run

This is the skill the part exists to teach.

Before you run something that changes hosts, determine exactly which hosts it will change — from the command line, not from belief.

It takes about four seconds, connects to nothing, and is the only control that catches every targeting mistake in this part at once: a mistyped group, an exclusion that did not fire, a glob that reached staging, a dynamic source that grew, a --limit that intersected to nothing.

The commands are simple. The discipline is running the right one and comparing the count against a number you decided beforehand.

The authoritative command

ansible-playbook -i inventory/ site.yml --limit 'us_east:!canary' --list-hosts

It is authoritative because it accounts for both halves of the target: the play’s own hosts: line, and your --limit. Every other form accounts for one of them.

$ ansible-playbook -i inventory/hosts.yml site.yml --limit eu_west --list-hosts

playbook: site.yml

play #1 (web): Configure the web tier	TAGS: []
  pattern: ['web']
  hosts (1):
    web01.example.com

play #2 (db): Configure the database tier	TAGS: []
  pattern: ['db']
  hosts (1):
    db01.example.com

Read three things from that output:

• The pattern: line is the play’s own hosts: value, unmodified.
• The hosts (N): count is the effective blast radius for that play.
• The number of plays — a site.yml with nine plays has nine separate answers, and the total is their union, not any single one.

The trap: --graph ignores --limit

This one has a specific name because it catches people who are doing the right thing.

$ ansible-inventory -i inventory/hosts.yml --graph --limit canary

@all:
|--@ungrouped:
|--@production:
|  |--@web:
|  |  |--web01.example.com
|  |  |--web02.example.com
|  |  |--web03.example.com
|  |  |--web04.example.com
|  |--@db:
|  |  |--db01.example.com
|  |  |--db02.example.com
|  |--@cache:
|  |  |--cache01.example.com
|--@staging:
|  |--@web_stage:
|  |  |--stage-web01.example.com
|  |  |--stage-web02.example.com
|  |--@db_stage:
|  |  |--stage-db01.example.com
|--@eu_west:
...

This is documented, not a bug. The tool says so in its own help:

$ ansible-inventory --help

Actions:
One of following must be used on invocation, ONLY ONE!

--graph               create inventory graph, if supplying pattern it must
                      be a valid group name. It will ignore limit
--host HOST           Output specific host info, works as inventory script.
                      It will ignore limit
--list                Output all hosts info, works as inventory script

--list does honour it:

$ ansible-inventory -i inventory/hosts.yml --list --limit canary --yaml

all:
children:
  canary:
    hosts:
      web01.example.com: {}
  eu_west:
    hosts:
      web01.example.com: {}
  production:
    children:
      web:
        hosts:
          web01.example.com:
            ansible_host: 192.0.2.11

The other half of scope: which tasks

Knowing the hosts answers half the question. --list-tasks answers the other half, and it resolves includes, imports and roles rather than showing you the file.

$ ansible-playbook -i inventory/hosts.yml site.yml --list-tasks

playbook: site.yml

play #1 (web): Configure the web tier	TAGS: []
  tasks:
    Install the package	TAGS: [packages]
    Render the configuration	TAGS: [config]
    Restart the service	TAGS: [config, restart]

play #2 (db): Configure the database tier	TAGS: []
  tasks:
    Tune the database	TAGS: [config]

It honours --tags, which is how you verify that a tagged run does what you think:

$ ansible-playbook -i inventory/hosts.yml site.yml --list-tasks --tags config

  play #1 (web): Configure the web tier	TAGS: []
  tasks:
    Render the configuration	TAGS: [config]
    Restart the service	TAGS: [config, restart]

play #2 (db): Configure the database tier	TAGS: []
  tasks:
    Tune the database	TAGS: [config]

--list-tags gives the vocabulary rather than the tasks — useful when somebody hands you an unfamiliar playbook and a ticket saying “run it with the config tag”:

$ ansible-playbook -i inventory/hosts.yml site.yml --list-tags

  play #1 (web): Configure the web tier	TAGS: []
    TASK TAGS: [config, packages, restart]

play #2 (db): Configure the database tier	TAGS: []
    TASK TAGS: [config]

The four commands, and what each is for

1. Decide the number first. "This should hit about twelve hosts" is the expectation, and it has to exist before the output does.
2. Build the exact command you intend to run, then append --list-hosts.
3. Read the count on each play. Compare it with the number from step one. A mismatch stops here.
4. Spot-check the list itself for a host that should not be there, especially one from a different environment.
5. Append --list-tasks instead, and confirm the task set matches the change you think you are making, including under any --tags.
6. Remove the --list flag and run, with --check --diff first if the change is not trivially reversible.

Step one is the step people skip, and it is the one that makes the rest work. The output is not self-validating: twelve hosts and three hundred hosts look equally reasonable on screen. Only the comparison against a prior expectation turns the number into information.

Knowledge check