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.
# 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: trueWhy 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.
Practice what you learned
1. What does it mean for an Ansible task to be idempotent?
2. Why are the command and shell modules NOT idempotent by default?
3. What does the creates argument do on a command or shell task?
4. Why does idempotency matter for ansible-playbook --check mode?
5. What problem occurs when a shell task lacks changed_when or creates guards?
Was this page helpful?
You May Also Like
Error Handling and Blocks
How Ansible reacts to task failures by default, and how block/rescue/always plus failed_when/changed_when give playbooks try/catch-like control over errors.
Ansible for Cloud Provisioning
Using Ansible's cloud modules and collections to create, modify, and configure cloud infrastructure declaratively, often in the same playbook run that configures the resulting hosts.
Dynamic Inventory
Inventory plugins and scripts that pull host lists from live sources like cloud APIs instead of static files, keeping Ansible's view of infrastructure accurate as it changes.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics