Check mode et diff Ansible : dry-run et visualisation des changements

Le check mode Ansible (--check) exécute un playbook en dry-run : il calcule ce qui changerait sans rien modifier. Couplé au mode --diff, vous voyez exactement les diffs des fichiers qui seraient écrits, les paquets qui seraient installés, les services qui seraient démarrés. C'est l'outil de pré-validation indispensable avant toute modification en production, et c'est aussi l'audit de conformité d'une fleet : --check retourne un PLAY RECAP avec changed=N qui chiffre la dérive.

Cette page couvre les deux flags (--check, --diff), leur combinaison, le contrôle au niveau task (check_mode: true|false), et les modules qui ne supportent pas check_mode (command, shell, certains modules custom).

Ce que vous allez apprendre

• --check : exécuter un playbook en dry-run sans rien modifier ;
• --diff : afficher les diffs des fichiers, configurations, états ;
• La combinaison --check --diff pour audit complet ;
• check_mode: true|false au niveau task pour des cas particuliers ;
• Les modules qui ne supportent pas --check (et comment les gérer).

Le mode --check en pratique

Lancez un playbook en dry-run :

ansible-playbook site.yml --check

Ansible exécute chaque tâche en mode simulation : aucun fichier n'est écrit, aucun paquet installé, aucun service démarré. Le PLAY RECAP affiche les changed=N comme si vous aviez vraiment exécuté.

Sortie typique :

TASK [Installer nginx] ***********************************************
changed: [web1.lab]
changed: [web2.lab]

PLAY RECAP ***********************************************************
web1.lab    : ok=5  changed=3  unreachable=0  failed=0
web2.lab    : ok=5  changed=3  unreachable=0  failed=0

changed=3 veut dire : 3 tâches modifieraient l'état réel si le playbook tournait pour de vrai. C'est l'indicateur de dérive : sur une fleet conforme, vous attendez changed=0 partout.

Le mode --diff

--diff affiche le détail des modifications, particulièrement utile pour les modules qui touchent des fichiers (copy, template, lineinfile) :

ansible-playbook site.yml --diff

Sortie typique :

TASK [Mettre à jour nginx.conf] ***************************************
--- before: /etc/nginx/nginx.conf
+++ after: /tmp/.ansible/tmp/<sha>/source
@@ -3,7 +3,7 @@
 worker_processes auto;
 events {
-    worker_connections 768;
+    worker_connections 1024;
 }
changed: [web1.lab]

Vous voyez exactement ce qui va changer dans le fichier. Indispensable pour valider un changement de config avant de l'appliquer.

La combinaison --check --diff

C'est la commande d'audit qu'on lance avant tout déploiement risqué :

ansible-playbook site.yml --check --diff

Effets combinés :

• Aucun changement réel sur les managed nodes (--check) ;
• Affichage complet des diffs (--diff) ;
• PLAY RECAP avec les changed=N qui montrent ce qui aurait été modifié.

Workflow typique :

# 1. Audit dry-run
ansible-playbook site.yml --check --diff > audit.log

# 2. Lecture de l'audit, validation
less audit.log

# 3. Si OK, exécution réelle
ansible-playbook site.yml --diff

Contrôle au niveau task : check_mode:

Vous pouvez forcer un comportement spécifique sur une tâche, indépendamment du flag CLI :

check_mode: false, toujours exécuter

Une tâche qui doit toujours s'exécuter, même en --check :

- name: Vérifier la version installée
  ansible.builtin.command: nginx -v
  register: nginx_version
  check_mode: false           # exécute même en --check
  changed_when: false         # ne marque pas comme changed

Cas typique : une vérification non-destructive qui doit donner la valeur réelle pour conditionner les tâches suivantes (when: nginx_version.stdout is defined).

check_mode: true, toujours simuler

Une tâche qui ne doit jamais modifier, même en exécution réelle :

- name: Tester ce que ferait dnf upgrade (toujours simulé)
  ansible.builtin.dnf:
    name: "*"
    state: latest
  check_mode: true            # toujours en mode simulation
  register: upgrade_simulation

Cas typique : afficher la liste des paquets qui seraient mis à jour, sans jamais les mettre à jour.

Les modules qui ne supportent pas --check

Tous les modules ne savent pas tourner en check mode. Les principaux non supportés :

Module	Pourquoi
command, shell, raw, script	Exécutent une commande arbitraire, Ansible ne peut pas savoir si elle modifie l'état
meta	Méta-actions (flush_handlers, clear_facts)
Certains modules custom	Si le développeur n'a pas implémenté supports_check_mode = True

Glissez pour voir

Pour les modules command/shell, en mode --check ils sont skippés par défaut. Si vous voulez quand même les exécuter (cas d'une vérification non destructive), forcez avec check_mode: false :

- name: Vérifier la version (exécuté même en --check)
  ansible.builtin.command: nginx -v
  register: result
  check_mode: false
  changed_when: false

Pour vérifier si un module supporte le check mode :

ansible-doc ansible.builtin.dnf | grep -A1 "support_check_mode"

Cas d'usage : audit de conformité

Sur une fleet existante, vous voulez savoir quels hôtes dévient de l'état désiré. Lancez votre playbook de baseline en --check :

ansible-playbook baseline.yml --check

Le PLAY RECAP montre les hôtes en dérive :

web1.lab    : ok=12  changed=0  unreachable=0  failed=0    ← OK
web2.lab    : ok=9   changed=3  unreachable=0  failed=0    ← 3 tâches en dérive
db1.lab     : ok=10  changed=2  unreachable=0  failed=0    ← 2 tâches en dérive

Couplé à un script qui parse la sortie et alerte un système de ticketing, c'est un audit de conformité automatisé, pattern fréquent en production grande échelle.

Pièges fréquents

Symptôme	Cause	Fix
--check affiche changed mais une exécution réelle ne change rien	Module qui ne supporte pas check correctement (faux positif)	Vérifier le module ; tester avec ansible-doc <module>
--check --diff ne montre pas le diff	Le module ne capture pas avant/après	Module limité ; vérifier en réel avec --diff seul
Une tâche command skippée bloque la suite	Mode --check skip command ; les tâches qui dépendent d'un register: plantent	Forcer check_mode: false sur la tâche command
Diff énorme et illisible	Le module copie un binaire ou un fichier très volumineux	no_log: true pour masquer, ou désactiver --diff ponctuellement
--check modifie quand même quelque chose	Bug dans un module custom	Reporter le bug ; entretemps check_mode: false à éviter

Glissez pour voir

À retenir

• --check lance le playbook en dry-run : aucun changement réel.
• --diff affiche les diffs des fichiers modifiés (avant/après).
• --check --diff est la commande d'audit : zéro changement, diff complet.
• check_mode: false force une tâche à s'exécuter même en --check (vérifications non-destructives).
• check_mode: true force une tâche à toujours simuler (jamais exécuter).
• Les modules command et shell sont skippés en --check par défaut, ajouter check_mode: false si lecture sans effet de bord.

Mettre en pratique

Un dry-run n'a de valeur que si vous savez ce qu'il ne couvre pas. Le lab vous fait lancer un playbook en --check --diff, repérer les modules qui ne savent pas simuler, forcer check_mode: false sur une lecture sans effet de bord, et diagnostiquer un faux positif changed. La vérification compare l'état des fichiers avant et après, ce qui prouve qu'aucune écriture n'a eu lieu pendant la simulation.

Lab pratique

Check mode et diff : dry-run et visualisation

$ dsoxlab run ecrire-code-checkmode-diff

Environnement : VM·Durée : ~45 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 dsoxlab, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
git clone https://github.com/stephrobert/ansible-training.git
cd ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run ecrire-code-checkmode-diff
dsoxlab check ecrire-code-checkmode-diff

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress.

Pour aller plus loin

• register et set_fact : capturer le résultat d'une vérification pour en faire une décision, pas une ligne de log.
• Contrôle de flux et gestion d'erreurs : failed_when: et assert transforment un audit en contrôle qui échoue quand il le doit.
• Facts et magic vars : la matière première d'un audit de conformité : ce que la machine déclare d'elle-même.

×

📖 Voir la documentation →