Templates Jinja2 et fichiers de configuration

Un template Ansible est un fichier de configuration modèle, écrit avec le langage Jinja2, dans lequel des variables, des boucles et des conditions sont remplacées par les valeurs de chaque hôte au moment du déploiement. Le module template produit ainsi, à partir d'un seul modèle, le bon fichier pour chaque serveur. Ce chapitre présente la syntaxe Jinja2, les filtres utiles, le module template et sa validation, et dit quand préférer copy, lineinfile ou blockinfile.

Le principe

Un fichier de configuration est rarement identique d'un serveur à l'autre : le nom du site change, la liste des serveurs DNS dépend du site, une option n'est utile que sur certains hôtes. Le template garde ce qui est commun et remplace ce qui varie par des variables.

Le rendu a lieu sur le nœud de contrôle ; seul le fichier final est envoyé. Le module compare ensuite ce fichier à celui du serveur : s'ils sont identiques, rien ne change (ok) ; sinon, il remplace le fichier (changed) et notifie les handlers. L'idempotence est donc assurée par la comparaison.

La syntaxe Jinja2

Jinja2 utilise trois délimiteurs :

Le modèle roles/socle/templates/chrony.conf.j2 de Sorbier :

# {{ ansible_managed }}
{% for serveur in serveurs_ntp %}
server {{ serveur }} iburst
{% endfor %}
driftfile /var/lib/chrony/chrony.drift
makestep 1 3
rtcsync
logdir /var/log/chrony

Rendu pour srv-journaux, avec serveurs_ntp: [192.168.10.177, 192.168.10.181] :

# Ansible managed
server 192.168.10.177 iburst
server 192.168.10.181 iburst
driftfile /var/lib/chrony/chrony.drift
makestep 1 3
rtcsync
logdir /var/log/chrony

ansible_managed est une variable fournie par Ansible, qui vaut « Ansible managed » par défaut. La mettre en commentaire en tête de chaque fichier prévient celui qui ouvre le fichier sur le serveur : une modification à la main sera écrasée au prochain passage.

Les lignes {% for %} et {% endfor %} ne laissent pas de ligne vide : le module template active l'option Jinja2 trim_blocks, qui supprime le retour à la ligne qui suit une instruction. Pour supprimer aussi l'espace avant une instruction, ajoute un tiret : {%- if … %}.

Les conditions s'écrivent avec if, elif, else, endif :

{% if web_hsts | default(true) %}
    Header always set Strict-Transport-Security "max-age=31536000"
{% endif %}

Les boucles parcourent une liste ou, avec .items(), un dictionnaire. La boucle a des variables utiles : loop.index (numéro du tour, à partir de 1), loop.first, loop.last.

Les autres hôtes sont accessibles par groups et hostvars. Ce modèle de fichier /etc/hosts liste tous les serveurs Linux de l'inventaire, utile pour un serveur de la DMZ qui n'interroge pas le DNS interne :

127.0.0.1 localhost
{% for hote in groups['linux'] %}
{{ hostvars[hote]['ansible_host'] }} {{ hote }}.{{ domaine_ad }} {{ hote }}
{% endfor %}

127.0.0.1 localhost
192.168.10.180 srv-journaux.ad.sorbier.example srv-journaux
192.168.10.225 srv-web.ad.sorbier.example srv-web

Ajoute un serveur au groupe linux de l'inventaire, relance : il apparaît dans le fichier, sans toucher au modèle.

Les filtres utiles

Un filtre transforme une valeur ; il s'écrit après un |, et les filtres s'enchaînent de gauche à droite. Ils servent dans les templates comme dans les playbooks. Les résultats ci-dessous ont été obtenus avec les variables de Sorbier (domaine_ad: ad.sorbier.example, serveurs_dns: [192.168.10.177, 192.168.10.181]).

Les filtres viennent de Jinja2 (default, upper, join, length…), d'ansible-core (bool, regex_replace, to_nice_yaml, password_hash…) et des collections (community.general.unicode_normalize, par exemple). ansible-doc -t filter -l les liste.

Le module template

    - name: Configurer chrony sur les contrôleurs de domaine
      ansible.builtin.template:
        src: chrony.conf.j2
        dest: /etc/chrony/chrony.conf
        owner: root
        group: root
        mode: "0644"
        backup: true
      notify: Redémarrer chrony

validate est la meilleure protection contre une configuration cassée. Le fichier généré est d'abord écrit dans un fichier temporaire, la commande le vérifie, et il n'est installé que si elle réussit. Le socle de Sorbier durcit SSH ainsi :

    - name: Durcir le serveur SSH
      ansible.builtin.template:
        src: sshd-sorbier.conf.j2
        dest: /etc/ssh/sshd_config.d/10-sorbier.conf
        owner: root
        group: root
        mode: "0644"
        validate: /usr/sbin/sshd -t -f %s
      notify: Recharger SSH

avec le modèle sshd-sorbier.conf.j2 :

# {{ ansible_managed }}
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
MaxAuthTries 3
LoginGraceTime 30
AllowGroups sudo {{ socle_groupe_ansible | default('ansible') }}

Une faute de frappe dans une directive fait échouer sshd -t : la tâche échoue, l'ancien fichier reste en place, SSH n'est pas rechargé, et tu ne te retrouves pas enfermé dehors. Debian 13 lit les fichiers de /etc/ssh/sshd_config.d/ grâce à la ligne Include du fichier principal : déposer un fichier à part évite de réécrire sshd_config en entier.

Les commandes de validation courantes :

Exemple complet : l'hôte virtuel Apache

Le rôle web de Sorbier génère l'hôte virtuel du site de suivi à partir de templates/site.conf.j2 :

# {{ ansible_managed }}
<VirtualHost *:80>
    ServerName {{ web_nom_site }}
    Redirect permanent / https://{{ web_nom_site }}/
</VirtualHost>

<VirtualHost *:443>
    ServerName {{ web_nom_site }}
    ServerAdmin {{ web_admin_mail }}
    DocumentRoot {{ web_racine }}

    SSLEngine on
    SSLCertificateFile {{ web_certificat }}
    SSLCertificateKeyFile {{ web_cle_privee }}
    Header always set Strict-Transport-Security "max-age=31536000"

    ErrorLog ${APACHE_LOG_DIR}/{{ web_nom_site }}-error.log
    CustomLog ${APACHE_LOG_DIR}/{{ web_nom_site }}-access.log combined
</VirtualHost>

${APACHE_LOG_DIR} n'est pas une variable Jinja2 (pas d'accolades doubles) : elle reste telle quelle dans le fichier, et c'est Apache qui la remplace. Le même modèle sert pour un deuxième site : il suffit d'un autre hôte, avec d'autres valeurs de web_nom_site et web_racine dans ses host_vars.

template, copy, lineinfile ou blockinfile ?

La règle : si Ansible est le seul à écrire le fichier, prends template, c'est le plus lisible et le plus sûr. lineinfile multiplié par dix sur le même fichier devient vite impossible à suivre : c'est le signe qu'il faut passer à un template ou à un fichier à part dans un dossier .d/.

Exercices

# {{ ansible_managed }}
search {{ domaine_ad }}
{% for serveur in serveurs_dns %}
nameserver {{ serveur }}
{% endfor %}

# Ansible managed
search ad.sorbier.example
nameserver 192.168.10.177
nameserver 192.168.10.181

    - name: Déclarer les serveurs DNS de l'annuaire
      ansible.builtin.template:
        src: resolv.conf.j2
        dest: /etc/resolv.conf
        owner: root
        group: root
        mode: "0644"

{% for site in sites %}
# Site {{ loop.index }} : {{ site.nom | upper }}
Listen {{ site.port }}
{% endfor %}
{% if journal_detaille %}
LogLevel debug
{% else %}
LogLevel warn
{% endif %}

# Site 1 : SUIVI
Listen 443
# Site 2 : INTRANET
Listen 8443
LogLevel warn

{{ (prenom[0] ~ nom) | community.general.unicode_normalize(form='NFD') | regex_replace('[^A-Za-z0-9]', '') | lower }}