ansible-idempotency_skill

Overview

This skill helps you write and verify idempotent Ansible tasks, especially when using command and shell modules. It provides patterns for changed_when, failed_when, check-before-create flows, verification steps, retries, and common anti-patterns to avoid. Use it to reduce false positives for "changed" and to make playbooks safe to run repeatedly.

How this skill works

The skill inspects command and shell tasks to ensure outputs and exit codes are captured with register and evaluated via changed_when and failed_when. It recommends pre-checks, post-verification, and use of strict shell flags (set -euo pipefail) for reliable scripts. An included checker script flags missing changed_when, unsafe shell invocations, potential secret leaks, unnamed tasks, and non-FQCN modules.

When to use it

• When using ansible.builtin.command or ansible.builtin.shell tasks that currently always report changed
• When implementing changed_when/failed_when expressions based on stdout, stderr, or rc
• When creating resources that must only be created if absent (check-before-create)
• When verifying a create operation actually succeeded (verify-after-create)
• When troubleshooting playbooks that report changes on every run

Best practices

• Always register command/shell output and use changed_when/failure rules based on rc, stdout, or stderr
• Mark read-only checks changed_when: false and failed_when: false to avoid noise
• Use check-before-create: detect existence first, then conditionally run create steps
• Use strict shell options (set -euo pipefail) in shell blocks to catch errors reliably
• Avoid blanket failed_when: false; instead allow expected messages or patterns
• Sanitize tasks handling secrets with no_log: true

Example use cases

• Create a resource only if a pre-check indicates it is missing, using when: template_exists.rc != 0
• Detect idempotent output like 'already exists' or 'no changes' to set changed_when appropriately
• Verify after creation with a read-only command that fails the task if verification fails
• Retry transient operations with until/retries/delay and mark those checks changed_when: false
• Use set_fact to capture state flags from inspection commands and drive conditional actions