Idempotency and Check Mode: Run Twice, Change Once

Why this matters

A deploy pipeline reruns a role after a network timeout, and the rerun appends a second identical line to a config file, then a third on the next retry. The application reads the first match and ignores the rest until the day it reads the last. Non-idempotent tasks turn retries, the most normal event in automation, into corruption. The rule is simple to state and strict to keep: running twice must change once, and the second run is the test that proves it.

Concepts

Idempotency means convergence: the first run changes what differs, every later run reports ok with zero changes. Built-in modules mostly detect state (packages, files with content, services with desired state); raw commands do not, unless given explicit creates, removes or changed-when rules that encode the state test. Every shell task needs its state test written beside it, or it will report changed forever and poison handlers, retries and audits.

Check mode is the plan output of this module: it predicts changes without applying them, and diff shows the exact lines that would change. Review before applying is the same discipline M12 taught: the preview names the blast radius while it is still cheap. Some tasks cannot predict (commands without check support skip with a warning); those tasks deserve extra suspicion and explicit state tests, because they are the ones most likely to surprise a retry.

The second-run test is the acceptance gate for every role. Apply, run again immediately, and require zero changes. Changes on the second run mean a task that cannot see state: fix the task, not the expectation. This test belongs in the pipeline, not in memory; L37 runs it as part of the lab deliverable.

Worked example

A demo role appends a config line with a raw command (no state test): first run changes, second run changes again, file grows. The learner rewrites the task with a proper state test, reruns twice, and watches changed-then-ok. The check-mode diff of both versions shows why: the first predicts change every time, the second predicts nothing after convergence.

Common wrong move

Skipping check mode because the change looks small. Small changes carry the same blast radius as large ones when the scope is wrong, and the preview is the only place scope errors show up before execution.