Which file module, and why · Ansible

Six modules in ansible.builtin put content into a file on a managed node: copy, template, file, lineinfile, blockinfile and assemble. They are not six styles of doing the same thing. They differ in one property that matters more than any of their options:

how much of the file’s contents the automation declares.

template declares all of it. lineinfile declares one line and says nothing about the other four hundred. That difference decides whether a reviewer reading your repository can answer “what is in /etc/chrony.conf on web03?” without logging into web03.

The decision, stated first

Module	Declares	Choose it when
`template`	The entire file	You own the file and any part of it varies by host, group or environment
`copy`	The entire file	You own the file and it is byte-identical everywhere
`blockinfile`	A marked region	You own part of a file that something else also writes
`lineinfile`	One line	You need one setting changed in a file owned by a vendor or a package
`assemble`	The whole file, from fragments	The program has no `conf.d` directory and several roles must each contribute a stanza
`file`	Metadata only	The thing you are managing is a directory, a symlink, permissions, or an absence

Read that table as a preference order from the top. Each row down gives away a little more of your ability to say what the file contains.

Why “declared state” is the axis

Consider a /etc/ssh/sshd_config managed by eleven lineinfile tasks. Every one of them is idempotent. Every one has a regexp, a line, and a passing test. The play runs green.

Now answer this: is X11Forwarding disabled on your fleet?

You cannot tell from the repository. Eleven tasks say what eleven settings should be; the file has roughly ninety directives and a distribution default for each one you did not name. Nothing in your automation records the other seventy-nine. If a package upgrade changes a default, the run stays green and the behaviour changes.

Now the same file as a template. The answer is: open templates/sshd_config.j2 and read it. Every directive that will exist on the host is in that file, in review, in Git history, with a blame line naming who changed it and when.

`copy` versus `template`

copy transfers a file unchanged. template renders it through Jinja2 on the controller first, then transfers the result. Two documented constraints push more work towards template than people expect.

The first is about variables. The copy module’s content option sets a file’s contents from a string, and it is tempting to build that string from a variable. Upstream is explicit:

If you need variable interpolation in copied files, use the ansible.builtin.template module. Using a variable with the content parameter produces unpredictable results.

The reason is that content is typed str and receives whatever the templating layer produced — a multi-line string, a rendered data structure, or a type that stringifies differently than you expect. There is no rendering step you control. template gives you one.

The second is about scale. copy will recurse into a directory, and the module’s own notes cap that:

The ansible.builtin.copy module recursively copy facility does not scale to lots (> hundreds) of files.

The mechanism is in the action plugin: a recursive copy enumerates the tree on the controller and issues per-file operations. For a handful of files it is fine. For a release artefact of ten thousand files it is a slow, chatty run whose failure mode is a task that appears to hang. Ship an archive and use ansible.builtin.unarchive, or use ansible.posix.synchronize, and say in a comment why.

Configuration changethe same intent, three ways— Only the third declares the file's contents in a form that varies correctly per host.

# Wrong: content built from a variable. Documented as unpredictable.
- name: Write the chrony config
ansible.builtin.copy:
  dest: /etc/chrony/chrony.conf
  content: "{{ chrony_config_body }}"
  mode: '0644'

# Right, but only if the file is byte-identical on every host.
- name: Install the shared chrony config
ansible.builtin.copy:
  src: chrony.conf
  dest: /etc/chrony/chrony.conf
  owner: root
  group: root
  mode: '0644'

# Right when anything varies - the servers, the region, the drift file.
- name: Render the chrony config
ansible.builtin.template:
  src: chrony.conf.j2
  dest: /etc/chrony/chrony.conf
  owner: root
  group: root
  mode: '0644'
  validate: /usr/sbin/chronyd -f %s -p

When a single line is the right answer

The course’s preference for whole-file management is not a prohibition. There is a shape of problem where lineinfile is the correct and maintainable choice, and it has a clear test:

You do not own the file.

The package owns it. The vendor ships it. An upgrade will replace it, and you want that upgrade to bring its new defaults. You need exactly one setting different from the shipped value.

Examples that pass the test:

/etc/default/grub on a Debian-family host — package-managed, replaced on upgrade, and you want one kernel parameter.
A vendor agent’s /opt/vendor/agent.conf where the vendor’s support policy is void if you replace the file.
/etc/sysctl.conf on a system where a sysctl.d drop-in is not honoured by the boot sequence you are stuck with.

Examples that fail it, and are the ones you meet in practice:

sshd_config, nginx.conf, chrony.conf, rsyslog.conf, sudoers — you own the policy in every one of those, and every one is routinely mismanaged by a pile of line edits.

`assemble`, and the case for it

assemble concatenates a directory of fragments into one destination file. Upstream describes the problem it solves precisely:

Often a particular program will take a single configuration file and does not support a conf.d style structure where it is easy to build up the configuration from multiple sources.

Files are joined in string sorting order, which is why fragments are conventionally named 00-header, 10-auth, 90-footer. Its useful options are regexp to filter which fragments participate, ignore_hidden (default false, so editor backups do get included unless you set it), delimiter, and validate.

Configuration changeassemble with validation— Fragments contributed by several roles, concatenated in sort order, validated before the file is put in place.

- name: Build sudoers from role fragments
ansible.builtin.assemble:
  src: /etc/sudoers.d.fragments
  dest: /etc/sudoers.assembled
  remote_src: true
  ignore_hidden: true
  regexp: '^[0-9]{2}-'
  owner: root
  group: root
  mode: '0440'
  validate: /usr/sbin/visudo -cf %s

Its cost is that the destination file’s contents are declared by the set of fragments present on the host, which is one indirection further from the repository than a template. Use it when several independent roles genuinely must contribute, and the program refuses a drop-in directory. If one role owns the file, template it.

Under the hood

copy, template, assemble and fetch are marked in ansible-doc with action: support: full — they have a corresponding action plugin, which is controller-side code that runs before the module does. This is what lets template read a .j2 file from your repository and render it with the host’s variables: the rendering happens on the controller, and only the result crosses the wire.

It is also why template has no remote_src option. There is nothing to render remotely; the Jinja environment and your templates/ directory both live on the controller.

lineinfile and blockinfile have no action plugin. They are ordinary modules that ship to the target and operate on a file already there, which is why they can edit a file that never existed in your repository — and why they cannot see your repository at all.

Reading the choice back out of a repository

The practical test for a reviewer is a grep, not an opinion.

Read-only / Safefind files managed line by line— Read-only. Groups every lineinfile and blockinfile task in the repository by the file it targets.

grep -rhA5 'ansible.builtin.lineinfile\|ansible.builtin.blockinfile' roles/ \
| grep -oP '^\s+(path|dest):\s*\K\S+' \
| sort | uniq -c | sort -rn

Read-only / Safewhat the counts mean— Illustrative output from a repository of the shape this lesson describes. The number is how many separate tasks edit that file.

$ grep -rhA5 'lineinfile' roles/ | grep -oP '(path|dest):\\s*\\K\\S+' | sort | uniq -c | sort -rn

     11 /etc/ssh/sshd_config
    6 /etc/security/limits.conf
    4 /etc/sysctl.conf
    1 /etc/default/grub

Illustrative output

The bottom line is fine: one setting, one vendor file. The top line is the finding. Eleven tasks against sshd_config is not eleven small problems, it is one file whose contents nobody has written down.

What happens if I template a file the package also updates?

Your rendered file wins, permanently, and the package’s new defaults never arrive.

On Debian-family systems, dpkg treats a modified conffile as a conflict and — in a non-interactive Ansible run — keeps your version and writes the new one alongside as .dpkg-dist. On RPM systems the new file lands as .rpmnew. Either way, the upgrade’s changed defaults sit in a file nobody reads.

That is the correct outcome when you meant to own the file: you get what you declared, and the fleet does not shift under you. It is the wrong outcome when you took over a vendor file to change one setting, which is exactly why that case belongs to lineinfile.

Whichever you chose, add the check to your upgrade runbook: find /etc -name '*.dpkg-dist' -o -name '*.rpmnew' tells you which declared files have pending upstream changes.

The decision, stated first

Why “declared state” is the axis

copy versus template

When a single line is the right answer

assemble, and the case for it

Reading the choice back out of a repository

Knowledge check

`copy` versus `template`

`assemble`, and the case for it