The seven things that can happen to a host · Ansible

The PLAY RECAP looks like a scoreboard. It is not. It is seven separate claims about seven different things, and only three of them tell you what state a host is actually in.

You have already met the recap as a report format. This part uses it as an evidence source — the thing you read at 03:00 when a change went wrong across a fleet and someone needs to know what to do next. That reading requires a much more precise vocabulary than “220 passed, 80 did not”, because the eighty are not one population and treating them as one is how a partial failure becomes an outage.

The question each counter answers

Every counter answers one question: after this run, what do I know about this host?

Counter	Did the module run on the host?	What you know about the host
`ok`	Yes	It was already in the desired state, as far as that module can tell
`changed`	Yes	It was not, and now it is
`skipped`	No — a `when` was false	Untouched by design. State is old and known
`failed`	It was attempted	The host may be half-changed. State is unknown in a specific place
`unreachable`	No — nothing connected	Nothing was attempted. State is stale but consistent
`rescued`	Yes, and it failed	A failure happened; a `rescue` block ran. State depends entirely on the rescue
`ignored`	Yes, and it failed	A failure happened and you told Ansible to carry on

Read down the third column. Three rows describe a host you can put in a sentence. Four describe a host you cannot, and each of those four needs a different response.

All seven in one run

Read-only / Safeone play, one host, seven outcomes — executed on ansible-core 2.21.3— Every task is debug, command /bin/true or fail, all against a local connection. Nothing on the machine is modified. The point is the recap line, not the tasks.

$ ansible-playbook -i inv.ini seven.yml

TASK [This one is ok] **********************************************************
ok: [lh] => { "msg": "nothing changed here" }

TASK [This one reports changed] ************************************************
changed: [lh]

TASK [This one is skipped] *****************************************************
skipping: [lh]

TASK [This one fails and is ignored] *******************************************
fatal: [lh]: FAILED! => {"changed": false, "msg": "ignored failure"}
...ignoring

TASK [Inner failure] ***********************************************************
fatal: [lh]: FAILED! => {"changed": false, "msg": "rescued failure"}

TASK [Recovery] ****************************************************************
ok: [lh] => { "msg": "recovered" }

TASK [This one fails for real] *************************************************
fatal: [lh]: FAILED! => {"changed": false, "msg": "the real failure"}

PLAY RECAP *********************************************************************
lh    : ok=4  changed=1  unreachable=0  failed=1  skipped=1  rescued=1  ignored=1

exit=2

Six tasks were written. The recap sums to more than six, and that is the first thing worth understanding about it.

`ok` is not a category, it is a total

ok counts every task that finished without an unhandled failure. It therefore includes the changed tasks and includes the ignored failures. Both verified separately on 2.21.3:

Read-only / Safetwo minimal plays, each with exactly one task — executed on 2.21.3— The first play runs one command task forced to report changed. The second runs one deliberately failing task with ignore_errors. Neither writes anything.

$ ansible-playbook -i inv.ini okcount.yml ; ansible-playbook -i inv.ini ignonly.yml

PLAY RECAP *********************************************************************
lh    : ok=1  changed=1  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0

PLAY RECAP *********************************************************************
lh    : ok=1  changed=0  unreachable=0  failed=0  skipped=0  rescued=0  ignored=1

One changed task produced ok=1 changed=1. One failed and ignored task also produced ok=1. So ok cannot be read as “number of tasks that were fine”. A host with ok=40 ignored=6 had six failures in it.

This matters the moment anyone builds a dashboard or a chat notification out of recap numbers. The intuitive summary — “sum the ok column, that is our success rate” — counts ignored failures as successes, on every host, permanently.

`failed` versus `unreachable`: the distinction the rest of the part is built on

These two are the ones people merge, and merging them is the single most expensive mistake in fleet triage.

A failed host ran something. Ansible connected, pushed a module, the module executed on the managed node, and it returned a result saying the operation did not succeed. The host is somewhere between “nothing happened” and “the change is half applied”:

apt failed to install a package — possibly after updating the package index, possibly after unpacking two of five packages.
template failed validation — but the previous lesson in the play already restarted a service.
command returned non-zero — after doing whatever the command does before its last line.

You cannot say what state that host is in without going and looking. What you can say is that something ran, so the change may be partially applied.

An unreachable host ran nothing. Ansible could not open a connection, so no module was ever transferred, so nothing executed. If the host was unreachable from the first task of the play, its configuration is exactly what it was before the run started.

That makes an unreachable host consistent — and stale. It is running last week’s configuration. It is not damaged. It is not half-anything. It is simply a host that did not get the change, and it will still be running the old configuration next Tuesday when something depends on the new one.

`skipped` is the good kind of untouched

A skipped task is the only “nothing happened” outcome that carries no uncertainty at all. The when evaluated false, so Ansible deliberately did not act. The host is in a known state: the state it was in, because your conditional said it should be.

The reason to name this explicitly is that a skipped host and an unreachable host produce the same change on disk — none — but opposite confidence. Skipped is a decision. Unreachable is an accident.

There is one way to get this wrong, and it is common enough to name: a when clause that references a fact. If facts were not gathered, or were served from a stale cache, the conditional can skip a task on a host that genuinely needed it. The recap will show skipped, which reads as intentional, and nobody will look again.

Read-only / Safea skip that hides a targeting bug— If ansible_facts.distribution is missing or cached from before a distribution upgrade, this task silently skips and the recap reports a deliberate decision. Structure only — this block is not executed against any host.

- name: Install the agent on Debian-family hosts
ansible.builtin.apt:
  name: monitoring-agent
  state: present
when: ansible_facts['os_family'] == 'Debian'

The defence is not to stop using conditionals. It is to make the expected count explicit — if you believe 180 of 300 hosts are Debian family, then skipped=120 is a pass and skipped=133 is a question.

`rescued`, and what a rescue actually promises

rescued counts a task that failed inside a block where a rescue existed and ran. The recap then reports failed=0 for that host.

What the rescue promises is that your code ran after the failure. It promises nothing about the result. A rescue that logs the failure and moves on leaves the host exactly as broken as the failure left it, while converting a red recap into a green one.

The useful discipline is to ask, of every rescue block you write: after this runs, can I describe the state of the host in one sentence? A rescue that restores a backup and restarts the service can. A rescue that prints a message cannot.

Under the hood

The seven counters are fields on a per-host AggregateStats object that the strategy plugin updates as results arrive, and the default callback prints at the end of the run. The increments happen in one place, which is why they are consistent across strategies and why the arithmetic above is not a quirk of the linear strategy.

The important asymmetry is where the increment happens. ok, changed, skipped, failed, rescued and ignored are all incremented from a task result — a JSON document that a module produced and Ansible received. unreachable is incremented from a connection error raised before any module result exists.

That is the mechanical reason the two are not comparable. A failure is something the managed node said. An unreachable is something the controller concluded on its own, having heard nothing. Every downstream difference in this part — which keywords intercept which, what the exit code is, what you can infer about disk state — follows from that one structural fact.

It also explains a behaviour that otherwise looks arbitrary: an unreachable host is removed from the play host list for the remainder of the run, while a failed host is removed from the play but its result is retained. The connection error has no result to retain.

What happens if a host is reachable at task 1 and unreachable at task 30?

You get the worst of both categories, and the recap does not tell you.

The host shows unreachable=1, which reads as “did not receive the change”. But tasks 1 through 29 did run on it. The host is partially converged: it has some of the change and not the rest, and unlike a failed host it also has no result for the task that was in flight.

The recap distinguishes these two populations only by the ok count. A host that was unreachable from the start has ok=0; a host that dropped at task 30 has ok=29. That is the whole signal, and it is why ok=0 is worth filtering on when you classify a fleet.

Reading the per-task output tells you where it stopped. A structured callback that writes JSON per task tells you reliably, which is why the observability part recommends one for any run large enough that scrolling is not an option.

What to do with each state

This is the table to keep. The rest of the part elaborates every row.

State	First action	Why
`ok` / `changed`	Verify a sample against the intended outcome	Ansible reports what the module claimed, not what the service is doing
`skipped`	Confirm the count matches your expectation	A wrong `when` looks identical to a right one
`failed`	Investigate before rerunning. Do not retry blind	The host may be half-changed; a rerun may compound it
`unreachable`	Add to a quarantine list. Establish why	It is stale, it will drift further, and it may be unreachable because of the change
`rescued`	Read what the rescue did	The recap is green; the host may not be
`ignored`	Read what you ignored, and why you thought it was safe	The `ok` count already absorbed it

The question each counter answers

All seven in one run

ok is not a category, it is a total

failed versus unreachable: the distinction the rest of the part is built on

skipped is the good kind of untouched

rescued, and what a rescue actually promises

What to do with each state

Knowledge check

`ok` is not a category, it is a total

`failed` versus `unreachable`: the distinction the rest of the part is built on

`skipped` is the good kind of untouched

`rescued`, and what a rescue actually promises