Module blockinfile Ansible : insérer un bloc multi-lignes idempotent

ansible.builtin.blockinfile insère ou met à jour un bloc multi-lignes dans un fichier existant, avec idempotence garantie via des markers automatiques. C'est le module qui comble le trou entre lineinfile: (1 ligne) et template: (fichier complet).

Cas d'usage typiques : ajouter 3-10 lignes de durcissement dans /etc/ssh/sshd_config.d/99-ansible.conf, déposer un bloc d'aliases dans /etc/profile.d/, gérer une section custom dans un fichier que vous ne contrôlez pas entièrement.

Ce que vous allez apprendre

• Le rôle des markers # BEGIN ANSIBLE MANAGED BLOCK / # END ANSIBLE MANAGED BLOCK.
• Comment personnaliser le marker pour gérer plusieurs blocs dans le même fichier.
• Quand blockinfile: est préférable à lineinfile: (multi-lignes) ou à template: (fichier non possédé).
• Le piège des commentaires de marker dans des fichiers où # n'est pas un commentaire.

Prérequis

• Connaître les modules copy: et lineinfile:, blockinfile: se positionne entre les deux.

Le mécanisme des markers

Quand vous insérez un bloc avec blockinfile:, Ansible encadre votre bloc avec deux markers :

# BEGIN ANSIBLE MANAGED BLOCK
PermitRootLogin no
PasswordAuthentication no
MaxAuthTries 3
# END ANSIBLE MANAGED BLOCK

Au prochain run, Ansible cherche les markers, remplace tout ce qui est entre les deux par le nouveau bloc, et regénère les markers. Conséquence : idempotence garantie, jamais de duplication.

Ne pas modifier les markers à la main entre deux runs, Ansible perdrait le repère et empilerait un nouveau bloc.

Exemple : durcissement sshd

- name: Durcissement sshd via blockinfile
  ansible.builtin.blockinfile:
    path: /etc/ssh/sshd_config.d/99-ansible.conf
    create: true
    mode: "0600"
    block: |
      PermitRootLogin no
      PasswordAuthentication no
      MaxAuthTries 3
      ClientAliveInterval 300
    marker: "# {mark} HARDENING ANSIBLE"
  notify: Reload sshd

create: true crée le fichier s'il n'existe pas, pratique pour les drop-in configs dans /etc/ssh/sshd_config.d/.

marker: "# {mark} HARDENING ANSIBLE" personnalise le marker. {mark} est remplacé par BEGIN ou END. Résultat dans le fichier :

# BEGIN HARDENING ANSIBLE
PermitRootLogin no
…
# END HARDENING ANSIBLE

Pourquoi customiser le marker ? Si vous gérez plusieurs blocs dans le même fichier (un pour le hardening, un pour les aliases utilisateur, un pour la perf tuning), chaque bloc doit avoir son marker unique, sinon Ansible ne sait plus lequel mettre à jour.

Insertion à un endroit précis, insertafter: / insertbefore:

Par défaut, blockinfile: ajoute à la fin du fichier (EOF). Pour insérer après une ligne précise :

- name: Ajouter un bloc apres la ligne PORT
  ansible.builtin.blockinfile:
    path: /etc/myapp/config.ini
    insertafter: '^Port='
    block: |
      LogLevel = INFO
      LogPath = /var/log/myapp/
    marker: "# {mark} LOGGING"

Si la regex ne matche pas et qu'on utilise insertafter: EOF (défaut), le bloc est ajouté en fin de fichier. Si la regex est définie et ne matche pas, le bloc est aussi ajouté en fin (comportement par défaut Ansible), pour échouer dans ce cas, ajouter une vérification préalable.

Suppression, state: absent

- name: Retirer le bloc de durcissement
  ansible.builtin.blockinfile:
    path: /etc/ssh/sshd_config.d/99-ansible.conf
    marker: "# {mark} HARDENING ANSIBLE"
    state: absent

Ansible cherche les markers BEGIN HARDENING ANSIBLE et END HARDENING ANSIBLE et supprime tout entre les deux (markers compris). Le reste du fichier est intact.

Marker dans des fichiers où # n'est pas un commentaire

Pour un fichier YAML, JSON ou XML, le marker # BEGIN… est invalide syntaxiquement.

# Pour un YAML : commentaire = "#" (OK)
marker: "# {mark} ANSIBLE"

# Pour un XML : commentaire = "<!-- ... -->"
marker: "<!-- {mark} ANSIBLE -->"

# Pour un fichier SQL :
marker: "-- {mark} ANSIBLE"

Toujours adapter le marker au format du fichier cible, sinon le fichier devient cassé.

Comparaison lineinfile vs blockinfile vs template

Deux questions suffisent à trancher, et le tableau les combine : combien de lignes faut-il poser, et qui possède le fichier. Une ligne isolée relève de lineinfile:, un fichier que votre playbook produit entièrement relève de template:, et tout ce qui se trouve entre les deux, en particulier un fichier fourni par un paquet système dans lequel vous n'écrivez qu'une section, relève de blockinfile:. La dernière ligne du tableau est la plus structurante : sur un fichier que vous ne possédez pas, réécrire l'ensemble revient à figer les valeurs par défaut de la distribution.

Les trois modules appartiennent à la collection ansible.builtin, et c'est sous cette forme pleinement qualifiée qu'il faut les écrire en production : ansible.builtin.lineinfile, ansible.builtin.blockinfile et ansible.builtin.template. Le cas d'école reste l'ajout d'une entrée dans /etc/hosts, une ligne unique dans un fichier système : ansible.builtin.lineinfile avec un regexp: qui cible la ligne, et l'exécution devient idempotente sans jamais toucher au reste du fichier.

Cas	Module recommandé	Raison
1 ligne (net.ipv4.ip_forward = 1)	lineinfile:	Le plus simple, regex pour matching
3-10 lignes liées (bloc d'options)	blockinfile:	Markers, idempotence, suppression facile
Fichier complet (nginx.conf)	template:	Interpolation Jinja2, validate, backup
Plusieurs blocs dans un fichier	blockinfile: × N	Un marker custom par bloc
Fichier qu'on ne possède pas (système)	blockinfile:	On modifie sans tout réécrire

Glissez pour voir

Pièges courants

La panne la plus fréquente de ce module est la perte d'idempotence, et elle a toujours la même racine : le module ne retrouve plus ses markers. Marker par défaut partagé par deux tâches, marker réécrit à la main, marker au mauvais format de commentaire, le symptôme varie mais la lecture est la même. Les deux dernières lignes du tableau relèvent d'une autre famille, une regex insertafter: qui ne correspond à rien et un fichier absent que create: true aurait créé.

Symptôme	Cause	Fix
2 blocs empilés à chaque run	Marker par défaut + 2 tâches dans le playbook	Marker unique par bloc (# {mark} BLOC1, # {mark} BLOC2)
Fichier YAML/JSON cassé	Marker # … injecté dans un format où # est invalide	Adapter le marker (-- {mark} pour SQL, <!-- {mark} --> pour XML)
Bloc ajouté à EOF au lieu de l'endroit voulu	insertafter: regex ne matche pas	Tester la regex avec grep -E avant
blockinfile: sur fichier inexistant échoue	create: false (défaut)	Ajouter create: true

Glissez pour voir

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• blockinfile: = idéal pour 3-10 lignes liées dans un fichier existant.
• Markers garantissent l'idempotence, ne jamais les modifier à la main.
• Marker custom (marker: "# {mark} MY_BLOCK") obligatoire si plusieurs blocs dans un fichier.
• create: true crée le fichier s'il n'existe pas, utile pour les drop-in configs.
• Adapter le format du marker au type de fichier (#, --, <!-- -->, etc.).

Mettre en pratique

Un bloc géré par blockinfile ne se juge pas au premier passage, mais au second. Ce lab vous fait déposer un fichier dans /etc/profile.d/ avec create: true, y insérer un jeu d'aliases encadré par des markers personnalisés, puis relancer le playbook. La correction compte les markers présents dans le fichier : deux blocs au lieu d'un signalent une perte d'idempotence, la panne la plus fréquente sur ce module.

Lab pratique

Module blockinfile : bloc multi-lignes idempotent

$ dsoxlab run modules-fichiers-blockinfile

Environnement : VM·Durée : ~30 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run modules-fichiers-blockinfile
dsoxlab check modules-fichiers-blockinfile

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Pour aller plus loin

• Module replace : modifier une valeur déjà présente sans encadrer quoi que ce soit de markers.
• Module systemd_service : recharger le service dont vous venez de modifier la configuration.
• Module sudoers : sur /etc/sudoers.d/, le module dédié valide avec visudo là où un bloc mal formé casse sudo.

×

📖 Voir la documentation →