--diff and what it prints · Ansible

--check tells you three files would change. --diff tells you which three lines, in which files.

That is a much larger difference than it sounds, and it is the single most useful artefact this whole part produces. A reviewer cannot audit a change count. They can audit a diff, in the same way they audit a pull request — and unlike a pull request, this diff is rendered against the actual current content of the actual target host, with the actual variables that host will get.

It also prints file contents to standard output, which is where the rest of this lesson comes from.

What a diff establishes

Read-only / Safea predicted change, in full— Verified on ansible-core 2.21.3 in check mode; nothing was written. The destination path is shown here as a documentation path.

$ ansible-playbook -i inv.ini render.yml --check --diff --limit web01.example.com

TASK [Render the application config] *******************************************
--- before
+++ after: /etc/app/app.conf
@@ -0,0 +1,4 @@
+[database]
+host = db01.example.com
+user = appuser
+password = REPLACE_ME

changed: [web01.example.com]

The --- before with no path and @@ -0,0 mean the file does not exist yet; an existing file shows both paths and the changed hunks only.

What that output proves, precisely: the content this task would write differs from the content that is there, in these ways. It is a statement about the file. Whether the resulting configuration is correct, whether the service parses it, whether the value is the one you meant — none of that is in scope, and the previous lessons cover why.

What makes it worth running anyway is that most configuration mistakes are visible in the text. A port that should be 8443 and reads 8080, a hostname pointing at the staging database, an option removed by a template refactor that nobody noticed: all of them are in the diff, and none of them are in a change count.

The disclosure

Look at the last line of that output again.

--diff renders the file. Rendering a template resolves every variable in it, including the ones that came from a vault, an external secret store, or a lookup — because the whole point of rendering is to produce the final content. The final content contains the credential.

The terminal is the least of it

The operator sees the secret, which is usually acceptable — they are deploying it.

The problem is everything else that captured the run:

The CI job log, retained for ninety days and readable by everyone with access to the pipeline, which is a much larger group than the people trusted with the credential.
The log aggregator, if log_path is set or the wrapper pipes output. Indexed, searchable, and replicated.
The scrollback buffer in a shared terminal multiplexer.
The change record, where somebody helpfully pasted the diff as evidence.
The chat channel, where somebody helpfully pasted it again.

A secret that reaches any of those is disclosed and must be rotated. Not “should probably be rotated at some point” — the control that made it a secret has failed, and every log retention policy in the organisation now governs how long it stays disclosed.

The two suppressions, and how they differ

Both exist. They are not interchangeable.

Read-only / Safeplain, diff: false, and no_log: true— Verified on ansible-core 2.21.3 with --check --diff -v. Three identical copy tasks rendering the same variable; only the keyword differs.

$ ansible-playbook -i localhost, secrets.yml --check --diff -v

TASK [Plain, diff shown] *******************************************************
--- before
+++ after: /etc/app/a.conf
@@ -0,0 +1 @@
+password = REPLACE_ME

changed: [localhost] => {"changed": true}

TASK [diff false] **************************************************************
changed: [localhost] => {"changed": true}

TASK [no_log true] *************************************************************
changed: [localhost] => {"censored": "the output has been hidden due to the fact that 'no_log: true' was specified for this result", "changed": true}

	`diff: false`	`no_log: true`
Suppresses the diff	Yes	Yes
Suppresses the rest of the task result	No	Yes, replaced with a `censored` message
Suppresses the task arguments at `-vvv`	No	Yes
You can still see whether the task changed something	Yes	Yes — `changed: true` survives
Suppresses the reason a failure occurred	No	Yes, which is its cost

- name: Render the application configuration
  ansible.builtin.template:
    src: app.conf.j2
    dest: /etc/app/app.conf
    mode: '0640'
  diff: false
  no_log: true

Use diff: false when the file contains a secret and you still want ordinary diagnostics. The task reports success, failure, and its error message normally; only the content is withheld.

Use no_log: true when the task arguments also carry the secret. A copy with content: "{{ db_password }}", a uri with a bearer token in headers, a command with a password in argv — all of those put the secret in the module invocation, where -vvv and a failure traceback will print it regardless of diff: false.

Most template tasks that render a credential want both: diff: false because the rendered file has it, no_log: true because a failure dumps module arguments.

`no_log` makes the task undebuggable at the worst moment

no_log: true replaces the entire result, including the failure message, with the censored string. When that task fails at 02:00, the output tells you it failed and nothing else.

Two things make this survivable:

Keep the secret in one small task. A template that renders one credentials file, no_log on that task alone, and the rest of the role readable. no_log at play or block level is how a whole role becomes opaque.

Have a way to turn it off deliberately. A variable is enough:

  no_log: "{{ not debug_secrets | default(false) }}"

Run with -e debug_secrets=true against a disposable host when you must, never against production, and never in CI. That it is a variable rather than an edit means the emergency version is in the repository, reviewed, rather than improvised by commenting out a line.

One host at a time

The documentation is explicit and the reason is practical:

Diff mode produces a large amount of output, so it is best used when checking a single host at a time.

ansible-playbook foo.yml --check --diff --limit foo.example.com

Two hundred hosts producing a forty-line diff each is eight thousand lines, and the one host whose diff is different from the other hundred-and-ninety-nine is invisible in it. One host is readable, and if the fleet is homogeneous it is also representative — which is what makes the canary the natural next step after it.

Where the fleet is not homogeneous, diff one host per meaningful class rather than one host in total. The classes are usually obvious from the inventory: one per environment, one per distribution version, one per role.

Diff support, and turning it on permanently

Diff mode is a per-module attribute in the same way check mode is:

diff_mode:
  description: Will return details on what has changed (or possibly needs
    changing in check_mode), when in diff mode
  support: full

template, copy, lineinfile, blockinfile, file and user all support it. assert reports diff_mode: none, which is why guards contribute nothing to a diff. command and shell have nothing to diff, so a play built from them produces --diff output that is empty rather than reassuring.

Two configuration settings govern it, and both are worth setting deliberately rather than inheriting:

[diff]
always = false
context = 3

DIFF_ALWAYS — ANSIBLE_DIFF_ALWAYS, default false — makes every run behave as though --diff were passed. It is tempting on a workstation and a bad default on a shared controller, precisely because it removes the moment where somebody decides to print file contents. DIFF_CONTEXT defaults to 3 lines either side of a hunk, and raising it makes diffs more readable and larger.

There is a genuine argument for always = true in a repository with no secrets in any templated file, where the diff is pure benefit. That condition is worth verifying rather than assuming, because it is a statement about every template in the repository including the ones added next quarter.

What happens if the secret has already been printed?

Treat it as disclosed and rotate it. That is the short answer and it is the right one, but the useful part is the sequence, because “rotate the credential” is rarely one action.

Establish the blast radius of the disclosure, not of the change. Which log destinations captured that run: CI, log_path, the aggregator, the terminal multiplexer, anything a callback plugin forwarded. Each has its own retention and its own access list.
Rotate the credential at its source, then redeploy everything that holds a copy. Note that this playbook is probably one of the things that holds a copy, and the rotation run will want diff: false on the task that just leaked.
Do not try to delete the logs. Some of them you cannot reach, some are replicated, and time spent on deletion is time not spent on rotation. Redaction after the fact is a worse control than rotation.
Add the suppression, and check its siblings. One task rendering a secret without diff: false usually means the convention was never established, so the same grep across the repository will find more:
```
grep -rn "no_log" --include='*.yml' roles/ | wc -l
grep -rln "password\|token\|secret\|key" roles/*/templates/ | wc -l
```
If the second number is much larger than the first, the incident was not bad luck.

Knowledge check

Why this matters

--diff is the one thing in this part that changes what a review can actually examine. Everything else produces a verdict — passed, failed, three changes — and a verdict is something a reviewer can only accept or reject. A diff is evidence, and evidence is what makes a review more than a signature.

The reason to be careful with it is that its value and its risk come from the same property: it prints what will really be on the machine. There is no version of --diff that shows you the meaningful changes and hides the sensitive ones, because it does not know which is which — only the person who wrote the template does, and the only place that knowledge can be recorded is diff: false and no_log on the tasks that need them.

Which makes this one of the few genuine security controls that lives in the playbook rather than in a platform. It is worth putting there before the first time somebody pastes a diff into a ticket.