Reading the recap, and the exit code

The PLAY RECAP is the only summary of a run that Ansible produces on its own, and the exit code is the only part of it a machine can read. Between them they answer “what just happened to my estate”, and almost every automation pipeline that has ever gone green on a failed run got one of the two wrong.

The seven fields

$ ansible-playbook -i inv2.ini vocab.yml

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

One line per host that the run attempted. Read it left to right:

Two of those deserve emphasis.

skipped conflates two causes. A task skipped by a false when: and a task skipped because the module does not support check mode produce identical output. In a --check run, skipped is partly a measure of how much the prediction did not cover.

rescued and ignored are not zero-cost. A recap reporting failed=0 rescued=3 describes a run in which three tasks failed. The run recovered; the estate may not have. Treating failed=0 as “clean” is how a degraded run gets recorded as a success.

unreachable is not failed

These are different questions about different systems, and conflating them sends you to debug the wrong thing.

• failed=1 — Ansible connected, ran a module, and the module reported failure. The playbook, the host’s state, or the module’s arguments are at fault.
• unreachable=1 — Ansible could not establish a usable connection. SSH refused, the host is down, DNS did not resolve, the key was rejected, or the Python interpreter could not be started. Nothing in your playbook is implicated.

$ ansible-playbook -i inv2.ini ec-unreach.yml

fatal: [web01.example.com]: UNREACHABLE! => {"changed": false, "msg": "Task failed: Failed to connect to the host via ssh: ssh: connect to host 192.0.2.11 port 22: Connection timed out", "unreachable": true}

PLAY RECAP *********************************************************************
web01.example.com          : ok=0    changed=0    unreachable=1    failed=0    skipped=0    rescued=0    ignored=0

The pre-flight check that proves nothing

Here is a reachability check that a lot of people have written:

- name: Confirm the fleet is reachable
  hosts: all
  gather_facts: false
  tasks:
    - name: Confirm the host answers
      ansible.builtin.debug:
        msg: 'reached {{ inventory_hostname }}'

Run against the same unreachable host as above, on the same inventory:

$ ansible-playbook -i inv2.ini preflight-debug.yml

TASK [Confirm the host answers] ************************************************
ok: [web01.example.com] => {
  "msg": "reached web01.example.com"
}

PLAY RECAP *********************************************************************
web01.example.com          : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

ok=1. unreachable=0. Exit code 0. A completely green run against a host that does not exist.

The exit code

The recap is for humans. Cron, CI and the wrapper script read the exit code, and it has one property that catches people out.

All four rows verified by execution on ansible-core 2.21.3. The exit-code table is not published in the upstream CLI documentation or the ansible-playbook(1) manual page; these values come from observed behaviour and from the installed source, and the version they were established against is stated deliberately.

The last row is the one that matters. Unreachable takes precedence:

$ ansible-playbook -i inv2.ini ec-both.yml; echo EXIT=$?

fatal: [localhost]: FAILED! => {"changed": false, "msg": "deliberate failure"}

PLAY RECAP *********************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0
web01.example.com          : ok=0    changed=0    unreachable=1    failed=0    skipped=0    rescued=0    ignored=0

EXIT=4

ansible-playbook -i inventory.ini site.yml
rc=$?
if [ "$rc" -ne 0 ]; then
echo "ansible-playbook exited $rc"
exit "$rc"
fi

Preserving the exact code on the way out is worth the extra word: 4 tells whoever reads the job log that at least one host was unreachable, which is an infrastructure page rather than a playbook bug.

Knowledge check