Jinja2 Fundamentals

Jinja2 is the templating engine Ansible uses everywhere a value can vary. The template module renders it into config files, but it does far more than that: when: conditions, loop expressions, and nearly every string in a playbook run through Jinja2 too. There are two delimiters to learn. {{ expr }} substitutes the value of an expression into the output, and {% ... %} runs control flow — if, for, set — without printing anything itself.

Once you see that {{ }} means "print this" and {% %} means "do this," the syntax stops being magic and becomes two tools with one job each. Everything in this chapter — the template module, filters, tests, lookups — is built on those two delimiters and one fact that catches everyone off guard: the rendering happens on the control node, not on the server the file lands on.

The Two Delimiters

{{ ansible_hostname }} prints the host's name into the output. {% if env == "prod" %} makes a decision and renders nothing on its own — it gates whatever sits between the if and its endif. {# this never reaches the file #} is a comment that vanishes during rendering. Those three forms make up every template you will ever write: print a value, run logic, leave a note. There is nothing else to the syntax.

The split matters because the two forms are not interchangeable. A {{ }} that wraps an if is a syntax error, and a {% %} that you expect to emit a value renders empty. The mental model is mechanical: braces-with-braces is an expression that resolves to text, brace-percent is a statement that controls flow. Keep them in separate boxes in your head and the templates read cleanly.

# {{ }} prints a value into the rendered file
server_name {{ larkspur_server_name }};

# {% %} runs logic and prints nothing itself
{% if env == "prod" %}
access_log /var/log/nginx/larkspur.access.log;
{% endif %}

# {# #} is a comment that never reaches the output file
{# bump worker_connections when we add the third web host #}

Variables and Facts Inside Templates

Anything in scope on the host is reachable inside a template. A group_vars value like nginx_worker_processes, a result you registered earlier in the play, or a gathered fact like ansible_processor_vcpus are all just names you can drop into a {{ }}. That is what lets a template size itself to the machine it lands on — the same larkspur.conf.j2 can set worker_processes to the host's actual vCPU count rather than a hard-coded guess that is wrong on half the fleet.

Facts are where templating earns its keep, because they describe the real machine, not your assumptions about it. A template that reads ansible_default_ipv4.address binds nginx to whatever IP the host actually has, and one that reads ansible_distribution branches on the OS without you tracking which box runs what. The catch is that a fact only exists if facts were gathered — reference one on a play that ran with gather_facts: false and the variable is simply undefined.

Where Templating Happens

Jinja2 is not confined to .j2 files. A when: env == "prod" condition is implicitly templated, a msg: "Deploying {{ release }}" in a debug task is templated, and a vars: value can reference another variable, which Ansible resolves by running it through Jinja2. The engine runs across most string values in a playbook, which is the real reason a stray {{ in an unexpected place — a password, a regex — gets evaluated when you did not mean it to.

This is liberating once it clicks: you do not learn one templating system for files and a different one for conditions. It is Jinja2 everywhere, the same delimiters and the same rules. The flip side is that "everywhere" includes places you forget about, which is why a value that happens to contain template syntax can blow up a task that has nothing to do with templates — a footgun the final topic of this chapter takes apart.

Bare vs Braced Expressions

A when: takes a bare expression — when: app_enabled, no braces — because the field is already a Jinja2 expression context. A string value, by contrast, needs {{ }} to escape out of literal text and into expression mode: msg: "{{ release }} deployed". Mixing the two conventions is the first syntax confusion every newcomer hits, usually by wrapping a when: in braces and getting a warning they do not understand.

The rule is about context. Fields that Ansible already evaluates as expressions — when:, failed_when:, changed_when: — want the bare form, and adding {{ }} is redundant at best. Fields that hold ordinary strings want the braces to mark which part is an expression. When in doubt, ask whether the field is a condition or a string: conditions go bare, strings get braced.

Rendering Happens on the Control Node

The template module reads the .j2 file, renders it against the host's variables right there on your laptop or CI runner, and then copies the finished file to the managed node. The server never sees Jinja2 — only the rendered result, a plain config file with every {{ }} already resolved to text. The managed node has no templating engine and needs none; by the time the file arrives, all the logic has already run.

This is the single most important fact in the chapter, and it is invisible until topic 37. As long as your templates read variables and facts about the target host, the distinction does not bite — Ansible has those values on the control node. The moment you reach for a lookup, which reads a file or environment variable, "on the control node" stops being trivia and starts being the reason lookup('file', '/etc/hostname') returns your laptop's hostname, not the server's.