The template Module

The template module is how Ansible turns a .j2 file full of variables into a real config file on the managed node. You give it src — the template on the control node — and dest, where the rendered file goes, and it renders, copies, and reports changed only when the result differs from what is already there. For Larkspur, this is the task that writes /etc/nginx/sites-available/larkspur.conf with the right server_name per environment and /etc/larkspur/app.env with the database host filled in.

The rule for choosing it is simple: reach for template over copy the instant a file contains anything that varies between hosts or environments. A file with even one {{ }} is a template, not a static asset, and shipping it with copy forces you to maintain a near-duplicate per host — exactly the snowflake problem templating exists to kill.

src and dest

src: larkspur.conf.j2 resolves automatically from the role's templates/ directory, so you name the file and Ansible finds it. dest: /etc/nginx/sites-available/larkspur.conf is the absolute path on the target where the rendered output lands. In the same task you set owner, group, and mode on the result, so the file arrives with the right permissions instead of needing a follow-up file task to fix them.

- name: Render the Larkspur nginx vhost
  ansible.builtin.template:
    src: larkspur.conf.j2          # resolved from the role's templates/
    dest: /etc/nginx/sites-available/larkspur.conf
    owner: root
    group: root
    mode: "0644"             # quoted string, not a bare number
    validate: "nginx -t -c %s"  # check the rendered file before it goes live
    backup: true
  notify: reload nginx

Why template Beats copy

copy ships a static file byte-for-byte; template renders variables first. That difference is the whole point. One larkspur.conf.j2 serves web1 and web2 with their own server_name, and staging and prod with their own worker_processes, from a single source. The alternative — a separate file per host kept in sync by hand — rots the moment someone edits one copy and forgets the others.

The tell that a file should be a template is a single {{ }}. The moment a config needs one host-, group-, or environment-specific value, it stops being a static asset and becomes a template. In practice that covers most config files, which is why template is the workhorse and copy is reserved for the genuinely fixed things — a binary, a license file, a config with zero variables.

validate= Before Replacing

validate: 'nginx -t -c %s' runs the config checker against the rendered file before Ansible moves it into place. The %s is the magic part: it expands to the temp path of the new candidate file, not the live one, so nginx tests the file that is about to go in. A broken render fails the task instead of overwriting a working config with one that will not start the service.

The footgun here is hard-coding the path. Writing validate: 'nginx -t -c /etc/nginx/nginx.conf' checks the old file, which is already valid, so validation passes while the broken new file goes in anyway. The %s is what points the checker at the candidate. Every config with a checker has one — visudo -cf %s, sshd -t -f %s — and using it turns a service-breaking typo into a failed task.

backup=yes

backup: true keeps a timestamped copy of the previous file on the target before overwriting it. If a render slips past validation and turns out wrong, you have a known-good file sitting right next to the live one, ready to restore by hand. On a file that gates whether nginx or gunicorn even starts, that is cheap insurance — a few kilobytes against an outage.

It is not a substitute for validate; it is the layer underneath it. Validation stops the bad files it can detect, and the backup catches the ones it cannot — a render that is syntactically valid but semantically wrong, like a correct config pointing at the wrong upstream. Turn both on for any config whose failure takes the service down.

Triggering Handlers

A template task that reports changed is what fires notify: reload nginx. This is where honest changed reporting earns its keep: the rendered config landing identical to what was already there correctly fires nothing, so the service does not churn on every run. Only a real change to the file triggers the reload. Pair every config-file template with a notify: to the matching reload or restart handler, and the service takes effect when the file changes and stays quiet when it does not.