Whitespace Control and Mistakes

Jinja2 keeps the whitespace around its tags, so a control tag leaves behind the newline and the indentation of the line it sat on. In plain Jinja2 a {% for %} loop renders one blank line per iteration; Ansible's template module drops that newline by default, but a loop indented to match its block still comes out with every line under it pushed out of place. Blank lines are noise in a diff, and the indentation is worse — in a YAML file it stops the parse. The fix is trim markers ({%- and -%}) and the trim_blocks / lstrip_blocks settings, which strip the newline and leading space a control tag leaves behind.

This is also the topic that collects the templating footguns that bite once a file stops being trivial: how undefined variables behave, and why a variable that happens to contain {{ }} gets re-rendered as if it were a template. None of these are exotic. They are the everyday ways a working template starts producing noisy diffs or silent wrong output, and each has a clean fix once you know it is there.

The Blank-Line Problem

In plain Jinja2, a {% for host in groups['web'] %} line, the matching {% endfor %}, and any {% if %} each leave their own newline in the output: every control-tag line that printed nothing still leaves the newline that followed it in the source, so a loop over five hosts renders five blank lines into the upstream block. Ansible's template module turns trim_blocks on by default, which removes exactly that newline, so the same loop renders tight there. The blank lines come back the moment a task sets trim_blocks: false, or the template is rendered by plain Jinja2 outside Ansible. Nginx and PostgreSQL both skip blank lines, so the cost is noisy diffs, not a broken file.

Trim Markers

{%- strips whitespace before the tag, and -%} strips it after. One dash is enough for the loop: {% for ... -%} eats the newline after the for line, so each iteration renders as one server line, with trim_blocks on or off. The dashes are surgical — you put them exactly where a stray newline is coming from, and leave the rest of the tag alone.

# no trim markers: tight with trim_blocks: true (the template module default),
# one blank line per iteration with trim_blocks: false or plain Jinja2
{% for host in groups['web'] %}
server {{ hostvars[host]['ansible_host'] }}:8000;
{% endfor %}

# a dash after the for tag: tight with trim_blocks on or off
{% for host in groups['web'] -%}
server {{ hostvars[host]['ansible_host'] }}:8000;
{% endfor %}

# a dash on endfor too: over-trimmed, every server on one line
# renders: server 10.0.1.11:8000;server 10.0.1.12:8000;
{% for host in groups['web'] -%}
server {{ hostvars[host]['ansible_host'] }}:8000;
{%- endfor %}

The danger is over-trimming. Put a dash on the endfor as well and it eats the newline at the end of each server line, so both hosts render as one fused line — the last loop in the block above. That collapses two directives onto one line and breaks the file far more thoroughly than the blank lines did. Trim markers cut both ways: under-trimming leaves noise, over-trimming fuses lines. The cure for both is to look at the rendered output, not the template, when deciding where a dash belongs.

trim_blocks and lstrip_blocks

Sprinkling a dash on every tag gets tedious, so Jinja2 offers two settings that do it wholesale. trim_blocks removes the first newline after a block tag, and lstrip_blocks strips the leading whitespace before one. Both are options on the template task, and a header line at the top of a template can override them for that one file. The module already has trim_blocks on by default, which is why a plain loop renders tight in Ansible. lstrip_blocks is off, and it is the one to turn on for config templates: with it, a tag indented to match its block no longer leaks those spaces into the output, and the lines under it keep the indentation you wrote.

upstream app {
    {% for host in groups['web'] %}
    server {{ hostvars[host]['ansible_host'] }}:8000;
    {% endfor %}
}

# rendered with lstrip_blocks: false (the default)
upstream app {
        server 10.0.1.11:8000;
        server 10.0.1.12:8000;
    }

# rendered with lstrip_blocks: true
upstream app {
    server 10.0.1.11:8000;
    server 10.0.1.12:8000;
}

The trade-off is that these settings change the bytes of existing templates too. Flip them on a template that quietly relied on the old whitespace and its output shifts, sometimes in ways that matter. That is not a reason to avoid them — it is a reason to flip them deliberately, with the rendered diff in front of you, rather than as an afterthought that silently rewrites a dozen config files at once.

Undefined-Variable Behavior

By default, an undefined variable raises an error at render time. That strictness is exactly what you want for config files: a typo in a variable name fails the play loudly instead of rendering a blank into app.env and letting the app boot with a missing setting. The default is your friend, and the instinct to loosen it — so a missing variable "just renders empty" — is a bug waiting to ship a half-blank config.

The right way to handle a genuinely optional value is not to rely on undefined-becomes-empty but to guard it explicitly with default. {{ optional_setting | default('off') }} says out loud what the missing-value behavior is, where depending on silent emptiness leaves it implicit and fragile. Strict by default, explicit defaults where you mean them — that combination keeps a missing variable from ever silently reaching a live file.

Recursive Templating

Ansible re-renders a variable whose value itself contains {{ }}. That is usually a feature: a group_vars value like base_url: "https://{{ domain }}" resolves correctly because Ansible templates the value before using it. The problem is when a value contains literal braces it did not mean as template syntax — a regex like {{2,4}}, a Prometheus query, a password that happens to contain {{. Ansible tries to evaluate it as a template and either fails or mangles the value.

The fix is to mark the value as not-to-be-templated. Wrap it in {% raw %}...{% endraw %} in a template, or tag it !unsafe in a vars file, and Ansible leaves the braces alone. This is the last footgun in the chapter and the most surprising, because the data looks fine until the one run where a password with the wrong character in it brings down a deploy with an error about an undefined template variable that you never wrote.