Idempotency in Ansible

Analogy categoryAnalogies

What Idempotency Means in Ansible

An idempotent operation produces the same end state no matter how many times it is applied, and Ansible modules achieve this by checking a resource's current state before acting rather than blindly executing a command every time. The file module, for example, checks whether a file already exists with the requested owner, group, and permissions before touching it, so re-running a playbook against already-converged hosts reports zero changed tasks instead of unnecessarily re-executing every step.

🏏

Cricket analogy: Idempotency is like a groundskeeper checking whether the pitch is already rolled and watered before doing it again, so running the maintenance routine twice in a day doesn't over-water the surface.

Idempotent Modules vs the command/shell Modules

Purpose-built modules such as package, service, file, user, copy, template, and lineinfile are idempotent because they compare the desired state described in the task against the actual state on the host and only act on the difference. The command and shell modules, by contrast, simply execute whatever arbitrary command you give them every single run with no built-in state comparison, so a task like shell: echo 'export PATH=...' >> ~/.bashrc would append a duplicate line on every playbook run unless you add explicit guards like creates, removes, or a changed_when/failed_when condition to approximate idempotent behavior.

🏏

Cricket analogy: Purpose-built modules are like a specialist DRS review system that checks ball-tracking data before confirming a decision, while raw shell commands are like an umpire's snap judgment applied fresh every single time regardless of what already happened.

yaml

# Idempotent: lineinfile checks whether the exact line already exists
- name: Ensure PATH export is present in .bashrc
  ansible.builtin.lineinfile:
    path: /home/deploy/.bashrc
    line: 'export PATH=$PATH:/opt/app/bin'
    state: present

# Non-idempotent without guards: shell just runs every time
- name: Initialize application database (guarded to run once)
  ansible.builtin.shell: /opt/app/bin/db-init.sh
  args:
    creates: /opt/app/.db-initialized   # skips task if this file already exists

- name: Restart service only if config actually changed
  ansible.builtin.command: systemctl restart myapp
  when: config_result is changed
  changed_when: true

Why Idempotency Matters for Safe Re-runs

Idempotency lets you run the same playbook on a recurring schedule to correct configuration drift, and it lets you safely re-run a playbook after a partial failure without side effects like duplicate cron entries, doubled-up appended config lines, or accidentally recreated resources. It's also what makes check mode (ansible-playbook --check) meaningful in the first place, since modules with proper idempotent logic can accurately predict whether a real run would report a change, whereas command/shell tasks generally can't support check mode reliably at all.

🏏

Cricket analogy: Safe re-runs enabled by idempotency are like a curator being able to re-inspect the pitch every morning of a five-day Test without worrying that repeated inspections themselves damage the surface.

ansible-playbook --check combined with --diff shows exactly what would change without applying it, but this preview is only accurate for modules that implement proper idempotency checks — command and shell tasks generally can't support check mode meaningfully at all.

shell/command tasks without changed_when or creates guards will report 'changed' on every single run even when nothing meaningful happened, which pollutes Tower/AWX job history with false changes and can break notification-on-change logic that depends on accurate status.

Idempotency means an operation produces the same end state regardless of how many times it's applied.
Purpose-built modules (file, package, service, user, template, lineinfile) check actual state before acting, achieving idempotency automatically.
command and shell modules execute arbitrary commands every run with no built-in state comparison.
creates, removes, changed_when, and failed_when are used to approximate idempotency for command/shell tasks.
Idempotency enables safe recurring runs for drift correction and safe re-runs after partial failures.
ansible-playbook --check accurately previews changes only for modules with real idempotency logic.
Unguarded shell/command tasks reporting false 'changed' status pollute job history and break change-based notifications.