What check mode cannot tell you · Ansible

The previous lesson turned a playbook into a drift report with one flag. This lesson is about the ways that report lies to you, all of which have been reproduced on ansible-core 2.21.3 rather than inferred.

They matter more than the mechanics, because a drift report you trust and should not is worse than no drift report at all.

Support is per-module, and it has three values

Every module documents a check_mode attribute, and it takes one of three values:

Read-only / Safeask the module, do not assume— Reads local documentation for the installed version. The ATTRIBUTES section carries check_mode and diff_mode support levels.

ansible-doc ansible.builtin.command | sed -n '/ATTRIBUTES/,/NOTES/p'
ansible-doc ansible.builtin.wait_for | sed -n '/ATTRIBUTES/,/NOTES/p'
ansible-doc ansible.builtin.template | sed -n '/ATTRIBUTES/,/NOTES/p'

Read on 2.21.3:

Module	`check_mode` support	Behaviour under `--check`
`template`, `copy`, `file`, `lineinfile`, `stat`, `setup`, `package_facts`, `service_facts`	`full`	Compares and predicts correctly
`command`	`partial`	Skipped unless `creates` or `removes` is given
`wait_for`	`none`	Always skipped

command being partial rather than none is a distinction worth having. Its documentation states that the command itself cannot be subject to check-mode semantics, so creates/removes are offered as a workaround — and they work:

Read-only / Safecommand with creates, under --check— Executed against ansible-core 2.21.3. With creates supplied, the module checks for the file and reports the correct changed status instead of skipping.

$ ansible-playbook -i inventory.ini creates.yml --check

TASK [command with creates, marker absent] *************************************
changed: [localhost]

TASK [command with creates, marker present] ************************************
ok: [localhost]

Without creates or removes, the same module is skipped. Which brings us to the trap.

The trap: a skipped command still registers a result

This is the most important verified fact in this part.

Read-only / Safewhat a check-skipped command registers— Executed against ansible-core 2.21.3. The task was skipped, and the registered variable is fully populated - with rc set to 0.

$ ansible-playbook -i inventory.ini probe.yml --check

TASK [dump] ********************************************************************
ok: [localhost] => {
  "probe": {
      "changed": false,
      "cmd": ["/bin/echo", "probe"],
      "delta": null,
      "end": null,
      "failed": false,
      "msg": "Command would have run if not in check mode",
      "rc": 0,
      "skipped": true,
      "start": null,
      "stderr": "",
      "stderr_lines": [],
      "stdout": "",
      "stdout_lines": []
  }
}

Look at rc. It is 0. The command never ran, and the registered result says it returned success.

Now consider the two gates every playbook contains:

Read-only / Safeboth naive gates are wrong, in opposite directions— Executed against ansible-core 2.21.3 under --check. The rc gate opened even though nothing ran; a stdout content gate would have closed silently, because stdout is an empty string.

$ ansible-playbook -i inventory.ini gates.yml --check

TASK [probe] *******************************************************************
skipping: [localhost]

TASK [naive gate on rc] ********************************************************
ok: [localhost] => {
  "msg": "NAIVE GATE OPENED"
}

when: probe.rc == 0 — opens. The play proceeds as though the probe had succeeded, on evidence that does not exist.
when: "'running' in probe.stdout" — closes, silently, because stdout is "". Every task behind it is skipped.
probe.stdout | default('unknown') — does not help. stdout exists and is the empty string, so default() never fires.

Writing conditionals that refuse

The fix is not a cleverer expression. It is to make the play refuse to decide when the evidence is missing.

Read-only / Safeguard on skipped, then on the value— The is skipped test distinguishes 'the probe says no' from 'the probe did not run'. The explicit fail turns a silently wrong dry run into a loud one.

- name: probe the current version
ansible.builtin.command:
  cmd: /usr/local/bin/appctl version
register: probe
changed_when: false

- name: refuse to continue if the probe did not actually run
ansible.builtin.fail:
  msg: >-
    The version probe was skipped, so this play cannot decide anything.
    Re-run without --check, or give the probe check_mode: false.
when: probe is skipped

- name: act on the probe result
ansible.builtin.debug:
  msg: "version is {{ probe.stdout }}"
when:
  - probe is not skipped
  - probe.rc == 0

Read-only / Safethe guarded play under --check— Executed against ansible-core 2.21.3. The guarded gate closes correctly and the explicit refusal fires, so a check run that cannot decide says so instead of reporting a clean estate.

$ ansible-playbook -i inventory.ini guard.yml --check

TASK [probe] *******************************************************************
skipping: [localhost]

TASK [guarded gate] ************************************************************
skipping: [localhost]

TASK [explicit refusal when the probe did not run] *****************************
fatal: [localhost]: FAILED! => {"changed": false, "msg": "probe was skipped; this play cannot decide anything in check mode"}

A failed check run is a vastly better outcome than a clean one that examined nothing. It is visible, it is actionable, and it cannot be mistaken for evidence.

`check_mode: false`: the trap in the other direction

The keyword exists for a real need: a read-only probe should run even during a dry run, because otherwise the dry run cannot compute anything.

Read-only / Safecheck_mode: false executes for real during a --check run— Executed against ansible-core 2.21.3. The first probe was skipped; the second, carrying check_mode: false, ran and returned real output during a --check run.

$ ansible-playbook -i inventory.ini forced.yml --check

TASK [probe with command (no creates/removes)] **********************************
skipping: [localhost]

TASK [gate on the probe] *******************************************************
ok: [localhost] => {"msg": "probe stdout was: "}

TASK [probe forced to run even in check mode] **********************************
ok: [localhost]

TASK [show forced result] ******************************************************
ok: [localhost] => {"msg": "forced stdout was: forced"}

That is the intended use, and it is correct here because the task only reads.

check_mode: false on a task that writes makes --check change production

The words check_mode: false mean ignore the —check flag for this task. Not “simulate more carefully”. The task executes.

The incident writes itself. Somebody adds check_mode: false to a task “so the fact-gathering step works in dry runs”, the task is later extended to write a file, and now every dry run — including the nightly drift report, including the pre-change dry run someone does to be careful — modifies production.

Two rules make this safe:

check_mode: false belongs only on tasks that read. Pair it with changed_when: false so the task can never report a change either.
It is a reviewable keyword. Grep for it before every release, and check each occurrence against rule 1. A check_mode: false on a template, copy, file, lineinfile, package or service task is a defect, without needing to read the surrounding play.

Read-only / Safeaudit every occurrence in the repository— Prints each use with three lines of context, so the module it applies to is visible. Run it as a review step, not once.

grep -rn -B 3 'check_mode:[[:space:]]*\(false\|no\|False\)' roles/ playbooks/

`wait_for` and the tasks that vanish

wait_for carries check_mode: support: none and is skipped in every check run — confirmed by execution.

That is usually harmless and occasionally not. A play that waits for a service port before verifying it, then checks the service, will in check mode skip the wait and immediately check — which is a different play from the one that runs in production, and it can pass when the real one would fail, or vice versa.

The point generalises: check mode does not run the play you wrote. It runs a play with some tasks removed. The removed tasks are the ones whose modules do not support it, and the recap does not distinguish them from tasks skipped by a when.

Read-only / Safehow much of the play does check mode actually cover?— Compares the skipped count between a real run and a check run against a single canary host. The difference is the set of tasks check mode cannot examine.

ansible-playbook -i inventory/ site.yml --limit canary01.example.com \
| tail -3 > /tmp/real.recap

ansible-playbook -i inventory/ site.yml --limit canary01.example.com --check \
| tail -3 > /tmp/check.recap

diff /tmp/real.recap /tmp/check.recap

If the check run skips twenty more tasks than the real one, your drift report has twenty blind spots and you now know the number. Put it in the runbook next to the report.

Under the hood

--check sets a flag on each task’s execution context. The action plugin consults it: if the module declares check-mode support, the flag is passed through and the module returns its prediction; if it does not, the action plugin short-circuits and returns a synthetic result with skipped: true and msg: "... would have run if not in check mode".

That synthetic result is a normal module result dictionary, which is exactly why the trap exists. It has to have the standard keys, so rc gets a value, and the value is 0 because no failure occurred — nothing occurred at all. There is no way for a when expression to distinguish “succeeded with rc 0” from “was never attempted” except by testing skipped, which is why is skipped is the load-bearing part of the guard rather than a stylistic preference.

check_mode: false sets that same flag to false for the one task, before the action plugin looks at it. The module never learns that a --check run is in progress, which is why it behaves exactly as it would in a real run — including writing.

What happens if you run the drift report without --check instead?

You get complete coverage and you have converted your drift detector into a nightly fleet-wide change.

That is a legitimate design — it is what unattended convergence means, and lesson 5 covers the trade honestly — but it must be a decision, not a workaround for check-mode gaps. The properties are different in ways that matter to whoever is on call: production now changes at 02:00 with nobody watching, handlers fire and restart services, and the run has a blast radius equal to the entire declared surface on every host.

If the motivation is only “check mode has blind spots”, the cheaper answers are: give read-only probes check_mode: false with changed_when: false; add creates/removes to command tasks that can carry them; replace command tasks with real modules where one exists; and guard every remaining conditional with is skipped.

That closes most of the gap without making the drift report a change event.

Support is per-module, and it has three values

The trap: a skipped command still registers a result

Writing conditionals that refuse

check_mode: false: the trap in the other direction

wait_for and the tasks that vanish

Knowledge check

`check_mode: false`: the trap in the other direction

`wait_for` and the tasks that vanish