Troubleshooting Ansible : verbosité, débogueur, idempotence et performance

80 % des problèmes Ansible se diagnostiquent avec 4 outils : -vvv pour SSH, debugger: on_failed pour les variables au runtime, profile_tasks pour les performances, et le test d’idempotence (run 2× et vérifier changed=0). Cette section approfondit le niveau intermédiaire/avancé : verbosité progressive pour identifier où ça plante, débogueur interactif pour fix au runtime sans relancer, idempotence + tuning pour des playbooks fiables et rapides en production. Incontournable pour un candidat RHCE EX294 et un opérateur AAP en environnement multi-host.

Aller droit au but

🚀 Verbosité (-v à -vvvv) Choisir le bon niveau, activer profile_tasks, no_log obligatoire sur secrets

📚 Débogueur interactif debugger: on_failed, REPL p task_vars, redo après modification

🎯 Idempotence cassée creates: / regexp: / changed_when: — fix les changed=N au second run

🔥 Tuning performances pipelining + forks + ControlPersist — gain typique -50 % à -60 %

Ce que vous allez apprendre

Choisir le bon niveau -v selon le symptôme (Jinja2, SSH, internals).
Activer le débogueur Ansible interactif et fixer une variable au runtime.
Mesurer les performances avec ansible.posix.profile_tasks callback.
Diagnostiquer une idempotence cassée et la fixer avec creates: / changed_when:.
Tuner SSH avec pipelining + forks + ControlPersist (-50 % de temps typique).

Prérequis

Avoir validé Debug premières erreurs.
Avoir écrit plusieurs playbooks (sections Premiers pas et Écrire du code).
Un lab homelab avec plusieurs hosts (idéalement 3+) pour mesurer parallélisme et performances.

Mon retour d’expérience — pour ceux qui veulent comprendre

Si l’une des cartes en haut de page vous a déjà orienté, vous êtes parti sur le bon pied. La suite de cette page s’adresse à ceux qui veulent comprendre la philosophie de cette section : pourquoi le débogueur interactif Ansible est un trésor sous-utilisé, pourquoi no_log est non négociable, et pourquoi le tuning performances vient APRÈS l’idempotence — jamais avant.

J’ai passé des nuits à débugger des playbooks Ansible qui plantent en prod sur 1 host sur 50, et qui marchent en pré-prod. Ce sont les heures qui forment le troubleshooter, pas les tutoriels. Cette section condense les réflexes que j’aurais aimé avoir 5 ans plus tôt — verbosité ciblée au lieu de -vvvv aveugle, débogueur interactif au lieu de relancer 30 fois, mesure avant tuning. Sans ces réflexes, on perd 80 % de son temps à chercher au mauvais endroit.

La boîte à outils du troubleshooter

Outil	Quand l’utiliser	Page dédiée
`-vvv`	Bug SSH, connexion, interpréteur Python	Verbosité
`debugger: on_failed`	Variable undefined, échec à fix au runtime	Débogueur
`profile_tasks` callback	Identifier les tâches lentes	Verbosité
Test idempotence (run 2x)	Vérifier qu’un playbook ne refait rien	Idempotence
`ANSIBLE_KEEP_REMOTE_FILES=1`	Inspecter les modules transférés sur cible	Verbosité
`ansible-navigator replay`	Rejouer un échec sans relancer	Modes interactifs

Quand utiliser quoi — arbre de décision rapide

Erreur SSH / Connection refused / Permission denied → ansible all -m ping -vvv, puis ssh -vvv user@host pour bypass Ansible.
Variable undefined / template Jinja2 → -vv (montre les args templatés). Si récurrent → debugger: on_failed.
MODULE FAILURE → -vvv + ANSIBLE_KEEP_REMOTE_FILES=1, exécuter le module Python à la main sur la cible.
Lent (>30s par run) → callback profile_tasks, identifier les tâches > 5s, optimiser ou paralléliser.
changed=N à chaque run → audit des modules command/shell/lineinfile, ajouter creates: / regexp: / changed_when:.
Erreur AAP / EE → ansible-navigator replay <artifact.json> (voir EE).

Le parcours en 3 phases

Phase 1 — Voir ce qui se passe

Verbosité progressive (-v à -vvvv) Choisir le bon niveau, activer profile_tasks, no_log obligatoire sur secrets.

Phase 2 — Fix au runtime

Débogueur Ansible interactif debugger: on_failed, REPL p task_vars, redo après modification d'args.

Phase 3 — Fiabiliser et accélérer

Idempotence cassée et tuning performances creates: / regexp: / changed_when:, pipelining, forks, ControlPersist.

Ce que je défends pour le troubleshooting Ansible

Cinq positions tranchées que cette section assume :

Verbosité ciblée, pas aveugle. -v pour les args, -vv pour les vars templatés, -vvv pour SSH, -vvvv pour les internals plugin. Empiler les v sans réflexion produit 50 000 lignes de log inutile et noie le vrai message.
Débogueur interactif au moindre échec récurrent. debugger: on_failed ouvre un REPL avec les variables à l’instant T. Vous fixez en 30 secondes au lieu de relancer 10 fois en modifiant des debug:. C’est l’outil le plus sous-utilisé d’Ansible.
Idempotence d’abord, performance ensuite. Tuner un playbook qui n’est pas idempotent, c’est tuner une mauvaise solution. Vérifier changed=0 au second run avant de toucher forks ou pipelining. Sinon vous accélérez du faux travail.
Mesure systématique avec profile_tasks avant tout tuning. Pas de tuning à l’instinct. Si une tâche prend 80 % du temps, c’est elle qu’on optimise — pas les 5 autres qui sont rapides.
no_log: true sur toute tâche manipulant un secret. Sans ça, -v leak la valeur claire dans la sortie. Indexable par défaut par les agents CI ou les stacks ELK. Non négociable.

Ce que je vous interdis

Cinq erreurs typiques de troubleshooting — chacune source de bugs additionnels :

-vvvv par défaut sur tout playbook qui plante. Le vrai message se noie dans 50 000 lignes. Commencer par -v et monter selon le symptôme.
debugger: always sur un play long. Le REPL s’ouvre après chaque tâche, paralyse l’exécution. Usage TDD ou debug ciblé, jamais en production ou play long.
changed_when: false posé par paresse pour faire taire changed=N. Masque les vraies modifications, casse l’audit, rend l’idempotence non vérifiable. Toujours diagnostiquer la vraie cause, pas masquer.
forks=200 sur un poste dev. Sature le file descriptor limit, plante la RAM. Les forks doivent matcher la capacité du control node ET la tolérance des managed nodes (load avg, IOPS).
pipelining=True sans vérifier requiretty dans /etc/sudoers. Pipelining incompatible avec requiretty. Sur RHEL par défaut, ça plante. Désactiver requiretty dans /etc/sudoers.d/ ou laisser pipelining off.

À retenir

-vvv = niveau de référence pour tout bug SSH ou MODULE FAILURE.
debugger: on_failed = inspection + fix au runtime, jamais en production.
profile_tasks = mesure systématique avant tout tuning.
Test idempotence = run 2× et vérifier changed=0 au 2e — à automatiser en CI.
Pipelining + forks + ControlPersist = 3 leviers cumulés, gain typique -50 % à -60 %.
no_log: true systématique sur toute tâche manipulant un secret.

Prochaines étapes

Commencer : verbosité progressive Niveaux -v à -vvvv, callbacks profile_tasks, no_log secrets.

Débogueur interactif REPL Ansible, fix variable au runtime, redo + continue.

Idempotence et tuning creates: / regexp: / changed_when:, pipelining, forks, ControlPersist.

Préparer la RHCE EX294 Mock 4h chrono avec les 12 catégories de l'examen.