ansible-idempotency

This skill should be used when writing idempotent Ansible tasks, using command or shell modules, implementing changed_when and failed_when directives, creating check-before-create patterns, or troubleshooting tasks that always show "changed".

⭐10stars🔀1forks📁View on GitHub🕐Updated Jan 2, 2026⬇️3downloads

When & Why to Use This Skill

This Claude skill provides comprehensive patterns and best practices for achieving idempotency in Ansible automation. It focuses on optimizing 'command' and 'shell' modules using directives like changed_when and failed_when to ensure tasks produce consistent results across multiple executions without unintended side effects, which is essential for reliable Infrastructure as Code (IaC).

Use Cases

  • Case 1: Optimizing shell-based tasks to accurately report change status and avoid 'always changed' false positives in playbooks.
  • Case 2: Implementing robust 'check-before-create' patterns for infrastructure resources such as VM templates, API tokens, or database entries.
  • Case 3: Customizing failure conditions to handle expected errors or non-zero exit codes gracefully in complex automation workflows.
  • Case 4: Auditing existing Ansible playbooks for anti-patterns and enforcing strict shell execution standards (set -euo pipefail) using the provided utility script.
  • Case 5: Creating reliable, multi-step deployment pipelines that can be safely re-run at any point in the lifecycle without corrupting the target state.
nameansible-idempotency
description>

Ansible Idempotency Patterns

Techniques for ensuring Ansible tasks are truly idempotent - producing the same result whether run once or multiple times.

Core Directives

changed_when

Controls when Ansible reports a task as "changed". Critical for command and shell modules which always report changed by default.

- name: Check if service exists
  ansible.builtin.command: systemctl status myservice
  register: service_check
  changed_when: false  # Read-only operation, never changes anything

failed_when

Controls when Ansible considers a task failed. Allows graceful handling of expected errors.

- name: Check resource existence
  ansible.builtin.command: check-resource {{ resource_id }}
  register: check_result
  failed_when: false  # Don't fail, we'll check the result ourselves

register

Captures task output for use in changed_when and failed_when expressions.

- name: Run command
  ansible.builtin.command: some-command
  register: cmd_result
  # Now cmd_result.rc, cmd_result.stdout, cmd_result.stderr are available

Pattern 1: Detect Actual Changes

Make commands report "changed" only when something actually changed:

- name: Create Proxmox API token
  ansible.builtin.command: >
    pveum user token add {{ username }}@pam {{ token_name }}
  register: token_result
  changed_when: "'already exists' not in token_result.stderr"
  failed_when:
    - token_result.rc != 0
    - "'already exists' not in token_result.stderr"
  no_log: true

Key pattern: Detect specific output that indicates no change occurred.

Pattern 2: Check Before Create

Check if a resource exists before creating it:

- name: Check if VM template exists
  ansible.builtin.shell: |
    set -o pipefail
    qm list | awk '{print $1}' | grep -q "^{{ template_id }}$"
  args:
    executable: /bin/bash
  register: template_exists
  changed_when: false  # Checking doesn't change anything
  failed_when: false   # Not finding it isn't a failure

- name: Create VM template
  ansible.builtin.command: >
    qm create {{ template_id }}
    --name {{ template_name }}
    --memory 2048
  when: template_exists.rc != 0  # Only create if doesn't exist
  register: create_result
  changed_when: create_result.rc == 0

Pattern 3: Verify After Create

Confirm resource creation succeeded:

- name: Create VM
  ansible.builtin.command: >
    qm create {{ vmid }} --name {{ vm_name }}
  register: create_result
  changed_when: true

- name: Verify VM was created
  ansible.builtin.shell: |
    set -o pipefail
    qm list | grep "{{ vmid }}"
  args:
    executable: /bin/bash
  register: verify_result
  changed_when: false
  failed_when: verify_result.rc != 0

Pattern 4: Conditional Change Detection

Use output content to determine if change occurred:

- name: Update cluster configuration
  ansible.builtin.command: update-config --apply
  register: update_result
  changed_when: "'Configuration updated' in update_result.stdout"
  failed_when: "'Error' in update_result.stderr"

Common Patterns

Output Indicator changed_when Expression
"already exists" "'already exists' not in result.stderr"
"no changes" "'no changes' not in result.stdout"
"created" "'created' in result.stdout"
"updated" "'updated' in result.stdout"
Exit code 0 = created result.rc == 0

Pattern 5: Multiple Failure Conditions

Allow specific "failures" that are actually expected:

- name: Run database migration
  ansible.builtin.command: /usr/bin/migrate-database
  register: migrate_result
  failed_when:
    - migrate_result.rc != 0
    - "'already applied' not in migrate_result.stdout"
    - "'no pending migrations' not in migrate_result.stdout"
  changed_when: "'applied' in migrate_result.stdout and 'already' not in migrate_result.stdout"

Pattern 6: Read-Only Operations

Mark read-only operations as never changed:

# Checking status
- name: Get cluster status
  ansible.builtin.command: pvecm status
  register: cluster_status
  changed_when: false
  failed_when: false

# Gathering information
- name: List available images
  ansible.builtin.command: qm list
  register: vm_list
  changed_when: false

# Verification checks
- name: Verify service is running
  ansible.builtin.command: systemctl is-active nginx
  register: nginx_status
  changed_when: false
  failed_when: false

Pattern 7: Retry Until Success

Use until for operations that may need retries:

- name: Wait for service to be ready
  ansible.builtin.uri:
    url: http://localhost:8080/health
    status_code: 200
  register: health_check
  until: health_check.status == 200
  retries: 30
  delay: 10
  # Total wait: up to 5 minutes

With command:

- name: Wait for VM to get IP address
  ansible.builtin.command: qm agent {{ vmid }} network-get-interfaces
  register: vm_network
  until: vm_network.rc == 0
  retries: 12
  delay: 5
  changed_when: false

Pattern 8: Set Facts for State

Use facts to track state across tasks:

- name: Check existing cluster status
  ansible.builtin.command: pvecm status
  register: cluster_status
  failed_when: false
  changed_when: false

- name: Set cluster facts
  ansible.builtin.set_fact:
    is_cluster_member: "{{ cluster_status.rc == 0 }}"
    in_target_cluster: "{{ cluster_name in cluster_status.stdout }}"

- name: Create cluster
  ansible.builtin.command: pvecm create {{ cluster_name }}
  when: not in_target_cluster
  register: cluster_create
  changed_when: cluster_create.rc == 0

Anti-Patterns to Avoid

Always Changed

# BAD - Always shows changed
- name: Check status
  ansible.builtin.command: systemctl status app

# GOOD
- name: Check status
  ansible.builtin.command: systemctl status app
  register: status_check
  changed_when: false
  failed_when: false

Silent Failure Suppression

# BAD - Hides all errors
- name: Critical operation
  ansible.builtin.command: important-command
  failed_when: false

# GOOD - Only allow expected "errors"
- name: Critical operation
  ansible.builtin.command: important-command
  register: result
  failed_when:
    - result.rc != 0
    - "'expected condition' not in result.stderr"

No Output Capture

# BAD - Can't check results
- name: Run command
  ansible.builtin.command: create-resource

# GOOD
- name: Run command
  ansible.builtin.command: create-resource
  register: result
  changed_when: "'created' in result.stdout"

Shell Script Requirements

Use strict error handling in shell scripts:

- name: Run pipeline
  ansible.builtin.shell: |
    set -euo pipefail
    cat data.txt | grep pattern | sort | uniq
  args:
    executable: /bin/bash
  register: pipeline_result
  changed_when: false

Why set -euo pipefail?

Flag Purpose
-e Exit on any command failure
-u Error on undefined variables
-o pipefail Catch errors in pipelines

Testing Idempotency

Verify playbooks are idempotent by running twice:

# First run - may show changes
uv run ansible-playbook playbooks/setup.yml

# Second run - should show 0 changes
uv run ansible-playbook playbooks/setup.yml

# If second run shows changes, playbook is NOT idempotent

Common changed_when Expressions

# Never changed (read-only)
changed_when: false

# Always changed (one-time operations)
changed_when: true

# Based on output content
changed_when: "'created' in result.stdout"
changed_when: "'already exists' not in result.stderr"
changed_when: "'updated' in result.stdout"

# Based on return code
changed_when: result.rc == 0
changed_when: result.rc != 1

# Complex conditions
changed_when:
  - result.rc == 0
  - "'no changes' not in result.stdout"

Utility Script

Use the idempotency checker to analyze playbooks for common issues:

# Check a single playbook
${CLAUDE_PLUGIN_ROOT}/skills/ansible-idempotency/scripts/check_idempotency.py ansible/playbooks/my-playbook.yml

# Check multiple playbooks
${CLAUDE_PLUGIN_ROOT}/skills/ansible-idempotency/scripts/check_idempotency.py ansible/playbooks/*.yml

# Strict mode (info issues become warnings)
${CLAUDE_PLUGIN_ROOT}/skills/ansible-idempotency/scripts/check_idempotency.py --strict ansible/playbooks/my-playbook.yml

# Summary only
${CLAUDE_PLUGIN_ROOT}/skills/ansible-idempotency/scripts/check_idempotency.py --summary ansible/playbooks/*.yml

The script detects:

  • Command/shell tasks without changed_when
  • Shell tasks without set -euo pipefail
  • Tasks missing no_log that may contain secrets
  • Tasks missing name attribute
  • Use of deprecated short module names (non-FQCN)

Script location: ${CLAUDE_PLUGIN_ROOT}/skills/ansible-idempotency/scripts/check_idempotency.py

  • ansible-error-handling - Block/rescue patterns
  • ansible-fundamentals - Module selection (prefer native modules)
  • ansible-proxmox - Proxmox-specific idempotency patterns