Jinja2 syntaxe de base : interpolation, boucles, conditions, whitespace

Jinja2 est le moteur de templating utilisé par Ansible pour générer des fichiers de configuration dynamiques. Au-delà de la simple interpolation {{ var }} que vous avez vue partout, Jinja2 supporte des boucles ({% for %}), des conditions ({% if %}), des commentaires ({# #}), et un contrôle fin du whitespace ({%- ... -%}). Cette page synthétise la syntaxe que vous taperez dans tout fichier .j2 ou dans une string Ansible avec interpolation Jinja.

L'enjeu : générer un fichier de config (motd, nginx.conf, sshd_config) à partir d'un template + variables, sans avoir à scripter ligne par ligne avec lineinfile:.

{# Commentaire (n'apparaît PAS dans la sortie) #}

{# Interpolation de variable #}
Bienvenue sur {{ ansible_hostname }} ({{ ansible_distribution }})

{# Condition #}
{% if ansible_memtotal_mb > 4096 %}
Mode haute mémoire activé
{% else %}
Mode mémoire standard
{% endif %}

{# Boucle #}
{% for user in admin_users %}
{{ user.name }} ALL=(ALL) {{ 'NOPASSWD:' if user.nopasswd else '' }} ALL
{% endfor %}

{# Contrôle whitespace : - en début/fin pour supprimer espaces et nouvelles lignes #}
{%- for service in services -%}
{{ service.name }}:{{ service.port }}
{%- endfor %}

{# Filtre + default #}
Port: {{ http_port | default(80) }}

Sécurité non négociable :

trim_blocks: true + lstrip_blocks: true sur le module template:, c'est l'usage standard 2026, sinon vous obtenez des lignes vides parasites partout dans votre fichier généré.
Toujours validate: sur le template: qui génère une conf critique (sshd, nginx, sudoers, named), un Jinja qui produit une syntaxe invalide casse le service au prochain reload.
| default(<valeur>) sur toute variable optionnelle, sinon une variable undefined plante le template avec un message obscur.
Pas de logique métier complexe dans un template Jinja, si vous avez besoin de plus de 2-3 conditions imbriquées, calculer dans le playbook avec set_fact: puis injecter le résultat dans le template.
Échapper les variables utilisateur avec | quote quand le template génère du shell, sinon une apostrophe dans la valeur casse la commande générée.

Ce que vous allez apprendre

{{ var }} pour interpoler une variable ou une expression
{% for %} + {% if %} pour la logique
{# commentaire #} pour commenter (ne sera pas dans la sortie)
Le whitespace control : {%- ... -%} et l'option trim_blocks: true
Différence entre un fichier .j2 (template) et une string Ansible avec Jinja inline

Prérequis

Avoir lu Filtres Jinja2 essentiels ;
Connaître les variables Ansible (cf. Variables, déclaration).

Les 3 marqueurs Jinja2

{# Ceci est un commentaire (n'apparaît PAS dans la sortie générée) #}

Hello {{ name | upper }}             ← interpolation : remplace par la valeur

{% if user_count > 0 %}              ← logique : pas affiché tel quel
Vous avez {{ user_count }} utilisateurs.
{% endif %}

{% for u in users %}                 ← boucle
- {{ u.name }} ({{ u.email }})
{% endfor %}

Marqueur	Rôle	Apparaît dans la sortie ?
`{{ ... }}`	Interpolation d'une variable / expression	Oui (la valeur)
`{% ... %}`	Logique (if, for, set, include)	Non (mais le résultat est dans la sortie)
`{# ... #}`	Commentaire	Non

Interpolation `{{ var }}`

{{ ansible_distribution }} {{ ansible_distribution_version }}
{{ user.name | default('inconnu') }}
{{ ports | join(', ') }}
{{ 2 + 3 }}                           ← expression Python (5)

L'interpolation accepte toute expression Python valide (limitée par sandbox) + les filtres Jinja (| upper, | default, | join).

Conditions `{% if %}`

{% if env == 'prod' %}
debug = false
{% elif env == 'staging' %}
debug = true
log_level = info
{% else %}
debug = true
log_level = debug
{% endif %}

Les opérateurs disponibles : ==, !=, >, <, >=, <=, and, or, not, in. Les tests (vu page suivante) : is defined, is none, is mapping.

Boucles `{% for %}`

{% for user in users %}
- {{ user.name }} ({{ user.email }})
{% endfor %}

Variables magiques loop.* disponibles dans la boucle :

Variable	Valeur
`loop.index`	Index 1-based (1, 2, 3...)
`loop.index0`	Index 0-based (0, 1, 2...)
`loop.first`	`true` si première itération
`loop.last`	`true` si dernière itération
`loop.length`	Nombre total d'éléments

{% for u in users -%}
{{ loop.index }}. {{ u.name }}{% if not loop.last %},{% endif %}
{% endfor %}

Boucle imbriquée :

{% for env, hosts in environments.items() %}
[{{ env }}]
{% for h in hosts %}
{{ h }}
{% endfor %}
{% endfor %}

Commentaires `{# #}`

{# Cette ligne est invisible dans le fichier généré #}
{# Utile pour expliquer la logique du template aux mainteneurs #}
{# Ne pas confondre avec les commentaires shell # qui SONT dans la sortie #}

Les {# #} ne sont jamais dans la sortie, différents des # bash comments qui apparaissent dans le fichier généré (parce qu'ils sont du texte normal pour Jinja).

Whitespace control, le piège n°1

Sans contrôle, ce template :

Services :
{% for s in services %}
  - {{ s }}
{% endfor %}

Produit (avec des lignes vides indésirables) :

Services :

  - sshd

  - chronyd

  - firewalld

Le \n après chaque {% ... %} est conservé. Solution : {%- ... -%} strip le whitespace avant/après le tag :

Services :
{% for s in services -%}
  - {{ s }}
{% endfor %}

Sortie propre :

Services :
  - sshd
  - chronyd
  - firewalld

Convention :

{%- : strip whitespace avant le tag
-%} : strip whitespace après le tag
{{- ... -}} : idem pour les expressions

Options globales : `trim_blocks` + `lstrip_blocks`

Plutôt que poser {%- / -%} partout, vous pouvez activer ces deux options au niveau du module template :

- name: Template avec whitespace control automatique
  ansible.builtin.template:
    src: motd.j2
    dest: /etc/motd
    trim_blocks: true        # supprime le \n après chaque {% %}
    lstrip_blocks: true      # supprime les espaces de début de ligne devant {% %}

Avec trim_blocks: true + lstrip_blocks: true, le template précédent sans {%- produit le bon résultat. C'est la combinaison recommandée, vous l'activez par défaut.

Cas pratique, MOTD avec if + for (lab `ecrire-code/jinja2-base`)

Voici le template validé sur le lab 26-ecrire-code-jinja2-base :

==========================================
  Bienvenue sur {{ inventory_hostname }}
==========================================
{% if host_role == "DB" %}
Profil : DB
{% endif %}
Services :
{% for s in services -%}
  - {{ s }}
{% endfor %}

Le playbook qui consomme ce template :

- name: Challenge jinja2 base
  hosts: db1.lab
  become: true
  vars:
    host_role: DB
    services:
      - postgresql
      - chronyd
      - firewalld
  tasks:
    - name: Poser /etc/motd-challenge via template
      ansible.builtin.template:
        src: templates/motd.j2
        dest: /etc/motd-challenge
        mode: "0644"

Contenu posé sur db1.lab :

==========================================
  Bienvenue sur db1.lab
==========================================

Profil : DB

Services :
  - postgresql
  - chronyd
  - firewalld

Les if et for sont rendus, le whitespace control sur le for évite les lignes vides entre services.

Différence : fichier `.j2` vs Jinja inline

Il y a deux contextes où vous écrivez du Jinja en Ansible :

1. Fichier `.j2` consommé par `template:`

- ansible.builtin.template:
    src: templates/nginx.conf.j2
    dest: /etc/nginx/nginx.conf

Le fichier complet est traité comme template Jinja2. Tous les marqueurs {{ }}, {% %}, {# #} sont actifs.

2. Jinja inline dans une string Ansible

- ansible.builtin.copy:
    dest: /tmp/foo
    content: "Bienvenue sur {{ inventory_hostname }}\n"

Seules les expressions {{ }} sont évaluées. Pas de boucles ou conditions inline.

Pour les logiques complexes, basculez sur un vrai fichier .j2 + le module template:.

Pièges fréquents

Symptôme	Cause	Fix
Lignes vides indésirables après `{% for %}`	Whitespace par défaut conservé	`{%- ... -%}` ou `trim_blocks: true` + `lstrip_blocks: true`
`{# commentaire #}` apparaît dans la sortie	Mauvais marqueur (probablement `{ # ... # }` avec espaces)	Pas d'espaces : `{# comment #}`
Boucle qui plante avec `'NoneType' has no attribute`	Variable absente dans certains items	Préfixer par `is defined` ou `default()`
Variables Ansible non interpolées dans `.j2`	Variables non passées au play	Vérifier `vars:` du play ou `host_vars/`
`{{ var }}` non interpolé dans un YAML inline	Manque les quotes	Toujours quoter : `content: "{{ var }}\n"`

À retenir

3 marqueurs Jinja2 : {{ }} interpolation, {% %} logique, {# #} commentaire.
Whitespace control essentiel : {%- ... -%} ou trim_blocks: true + lstrip_blocks: true (recommandé).
loop.* expose index, first, last, length dans une boucle for.
Différence fichier .j2 (Jinja complet) vs Jinja inline (interpolation seule).
Le module template: transforme le .j2 côté control node, copie le résultat vers le managed node.

Pratiquer dans le lab

Cette page a un lab d'accompagnement : labs/ecrire-code/jinja2-base/ dans stephrobert/ansible-training. Il contient un README.md guidé, un Makefile (make verify lance les tests), et un challenge final auto-évalué : générer un /etc/motd-challenge qui combine {% if %} (profil DB) et {% for %} (liste de services) avec whitespace control propre.

Une fois le lab provisionné :

cd ~/Projets/ansible-training/labs/ecrire-code/jinja2-base/

cat README.md           # tuto pas à pas
cat challenge/README.md # consigne du challenge
pytest -v challenge/tests/   # 6 tests testinfra

Prochaines étapes

Filtres Jinja2 avancés regex_search, regex_findall, groupby, flatten, from_yaml, password_hash, b64encode

Tests Jinja2 is defined, is none, is mapping, is sequence, is regex

Module template ansible.builtin.template, validate:, backup:, lstrip_blocks:, trim_blocks: