Reading diff output properly · Ansible

changed=3 tells you that three declarations do not match. --diff tells you what does not match, in the only form that lets a human judge whether the difference is a problem.

It is the best review surface Ansible has, and it is incomplete in ways that are not obvious from looking at the output.

What a hunk actually says

Read-only / Safea copy task, in check and diff mode— Executed against ansible-core 2.21.3. The file on disk has MaxClients 150; the declaration says 256. Check mode made no change - the file was still 150 afterwards.

$ ansible-playbook -i inventory.ini site.yml --check --diff

TASK [converge the config] *****************************************************
--- before: /etc/app/live.conf
+++ after: /srv/automation/files/desired.conf
@@ -1,2 +1,2 @@
-MaxClients 150
+MaxClients 256
Timeout 60

changed: [localhost]

Reading it precisely:

before: is the file on the managed host, as it is now.
after: is the content that would be written. For ansible.builtin.copy that label is the source path on the controller, not the destination.
- lines disappear, + lines appear, unprefixed lines are context.
The direction is always “current state on the left, declared state on the right”, which is the opposite of a Git diff reviewing a proposed change to the declaration itself. Both appear in a normal working day and it is worth being conscious of which one you are looking at.

For ansible.builtin.template the after: label is stranger still:

Read-only / Safea template task, in check and diff mode— Executed against ansible-core 2.21.3. The after label points at a controller-side temporary file holding the rendered result.

$ ansible-playbook -i inventory.ini site.yml --check --diff

TASK [render config] ***********************************************************
--- before: /etc/app/live.conf
+++ after: /home/deploy/.ansible/tmp/ansible-local-282623jc626hgd/tmpe6rtyo04/app.conf.j2
@@ -1,2 +1,2 @@
-MaxClients 150
+MaxClients 512
Timeout 60

changed: [localhost]

That path is real. The template is rendered on the controller, into ~/.ansible/tmp, and then compared. Which means a --check --diff run writes the fully rendered configuration — including any secrets it contains — to the controller’s local disk, even though it changes nothing on the target.

Which modules produce a diff at all

diff_mode is a documented attribute, exactly like check_mode, and it varies more than people expect. Read on 2.21.3:

Module	`diff_mode` support
`template`, `copy`, `lineinfile`, `blockinfile`, `replace`, `assemble`, `cron`, `apt`, `dnf`	`full`
`file`, `unarchive`	`partial`
`command`, `shell`, `systemd_service`, `user`, `group`, `get_url`, `wait_for`, `stat`, `setup`	`none`
`service`, `package`	`N/A` (action plugins that dispatch to a concrete module)

Read-only / Safecheck before you rely on it— Prints the diff_mode support level for a module in the installed version. Do this rather than assuming from the module family.

ansible-doc ansible.builtin.file | sed -n '/diff_mode/,+3p'
ansible-doc ansible.builtin.systemd_service | sed -n '/diff_mode/,+3p'

The consequence for a drift report: a task can report changed with no diff at all. systemd_service restarting a unit, user altering a shell, get_url fetching a file — all report a change and show you nothing about what the change is.

So a drift report is two different documents stapled together: the part with diffs, which a reviewer can judge, and the part without, which is just a list of task names. Knowing which findings fall in which half is the difference between reviewing a change and rubber-stamping it.

`no_log` deletes the diff

The interaction is complete rather than partial, and it is worth seeing:

Read-only / Safethe same task, with and without no_log— Executed against ansible-core 2.21.3 under --check --diff. The first task carries no_log: true and produced no diff body at all; the second is identical apart from the keyword.

$ ansible-playbook -i inventory.ini nolog.yml --check --diff

TASK [secret-bearing config, no_log on] ****************************************
changed: [localhost]

TASK [same, no_log off] ********************************************************
--- before: /etc/app/live.conf
+++ after: /srv/automation/files/desired.conf
@@ -1,2 +1,2 @@
-MaxClients 150
+MaxClients 256
Timeout 60

changed: [localhost]

no_log: true gives you changed and nothing else. That is exactly what it is for, and it creates a genuine conflict:

Without no_log, a diff of a rendered template prints its contents — database passwords, API tokens, private keys — into the run log, and from there into CI output, chat notifications, and log aggregation, where they are retained and searchable.
With no_log, the most sensitive files in your estate are exactly the ones nobody can review, and drift in them is reported as a count with no detail.

Diff patterns that are not drift

A useful skill is recognising the diffs that indicate a defective declaration rather than a changed host. Four common ones:

A timestamp in a managed header. A template whose header renders Generated at {{ ansible_date_time.iso8601 }} differs on every single run, on every host, forever. The diff is one line and it is always there. This one also breaks handlers: the file is rewritten every run, so the notify fires every run, and the service is restarted nightly for no reason.

Whitespace and line-ending churn. A diff where every line is both removed and added is usually a trailing-newline or CRLF difference, not a content change. Look at the hunk header: @@ -1,40 +1,40 @@ on a file nobody edited is the signature.

Reordered lines. A template iterating a dictionary can emit keys in a different order than the file on disk has them. The content is equivalent and the diff is large. Sort explicitly in the template.

The whole file as additions. @@ -0,0 +1,120 @@ means the file does not exist on the host. That is not drift in the “someone edited it” sense; it is a host that has never had this configuration, which is usually either a new host or a when condition that has been excluding it.

Read-only / Safecapture the diff as the reviewable artefact— Runs the check with diff and keeps the output. This file is what gets attached to the change record or the pull request - the evidence of what the change would do, host by host.

ansible-playbook -i inventory/ site.yml \
--limit wave1_canary \
--check --diff \
| tee "artifacts/diff-$(date +%Y%m%dT%H%M%S)-$(git rev-parse --short HEAD).txt"

Naming the file after the commit matters for the same reason it did in the runtime-budget work: a diff is only interpretable against the version of the content that produced it.

Under the hood

Diff mode is not implemented by the engine either. A module that supports it returns a diff key in its result — either {"before": ..., "after": ...} with strings, or {"before_header": ..., "after_header": ...} alongside them — and the callback plugin renders it.

That is why the after: label is a file path rather than a description: the module puts the path it was going to install into after_header, and for template that path is the controller-side temporary file holding the rendered output, because that is genuinely what would be copied into place.

It also explains why some modules produce a diff of dictionaries rather than text. Nothing constrains before and after to be file contents; a module managing a structured resource can return the old and new dictionaries and the callback will render them. And it explains no_log completely: the callback suppresses the entire result payload for that task, and the diff is part of the payload.

What happens if you diff the whole fleet at once?

You get an artefact nobody reads, which is the same as having none.

A --check --diff run over two thousand hosts produces two thousand copies of largely identical diffs. The information content is small — usually a handful of distinct differences repeated many times — and the volume is enormous.

Three things make it usable:

Run the diff against a representative subset, not the fleet. The canary set from the wave work is the right population: it spans the variation, so distinct differences show up, and it is small enough to read.

Group by difference rather than by host. The question worth answering is “how many distinct drifts exist and how many hosts does each affect”, which is a hash of the diff body and a count, not a transcript.

And keep the per-host counts from the recap separately. Those trend well and are cheap to store; the diff bodies are for investigating a specific finding, not for archiving.

What a hunk actually says

Which modules produce a diff at all

no_log deletes the diff

Diff patterns that are not drift

Knowledge check

`no_log` deletes the diff