ansible_play_hosts, ansible_play_batch and friends · Ansible

Everything so far has verified scope from outside the play, before it runs. This lesson is the inside view: how a play answers “how big am I” about itself, while executing.

That matters because a guardrail written in a playbook travels with the playbook. A wrapper script protects the runs that go through the wrapper; an assertion inside the play protects every run, including the one somebody types by hand at two in the morning.

Three variables carry the answer, and they are close enough in name that picking the wrong one produces a guardrail that quietly never fires.

Variable	Contains
`ansible_play_hosts_all`	Every host the play selected, fixed for the whole play
`ansible_play_hosts`	Hosts still active — the above, minus failed and unreachable
`ansible_play_batch`	The hosts in the current `serial` batch

Under `serial`, verified

The common misreading is that ansible_play_hosts narrows to the current batch. It does not.

Read-only / Safescope.yml— Read-only: debug connects to nothing and changes nothing. serial: 2 over a four-host group gives two batches.

- name: Show the scope variables
hosts: web
gather_facts: false
serial: 2
tasks:
  - name: Report scope
    run_once: true
    ansible.builtin.debug:
      msg:
        - "play_hosts_all={{ ansible_play_hosts_all }}"
        - "play_hosts={{ ansible_play_hosts }}"
        - "play_batch={{ ansible_play_batch }}"

Read-only / Safetwo batches, three variables— Real output from ansible-core 2.21.3. Read the middle line of each block: play_hosts is all four hosts in both batches. Only play_batch narrows.

$ ansible-playbook -i inventory/hosts.yml scope.yml

PLAY [Show the scope variables] ************************************************

TASK [Report scope] ************************************************************
ok: [web01.example.com] => {
  "msg": [
      "play_hosts_all=['web01.example.com', 'web02.example.com', 'web03.example.com', 'web04.example.com']",
      "play_hosts=['web01.example.com', 'web02.example.com', 'web03.example.com', 'web04.example.com']",
      "play_batch=['web01.example.com', 'web02.example.com']"
  ]
}

PLAY [Show the scope variables] ************************************************

TASK [Report scope] ************************************************************
ok: [web03.example.com] => {
  "msg": [
      "play_hosts_all=['web01.example.com', 'web02.example.com', 'web03.example.com', 'web04.example.com']",
      "play_hosts=['web01.example.com', 'web02.example.com', 'web03.example.com', 'web04.example.com']",
      "play_batch=['web03.example.com', 'web04.example.com']"
  ]
}

Note also that the PLAY header appears twice. Under serial, each batch is its own execution of the play — which is why handlers flush per batch and why a failure in batch one stops batch two from starting.

After a failure, verified

ansible_play_hosts is the one that changes during the play. Here a mid-play task fails on one host:

Read-only / Safeone host drops out— Real output from ansible-core 2.21.3. Before the failing task, play_hosts is four. After it, three - web02 has left. play_hosts_all is four throughout.

$ ansible-playbook -i inventory/hosts.yml shrink.yml

TASK [Report before] ***********************************************************
ok: [web01.example.com] => {
  "msg": "before: play_hosts=4 play_hosts_all=4"
}

TASK [Fail on web02] ***********************************************************
fatal: [web02.example.com]: FAILED! => {
  "assertion": "inventory_hostname != 'web02.example.com'",
  "msg": "deliberate"
}

TASK [Report after] ************************************************************
ok: [web01.example.com] => {
  "msg": "after: play_hosts=['web01.example.com', 'web03.example.com', 'web04.example.com'] play_hosts_all=4"
}

That is what “still active” means, and it makes ansible_play_hosts the right variable for a different question: how much of the fleet is still healthy partway through a rollout.

Read-only / Safea mid-rollout health gate— Read-only. Placed between phases of a play, this stops a rollout that has quietly lost a quarter of its hosts even though no individual failure was fatal.

- name: Stop if too much of the fleet has dropped out
run_once: true
ansible.builtin.assert:
  that:
    - (ansible_play_hosts | length) >= (ansible_play_hosts_all | length * 0.8)
  fail_msg: >-
    Only {{ ansible_play_hosts | length }} of
    {{ ansible_play_hosts_all | length }} hosts are still active.
    Halting before the next phase.

Choosing the right one

The question you are asking	The variable
How many hosts can this run possibly affect?	`ansible_play_hosts_all`
Is this run wider than the change ticket says?	`ansible_play_hosts_all`
How much of the fleet is still healthy right now?	`ansible_play_hosts`
Have too many hosts dropped out to continue?	`ansible_play_hosts`
Is this batch too large, or does it hold two quorum members?	`ansible_play_batch`
Which host am I?	`inventory_hostname`

`inventory_hostname` is not `ansible_hostname`

A related pair, and confusing them produces bugs that only appear on some hosts.

inventory_hostname is the name this host has in the inventory. It always exists, it never requires a connection, and it is what patterns, group_vars filenames and --limit all match against.

ansible_hostname is a gathered fact — the short hostname the machine reports about itself. It requires gather_facts: true and a successful connection, and it can differ from the inventory name for entirely ordinary reasons: the inventory uses an FQDN and the host is configured with a short name, the inventory uses an alias with ansible_host pointing elsewhere, the machine was rebuilt and renamed.

Read-only / Safethe two can disagree, legitimately

inventory entry:   web01.example.com
ansible_host:      192.0.2.11
inventory_hostname web01.example.com     always available
ansible_hostname   web01                 requires gather_facts
ansible_fqdn       web01.example.com     requires gather_facts

The rule that avoids the whole class of bug: use inventory_hostname for anything to do with identity, targeting, grouping or file naming, and ansible_hostname only when you genuinely need what the machine calls itself — writing its own hostname into a config file it serves, for instance.

A conditional written as when: ansible_hostname == 'web01' breaks silently on any host whose configured name differs from its inventory name, and works everywhere you tested. inventory_hostname has no such failure mode, and works with gather_facts: false.

Under the hood

These are magic variables: they are not gathered facts and not inventory variables, but values injected by the executor into the templating context for each task.

Two properties follow.

They cannot be set, and setting them silently does nothing useful. A set_fact named ansible_play_hosts does not change which hosts the play runs on. The play’s host list was decided before the first task ran; the variable reports it.

They are evaluated per task, not per play. This is why ansible_play_hosts shrinks between two tasks in the same play, and it means an assertion placed early sees a different value from the same assertion placed late. For a blast-radius ceiling, early is correct: you want to refuse before anything has changed.

Two more magic variables are worth knowing alongside these, because they answer questions the three above do not:

groups — a dictionary of every group in the inventory to its members, regardless of whether they are in this play. This is how a play checks something about hosts it is not targeting, such as whether its target set intersects a protected group.
group_names — the list of groups the current host belongs to. when: "'do_not_automate' not in group_names" is a per-host guard, and unlike a pattern exclusion it cannot be lost when somebody edits the hosts: line.

Finally, the naming history, because it is actively misleading. The bare play_hosts still works and is an alias for ansible_play_batch, not for ansible_play_hosts:

Read-only / Safewhat play_hosts actually is— Real output from ansible-core 2.21.3 under serial: 2. play_hosts equals ansible_play_batch, and the deprecation warning names the removal version.

$ ansible-playbook -i inventory/hosts.yml legacy.yml

[DEPRECATION WARNING]: The `play_hosts` magic variable is deprecated. This
feature will be removed from ansible-core version 2.23.
  "msg": "play_hosts=['web01.example.com', 'web02.example.com'] ansible_play_batch=['web01.example.com', 'web02.example.com']"
  "msg": "play_hosts=['web03.example.com', 'web04.example.com'] ansible_play_batch=['web03.example.com', 'web04.example.com']"

Code that reads play_hosts expecting “all the hosts in the play” is reading the batch. Any surviving use of it is something to replace rather than trust, and it is scheduled for removal in 2.23 regardless.

What happens if you use these with run_once?

run_once: true makes a task execute on the first host of the batch and apply its result to the others. Combined with these variables that is usually what you want for an assertion — you want the check evaluated once, not once per host — but there is a wrinkle worth knowing.

Under serial, run_once means once per batch, not once per play. A run_once assertion in a serial: 2 play over ten hosts runs five times. For a ceiling assertion that is harmless: ansible_play_hosts_all is the same value every time, so the check simply passes or fails identically five times over.

It stops being harmless when the run_once task has a side effect — sending a notification, taking a lock, writing a marker. Five notifications instead of one is the visible version; a lock taken per batch is the version that causes an incident.

If you need genuinely once per playbook rather than once per batch, put the task in its own play without serial, before the play that does the work. That is the shape the pre-flight guard in the next lesson uses, and the reason it is a separate play rather than a first task.

Knowledge check

Why this matters

A guardrail in a wrapper script protects the runs that go through the wrapper. A guardrail inside the play protects every run — the scheduled one, the one from CI, and the one somebody types by hand during an incident when the wrapper is the last thing on their mind.

These variables are what makes the second kind possible. They let a play state its own limits: this play must not exceed N hosts, this play must not touch anything in the protected group, this rollout must stop if more than a fifth of the fleet has dropped out.

Which makes picking the right one load-bearing. A ceiling asserted against ansible_play_batch under serial is a guard that runs, passes and protects nothing — and it looks exactly like one that works. The next lesson assembles these into the pre-flight block that this part has been building towards.

Under serial, verified

After a failure, verified

Choosing the right one

inventory_hostname is not ansible_hostname

Knowledge check

Under `serial`, verified

`inventory_hostname` is not `ansible_hostname`