How to Write an Idempotent Ansible Playbook

What idempotency means in Ansible

Ansible modules describe state, not actions. The file module says "this directory should exist with these permissions" - not "run mkdir." On the first run Ansible creates what's missing. On the second run it checks the current state, finds nothing has drifted, and reports changed=0. That's idempotency, and it's the foundational principle that makes Ansible safe to run repeatedly in production.

A working playbook: file + template tasks

The playbook below targets localhost, declares two directories and renders two files from Jinja2 templates. It is idempotent because every task uses a declarative module - nothing calls shell: or command: to run a raw script.

---
- name: Bootstrap the API stack
  hosts: localhost
  connection: local
  gather_facts: false
  vars:
    service_name: API

  tasks:
    - name: Ensure /srv/api exists
      ansible.builtin.file:
        path: /srv/api
        state: directory
        owner: root
        group: root
        mode: '0755'

    - name: Render /srv/api/index.html
      ansible.builtin.template:
        src: index.html.j2
        dest: /srv/api/index.html
        owner: root
        group: root
        mode: '0644'

    - name: Ensure /etc/nginx/conf.d exists
      ansible.builtin.file:
        path: /etc/nginx/conf.d
        state: directory
        owner: root
        group: root
        mode: '0755'

    - name: Render nginx site config
      ansible.builtin.template:
        src: api.conf.j2
        dest: /etc/nginx/conf.d/api.conf
        owner: root
        group: root
        mode: '0644'

The matching Jinja2 template templates/index.html.j2 uses the service_name variable from the play's vars: block:

<h1>{{ service_name }} Ready</h1>

Running and verifying idempotency

Run the playbook twice against localhost using a comma-delimited inline inventory (no inventory file needed):

# First run - creates the directories and renders the files
ansible-playbook site.yaml -i 'localhost,' --connection=local

# Second run - reports changed=0 if everything is idempotent
ansible-playbook site.yaml -i 'localhost,' --connection=local

The second run should output changed=0 unreachable=0 failed=0. If changed is non-zero, a task is not idempotent - often a shell: or command: task that Ansible cannot diff.

Common mistakes that break idempotency

• Using shell: or command: without creates: or changed_when - these modules always report changed. Add creates: /path/to/artifact so Ansible skips the task when the artifact already exists.
• Forgetting state: directory - ansible.builtin.file defaults to state=file; without state: directory it won't create a directory.
• Hardcoding mode as an integer - use a quoted string ('0755') to avoid octal interpretation bugs across Python versions.

Scaling up: roles and variables

For real infrastructure, split tasks into reusable roles (roles/nginx/tasks/main.yaml), pull variables from group_vars/ or host_vars/, and drive playbooks from a control host or ansible-pull in agent mode. Terraform outputs can feed Ansible inventory so provisioned infrastructure flows directly into configuration management.