Anti-pattern: tasks that always change, or never do · Ansible

changed is a single boolean, and an unusual amount of this course rests on it. Handlers fire on it. The recap counts it. Drift detection reads it. The audit trail your compliance team looks at is a summary of it.

The anti-pattern is a changed result that does not correspond to a change. It has two directions and they fail completely differently.

Direction 1: always changed

Service impact possiblea task that reports a change on every run— SERVICE-IMPACT: the notified handler restarts a service. The command is a read, so nothing changes - but command reports changed on exit code zero, which is all it can observe.

- name: Regenerate the application configuration
ansible.builtin.command:
  cmd: /srv/app/bin/generate-config
notify: Restart app

Read-only / Safewhat command reports, with and without changed_when— Real output from ansible-core 2.21.3. Two identical read-only commands; the second has no changed_when and is reported as changed. This is the default behaviour, not a defect in the command.

$ ansible-playbook -i inventory/hosts.yml shellish.yml

TASK [Query the effective user] ************************************************
ok: [localhost]

TASK [The same query with no changed_when] *************************************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

The failure. The handler fires on every run. On a nightly play across three hundred hosts, that is three hundred service restarts a night on a fleet where nothing changed.

The consequences compound:

User-visible impact. Every restart drops connections, empties caches and produces a latency spike. Nightly, forever.
The recap becomes noise. changed=300 every night means changed=300 carries no information, so the night something genuinely changes is indistinguishable.
Diagnosis is hard out of proportion to the cause. The symptom is “the application restarts at 02:00 and nobody knows why”. The investigation starts with systemd, the package manager and cron. The cause is one missing changed_when in a role three levels deep.

The diagnostic that finds it in one command

Run the play twice against a converged host. The second run should report changed=0. Whatever it reports as changed is either a genuine change you have not noticed, or this defect.

ansible-playbook site.yml --limit canary
ansible-playbook site.yml --limit canary   # changed=0 expected

That is the idempotence test from Part XII used as a diagnostic rather than as a principle, and it takes two minutes.

Direction 2: never changed

Service impact possiblethe blanket suppression— SERVICE-IMPACT: the task rewrites a configuration file on every run. changed_when: false only silences the report.

- name: Write the application configuration
ansible.builtin.command:
  cmd: /srv/app/bin/write-config --output /etc/app/app.conf
changed_when: false
notify: Restart app

This gets added for an understandable reason: the recap was noisy, and changed_when: false made it quiet. It is direction 1 apparently fixed, and it is much worse.

The failure, part one: the handler never fires. notify acts only on a genuine changed result. The configuration file is rewritten and the service is never restarted, so it keeps running the old configuration. The repository, the recap and the drift report all agree that the host is converged. The host disagrees, and nothing asks it.

The failure, part two: drift becomes invisible. Part XXXVI’s drift detection is a check-mode run whose changed results are the drift report. A task hard-coded to changed_when: false reports no drift whatever the host’s state — so the one mechanism designed to catch a host that has quietly diverged is blind on exactly that task.

The line between the tool and the anti-pattern

changed_when is taught in earnest in Part XII, and it is the right answer to a real problem. The distinction is exact:

	Precision tool	Anti-pattern
Value	Derived from the command’s own evidence	Hard-coded `false`
Effect	Reporting matches what happened	Reporting contradicts what happened
Test	If the task changed something, this would say so	It would not

Configuration changethe same task, done three ways— CONFIGURATION for the third form only; the first two are read-only. Only the third both acts and reports accurately.

# Honest: this task genuinely changes nothing, and says so.
- name: Read the current version
ansible.builtin.command:
  cmd: /srv/app/bin/version
register: app_version_out
changed_when: false
check_mode: false

# Honest: the answer is derived from the command's own output.
- name: Reload the ruleset if it differs
ansible.builtin.command:
  cmd: /usr/sbin/nft -c -f /etc/nftables.conf
register: nft_check
changed_when: nft_check.rc == 1
failed_when: nft_check.rc not in [0, 1]

# Better still: a module that knows what it manages.
- name: Write the application configuration
ansible.builtin.template:
  src: app.conf.j2
  dest: /etc/app/app.conf
  validate: '/srv/app/bin/check-config %s'
notify: Restart app

The third form is the one to reach for. template compares the rendered content against what is on the host and reports changed only when they differ — so the handler fires exactly when it should, --check shows what would change, and --diff shows the content. All three properties come from using a module that understands its subject, which is the same argument as lesson 1 of this part.

Auditing a fleet for it

Read-only / Safefind the suppressions and the always-changers— READ-ONLY: greps the repository and reads previous run logs. The second command is the one that finds direction 1, which grep cannot see.

cd /srv/ansible

# Hard-coded suppressions, which need reviewing individually.
grep -rn 'changed_when:\s*\(false\|False\|no\)'    --include='*.yml' --include='*.yaml' .

# Files containing a command/shell task but no changed_when anywhere -
# candidates for direction 1, since those tasks report changed on every
# successful run.
grep -rlE '^\s*(ansible\.builtin\.)?(command|shell):'    --include='*.yml' . | xargs grep -L 'changed_when'

# ansible-lint names them directly, task by task.
ansible-lint --profile production

# The behavioural test: two runs, second should be changed=0.
ansible-playbook site.yml --limit canary
ansible-playbook site.yml --limit canary

For every hard-coded changed_when: false, ask whether the task genuinely changes nothing. If it does change something, that is a defect, and the handler downstream of it is not firing.
For every command/shell task with no changed_when, decide: is it a read, in which case changed_when: false is honest, or does it act, in which case derive the value from evidence.
Run the play twice on a canary and treat any changed on the second run as a finding to explain.
Check what each affected handler does. A restart storm on a stateless web tier is annoying; on a database or a message broker it is an outage.
Add ansible-lint no-changed-when to CI so the count cannot grow again silently.

Under the hood

Where does changed actually come from, and why can it not be checked?

It is a key in the JSON document the module returns. ansible-core reads it, records it, and acts on it — notifying handlers, incrementing the recap counter, exposing it on the registered variable. There is no verification step anywhere, because ansible-core has no way to observe the module’s subject and therefore no way to form an opinion about whether anything changed.

changed_when is applied afterwards, as a post-processing step. The module runs, returns its result, and then the conditional is evaluated against that result and overwrites the changed key. This is why changed_when cannot make a task idempotent: by the time it is evaluated, the task has already done whatever it does. It is a statement about the report, not about the behaviour, and that ordering is the whole reason the anti-pattern exists.

Handlers then consume the final value. A notify is registered only when the post-processed changed is true, which is why the two directions produce the two failures: an always-true value notifies constantly, and a hard-coded false value never notifies at all, regardless of what the module reported.

The design consequence is worth naming, because it recurs throughout this part. ansible-core provides mechanisms and delegates all semantics to modules and to the person writing the play. That is what makes it capable of managing anything with an interface — and it means the guarantees people assume they have are guarantees somebody has to supply. changed is not a fact the system determines. It is a claim, and this anti-pattern is what happens when the claim is made carelessly in either direction.

What happens if a task must run every time but should not trigger handlers?

A legitimate requirement — a metrics push, a heartbeat, a cache warm — and there is a correct way to express it that is not changed_when: false on something that acts.

If it genuinely changes nothing on the host, changed_when: false is honest. A task that posts a metric to a remote system changes nothing about the managed node, and reporting ok rather than changed is accurate rather than a suppression. This is the common case and it is not the anti-pattern.

If it does change something, report it and control the handler instead. Keep changed truthful and remove the notify, or move the restart behind a condition that reflects when a restart is actually needed. The handler subscription is the thing you want to change, not the truth value.

If the recap noise is the real problem, fix the noise properly. A task that legitimately changes something every run is telling you something about the design — usually that an imperative operation is sitting in a converge playbook and belongs in its own play, on its own schedule, where a changed on every run is expected and meaningful.

Where nothing else fits, an explicit comment carries the decision forward:

- name: Push the metrics snapshot
  ansible.builtin.command:
    cmd: /usr/local/bin/push-metrics
  # Changes nothing on this host; the effect is entirely on the
  # metrics service, so reporting a change here would be wrong.
  changed_when: false

The reviewable difference between that and the anti-pattern is one line of English stating why the value is correct. Nothing enforces it, and it is still the thing that stops the next person copying the pattern onto a task that does modify the host.

Knowledge check

Why this matters

changed is the smallest piece of state in this entire course and it carries the most weight. One boolean per task decides whether a service restarts, whether the recap means anything, whether drift detection can see, and whether the audit record describes reality.

Both directions of this anti-pattern end in the same place: nobody trusts the recap. Always-changed makes the value meaningless by never varying; never-changed makes it meaningless by never being set. Once the team learns the recap does not tell them anything, the nightly drift report becomes a page nobody opens, and the question “has anything on these hosts diverged” stops having an answer.

That is a much larger loss than the restart storm, and it is quieter. A restart storm is visible and gets fixed because it annoys people. A suppressed changed produces no symptom at all until the day somebody needs to know whether a host matches its repository, and finds that the mechanism for answering that was disabled three years ago in a commit whose message was “reduce recap noise”.

The corrected form is almost always the same move as lesson 1: use a module that knows what it manages, and let it decide. template compares content and reports honestly. Reaching for command plus a hand-written changed_when means taking on a judgement the module would have made for you.