Reading a PLAY RECAP like an operator · Ansible

The recap is the most-read and least-read output in Ansible. Everybody looks at it. Almost everybody reads two fields — failed and unreachable — and treats the rest as decoration.

The other five are where the interesting failures live. A run in which nothing failed, nothing was unreachable, and nothing happened is a common and expensive outcome, and it is visible in the recap only if you read skipped. A fleet that has quietly acquired a second owner for one piece of state announces itself in changed, permanently, and never anywhere else.

This lesson goes field by field, with a single run that exercises all seven.

Every field, in one run

Four hosts, arranged so that each one produces a different outcome:

Read-only / Safeevery recap field populated— Verified on ansible-core 2.21.3. Four hosts with ansible_connection=local; the only modules are debug and fail, so nothing was changed on any system. The changed results come from changed_when.

$ ansible-playbook -i hosts.ini recap.yml

PLAY RECAP *********************************************************************
web1                       : ok=3    changed=1    unreachable=0    failed=0    skipped=3    rescued=0    ignored=0
web2                       : ok=3    changed=1    unreachable=0    failed=0    skipped=3    rescued=0    ignored=1
web3                       : ok=3    changed=0    unreachable=0    failed=0    skipped=3    rescued=1    ignored=0
web4                       : ok=2    changed=0    unreachable=0    failed=1    skipped=3    rescued=0    ignored=0

Now the fields, in the order they mislead people.

`ok` — the module was satisfied

ok counts tasks that completed and reported no change. It is an assertion about the module, not about the system.

ansible.builtin.service reporting ok means the module asked the service manager for the state of a unit, found it already matching, and had nothing to do. It does not mean the application inside that unit is answering requests. It does not mean the port is listening. The verify the outcome, not the task result lesson makes this argument in full, and it is the reason the whole of this part exists.

Read ok as “nothing needed doing here, according to the thing that checked”.

`changed` — the module says it altered something

The single most information-dense field, and the one this part builds its metrics on.

On a converged fleet — one where the automation has already been applied and nothing external has interfered — the healthiest possible result is changed=0 on every host. Zero means the desired state and the actual state agree everywhere.

That makes any non-zero changed on a converged fleet a question with exactly three answers:

You just deployed something. Expected, and the count should return to zero on the next run.
Something outside Ansible changed the host, and this run corrected it. That is drift, and the count is the signal.
A task is lying. It reports changed on every run because its changed_when is wrong, or because it is a command that has no way to know. This is the case that destroys the value of the other two, and the inaccurate changed lesson is the reference.

The third case is worth being severe about. One permanently-changing task means changed never falls to zero, which means nobody can use it as a signal, which means real drift is invisible. A single sloppy task removes the fleet’s ability to be audited.

`unreachable` — the connection failed

A connection was attempted and did not succeed: SSH refused, timed out, DNS failed, authentication failed at the transport level. It is categorically different from failed, and the unreachable versus failed lesson is the full treatment.

The caveat that catches people is the mirror image: a task that never connects cannot report a host unreachable. ansible.builtin.debug, ansible.builtin.fail, set_fact and assert are action plugins that execute on the controller. A “can we reach the fleet?” pre-flight play built from debug reports unreachable=0 for hosts that are comprehensively unreachable, because nothing tried.

Verified on 2.21.3 against two documentation-range addresses that cannot answer:

Read-only / Safea task that connects, against hosts that cannot answer— Verified on 2.21.3. 192.0.2.0/24 is documentation-reserved and unroutable by design, which is what makes this test safe.

$ ansible-playbook -i hosts.ini unreach.yml

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

The run exited 4. A run with a task failure and no unreachable host exits 2. A run with both exits 4 — verified by execution, because unreachable takes precedence. A CI gate that checks only for 2 treats a run containing both as a pass.

`failed` — a module reported failure and was not rescued

The one everybody reads. Worth two notes.

It counts hosts, not tasks: a host that failed once shows failed=1, and it left the play at that point, so its other counters stopped incrementing. web4 above shows ok=2 rather than ok=3 for exactly that reason.

And a failed host does not stop the other hosts by default. The play continues on everyone else, which is why partial failure is the normal shape of a fleet run and why Part XLIV exists.

`skipped` — a task was not run because a condition said not to

The field that hides the most.

A skip is indistinguishable in the recap from a deliberate one. skipped=3 on a play that deliberately targets three optional tasks is healthy. skipped=3 on a play where a variable name was mistyped means the work did not happen — and the run is green:

Read-only / Safea completely successful run in which nothing was done— Verified on 2.21.3. The deploy task is gated on deploy_enabled, which is undefined, so default(false) skips it on every host. Exit code was 0.

$ ansible-playbook -i hosts.ini skipall.yml

PLAY RECAP *********************************************************************
web1                       : ok=0    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
web2                       : ok=0    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
web3                       : ok=0    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0
web4                       : ok=0    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

failed=0 everywhere. Exit code 0. CI is green. The deployment did not happen.

The tell is ok=0. A run that did nothing at all has nothing in ok, and that combination — ok=0 with a non-zero skipped — is worth alerting on directly.

`rescued` — a failure was caught by a `rescue` block

A task failed, a rescue handled it, and the host continued. web3 above shows rescued=1 and failed=0: from the recap’s point of view the host succeeded.

Which is correct, and is also an event worth counting. A rescue firing means the primary path did not work. If rescued is routinely non-zero, your automation is routinely taking its error path, and the run summary is the only place that says so — the run output scrolls past and the exit code is 0.

`ignored` — a task failed and `ignore_errors: true` swallowed it

web2 shows ignored=1. Something genuinely failed there and the play was instructed not to care.

Every non-zero ignored is a decision somebody made once, in a commit that is probably older than the current problem. The ignore_errors lesson argues that most of them should be failed_when instead. In the recap, the number is the count of failures you have agreed in advance not to be told about, and it deserves the same periodic review as a suppressed alert.

Hosts that never ran are absent, not zero

The recap enumerates hosts that produced a result. A host that was never reached — because the play stopped before its batch, or because it was never in the target set — does not appear at all.

From the serial: 1 demonstration in Part XLII, verified on 2.21.3 with four hosts in the play:

PLAY RECAP *********************************************************************
web1                       : ok=1    changed=1    unreachable=0    failed=0    skipped=1
web2                       : ok=1    changed=1    unreachable=0    failed=1    skipped=0

web3 and web4 are not listed with zeros. They are simply not there.

This is the single most important thing to know about reading a recap after a partial failure, because the natural reading of “two hosts in the recap” is “two hosts in the run”. Answering which hosts did this touch? requires the target list as well as the recap — and reconstructing the target list after the fact is exactly what lesson 4 is about.

A four-step reading

The order matters, because each step changes what the next one means.

Count the hosts. Compare against what you expected to target. Missing hosts are the finding, and they are invisible if you start with the numbers.
unreachable, then failed. In that order: unreachable hosts are an infrastructure statement, failed hosts are an automation statement, and confusing them sends the diagnosis to the wrong team.
changed against your expectation for this run. For a deploy, some change is expected. For a scheduled convergence run on a stable fleet, any change is a question.
skipped and ok together. ok=0 with a non-zero skipped is the run that did nothing. A skipped count that differs between hosts you believe are identical is a variable resolving differently somewhere.

Then, and only then, the exit code — because it compresses all of that into one number and discards which hosts were involved.

Under the hood

The recap is produced by a callback plugin, not by the executor.

Ansible’s task engine emits events — v2_runner_on_ok, v2_runner_on_failed, v2_runner_on_skipped, v2_runner_on_unreachable and their relatives — and a callback plugin decides what to do with them. The stats you see are accumulated by the same object across the whole run and printed by v2_playbook_on_stats at the end.

Three consequences follow, and all three matter later in this part.

The recap is a rendering, not the data. The numbers exist as a structure before they become that text, which is why a different callback can emit the same run as JSON with the per-task detail intact. Lesson 4 uses exactly that.

Only one callback owns stdout, but many can be active at once. The recap you read and a machine-readable artefact are not alternatives; they are two consumers of one event stream. Lesson 2 is about choosing them.

changed is whatever the module said. The callback is counting result.changed from the module’s return value. It performs no independent verification, and it cannot: it never saw the host. A command task with changed_when: true increments the fleet’s drift metric with no change having occurred anywhere, and nothing downstream can tell the difference.

That last point is why the accuracy of changed_when is not a style question. It is the input to every metric in lesson 6.

What happens if you gate CI on the exit code alone?

You get a gate that is right most of the time and wrong in the two cases you built it for.

Case one: the run that did nothing. Every task skipped because a variable was undefined. Exit code 0, verified. The pipeline reports success and promotes the change.

Case two: failures plus unreachable hosts. Verified on 2.21.3, a run with both a task failure and an unreachable host exits 4, not 2 — unreachable takes precedence. A gate written as “fail the job if the exit code is 2” passes it.

The exit code is a summary of a summary. It is the right thing to check for “did the command work”, and the wrong thing to check for “did the change happen”.

What to gate on instead, in increasing order of effort:

Non-zero of any kind fails the job. Trivially better than checking for a specific code, and it catches case two.
Assert the outcome inside the play. A final task that fails if the thing you deployed is not answering. This turns “did nothing” into a real failure, because the assertion is not conditional on the same variable that caused the skip.
Parse a machine-readable artefact. The recap fields per host, checked against expectations: at least N hosts present, zero unreachable, and a changed count within the range this run should have produced. That artefact is lesson 4.

Recap patterns worth recognising on sight

Pattern	What it usually means
`ok=0` and `skipped` non-zero	The run did nothing. Check the conditional variable
Fewer hosts than expected	Hosts were never reached. Compare against the target list
`changed` non-zero on every run, forever	A lying task, or a resource with two owners
`changed` suddenly non-zero on a stable fleet	Drift. Something outside Ansible changed the hosts
`rescued` routinely non-zero	The automation is habitually taking its error path
`ignored` non-zero	Failures you agreed in advance not to hear about
`unreachable=0` on a play built from `debug`	Proves nothing; nothing tried to connect
`skipped` differing across identical hosts	A variable resolves differently on some of them

Knowledge check

Why this matters

Seven numbers per host, printed at the end of every run, and they are the only automatic record most estates ever produce of what their automation did.

The habit worth building is to stop reading the recap as a pass/fail light and start reading it as a measurement. failed and unreachable are the least interesting fields precisely because they are loud — they will find you anyway. The quiet ones carry the information: a changed count that never reaches zero, a skipped count that differs between supposedly identical hosts, a host that is simply not on the list.

And the sentence that the rest of this part elaborates is already visible here. A run in which every task succeeded is a successful run. Whether it was a successful change is a different question, answered by different evidence, and the recap does not attempt it.

The next lesson is about what else you can ask the run to tell you.

Every field, in one run

ok — the module was satisfied

changed — the module says it altered something

unreachable — the connection failed

failed — a module reported failure and was not rescued

skipped — a task was not run because a condition said not to

rescued — a failure was caught by a rescue block

ignored — a task failed and ignore_errors: true swallowed it