Idempotence, Registered Results, and Handlers
Make repeated runs predictable, inspect task output, and restart services only when configuration changes.
What Idempotence Means
An idempotent task can run repeatedly and reach the same desired state without making an unnecessary change every time.
Examples:
aptwithstate: presentchanges a host only when a package is missing.servicewithstate: startedchanges a host only when the service is stopped.templatechanges a file only when its content or metadata differs.userchanges group membership only when required.
A second playbook run should ideally report mostly ok, not changed.
First run: changed=4
Second run: changed=0
Commands Need Extra Care
Ansible cannot always determine whether an arbitrary command changes the machine:
- name: Read the Docker version
ansible.builtin.command: docker --version
register: docker_version
changed_when: false
The command is read-only, so changed_when: false keeps the play recap accurate.
For a command that creates something, use conditions such as creates or removes when appropriate:
- name: Initialize application data
ansible.builtin.command: /opt/app/bin/initialize
args:
creates: /opt/app/.initialized
Registering Task Results
register stores a task’s complete result in a variable:
- name: Read the Docker version
ansible.builtin.command: docker --version
register: docker_version
changed_when: false
- name: Show the Docker version
ansible.builtin.debug:
msg: "{{ docker_version.stdout }}"
A command result commonly contains:
| Field | Meaning |
|---|---|
stdout |
Standard output |
stderr |
Error output |
rc |
Process return code |
changed |
Whether Ansible reports a change |
failed |
Whether the task failed |
Registered values are host-specific. Each managed host stores its own result.
Restart Only When Needed
Using state: restarted in a normal task restarts a service on every run. A handler makes the restart event-driven:
tasks:
- name: Deploy Nginx configuration
ansible.builtin.template:
src: nginx.conf.j2
dest: /etc/nginx/nginx.conf
owner: root
group: root
mode: "0644"
notify: Restart Nginx
handlers:
- name: Restart Nginx
ansible.builtin.service:
name: nginx
state: restarted
The handler runs only if the template task reports a change. If several tasks notify the same handler, it normally runs once at the end of the play.
Operations That May Surprise You
These patterns can make repeated runs less predictable:
# Upgrades whenever newer packages are available
state: latest
# Restarts on every run
state: restarted
# Runs without built-in desired-state knowledge
ansible.builtin.command: some-command
They are not always wrong, but their behavior should be intentional. Package upgrades are often better handled through a controlled maintenance policy than hidden inside every configuration run.
Key takeaway Accurate change reporting builds trust in automation. Use declarative modules, mark read-only commands correctly, and connect configuration changes to service restarts through handlers.