Template a drop-in, not the whole file · Ansible

The default assumption in this part has been that Ansible owns the file: the template is the source of truth, anything on the host is replaced, and drift is corrected on the next run. That is the right model and it is what makes changed=0 meaningful.

Sometimes you cannot have it. The file is shipped by a package that rewrites it on upgrade. Another team edits it. It contains a section generated by a different tool. Ownership is not available, and the question becomes what to do instead.

Three ways to own less than a file, ranked

1. Template a drop-in. Ansible owns a whole file in a directory the service includes. Full ownership, smaller scope. This is the right answer whenever the service supports it.

2. Manage a marked block with blockinfile. Ansible owns a delimited region of somebody else’s file. Workable, and it is the second choice for a reason.

3. Manage individual lines with lineinfile. Ansible owns a regex match. This is the option that produces the surprises, and the files part covers when it is genuinely appropriate.

The gap between the first and the rest is larger than the gap between the second and third. A drop-in gives you back everything: full-file replacement, atomic writes, validate:, a clean diff, and the ability to answer “what does Ansible manage here” by listing a directory.

Which services support drop-ins

More than people expect. The convention is close to universal on modern Linux:

Service	Drop-in location	Notes
systemd units	`/etc/systemd/system/<unit>.service.d/*.conf`	Overrides the packaged unit; needs `daemon_reload`
nginx	`/etc/nginx/conf.d/*.conf`	Inside the `http` context
sudo	`/etc/sudoers.d/*`	`visudo -cf` validates a fragment properly
sshd	`/etc/ssh/sshd_config.d/*.conf`	Where the distribution’s `sshd_config` has the `Include`
systemd-networkd, logind, journald	`<name>.conf.d/*.conf`	Same convention throughout
APT	`/etc/apt/apt.conf.d/*`
sysctl	`/etc/sysctl.d/*.conf`
logrotate	`/etc/logrotate.d/*`
PAM, cron, udev, modprobe	various `.d` directories

The example

Configuration changeowning a fragment completely— A whole file, fully templated, validated, with a header - inside a directory the service includes.

- name: Deploy the reverse proxy site definition
ansible.builtin.template:
  src: site.conf.j2
  dest: /etc/nginx/conf.d/10-{{ app_name }}.conf
  owner: root
  group: root
  mode: '0644'
  validate: nginx -t -c %s
notify: Reload nginx

Note the numeric prefix. Include globs are read in sorted order, and the order matters for anything where later directives override earlier ones. 10-, 20-, 50- makes the ordering explicit and leaves room to insert; a bare {{ app_name }}.conf makes it alphabetical by application name, which is an ordering nobody chose.

The validate on that task hits the fragment problem from the previous lesson — nginx -t -c will reject a bare server block. For this specific case the workaround is a wrapper: a minimal staging configuration that wraps the fragment in an http block. Whether that is worth building is a judgement call, and if it is not, the honest answer is to leave validate off this task and rely on the canary instead of pretending the check is there.

What a drop-in actually buys

A smaller diff. The change under review is the fragment, not a 400-line file where three lines differ. Reviewers read small diffs properly and skim large ones.

A smaller blast radius. A mistake in a drop-in breaks the feature that drop-in configures. A mistake in a whole templated nginx.conf breaks every site on the host, including the ones that had nothing to do with the change.

A clean answer to provenance. ls /etc/nginx/conf.d/ tells an operator on the box exactly which files are managed. With blockinfile and lineinfile, that question requires reading files and recognising marker comments.

Package upgrades stop being a conflict. The package owns its file and can rewrite it freely; your drop-in is untouched. With a lineinfile edit, an upgrade can silently revert your change — and Ansible will silently re-apply it on the next run, so the setting oscillates and nobody notices until the window between the two matters.

Removal is state: absent on a file. Undoing a lineinfile means knowing what the line was before, which nothing records.

Partial ownership of one file is the worst option

Ranking the three models by how well they answer “what is the correct content of this file”:

Ansible owns the file. The template answers it.
Ansible owns a drop-in. The template answers it for the drop-in; the package answers it for the base.
Ansible owns some lines in a file somebody else also edits. Nothing answers it. The file’s content is a function of the template, the package version, and every manual edit anyone has made, in the order they happened.

The third produces hosts that differ in ways nothing records, which is the definition of a snowflake. The drift part is largely about the consequences.

If a file genuinely must be co-owned, write down who owns which part — in the role’s README, in a comment in the file, in the change process — and accept that you have taken on a manual coordination cost that automation will not remove.

When a whole file is still right

Drop-ins are not automatically better. Take the whole file when:

The service has no include mechanism. Many application configs do not, and forcing one is not your job.
Ansible genuinely is the source of truth. If nothing else writes the file and no package rewrites it, owning it outright gives the strongest guarantee available and the simplest mental model.
The configuration only makes sense as a whole. A file whose directives interact heavily is easier to reason about in one template than split across fragments whose combined effect nobody can see.
validate: needs the complete file. Owning the whole thing makes the parameter work, and giving that up for a smaller diff is usually a bad trade.

Read-only / Safeanswering the provenance question on a host— Read-only. The generated header and the directory listing together tell an operator what is managed and what is not.

$ ls -la /etc/nginx/conf.d/ && head -3 /etc/nginx/conf.d/10-billing.conf

total 20
drwxr-xr-x 2 root root 4096 Aug 11 09:14 .
drwxr-xr-x 6 root root 4096 Aug 11 09:14 ..
-rw-r--r-- 1 root root 1204 Aug 11 09:14 10-billing.conf
-rw-r--r-- 1 root root  318 Jul 02 16:41 default.conf

# Ansible managed - roles/webserver/templates/site.conf.j2
# Do not edit on the host; changes are overwritten on the next run.
# Source of truth: git.example.com/infra/ansible

The header is the subject of the next lesson. It is what turns a directory listing into an answer.

Under the hood

There is no drop-in mechanism in Ansible. This is entirely a property of the service: a glob include in its configuration parser, and a convention about where the directory lives.

That is worth being explicit about, because it decides what you can do. Ansible cannot make a service support fragments. If the parser reads one file, one file is what you manage.

The systemd case is the most structured version and worth understanding because the pattern recurs. A file in /etc/systemd/system/nginx.service.d/override.conf is merged with the packaged unit rather than replacing it: most directives are overridden by the drop-in, but list-valued directives such as ExecStart append unless you first clear them with an empty assignment. That is a real trap — an override that adds a second ExecStart rather than replacing the first — and systemctl cat nginx.service shows the assembled result including every drop-in, which is the diagnostic.

The general lesson generalises past systemd: when a service assembles configuration from fragments, ask the service what it assembled. nginx -T, sshd -T, systemctl cat, sudo -l. The fragment on disk is your intent; the assembled output is the configuration. Reviewing the first and assuming the second is how a correct drop-in ends up having no effect.

What happens if someone deletes the drop-in by hand?

The next run puts it back, and reports changed.

That is the drop-in model working exactly as intended, and it is a better outcome than the equivalent for lineinfile, where a hand-edited line produces a re-application that may or may not restore the original meaning depending on how the regex matches what is now there.

The interesting question is whether you find out. A changed on a file task during a routine run, on a host where nothing was supposed to change, is drift — and it is exactly the signal changed=0 runs make visible. If your scheduled runs are green apart from one host that reports changed=1 every time, somebody is editing that host by hand between runs, and the recap has been telling you so.

Which is the whole argument for keeping the recap trustworthy: it only works as a drift detector if nothing else in the play reports changed spuriously.

Knowledge check

Why this matters

The question an operator asks at two in the morning is “what does Ansible manage on this host, and what did somebody do by hand?”

With drop-ins, the answer is a directory listing and a header comment. With a whole-file template, the answer is the template. With lineinfile scattered across files another team also edits, there is no answer — the file’s content is a history, not a state, and reconstructing it means reading the role, the package changelog and whatever anyone remembers doing.

The technical benefits are real: smaller diffs, smaller blast radius, no fight with package upgrades, clean removal. But the reason to reach for a drop-in first is the operational one. It keeps the host’s configuration explainable, and explainable is what you need when the person who wrote the role is not the person on call.