Contactez-nous

Utiliser le mode verbeux (`-v`, `-vv`, `-vvv`) pour le diagnostic

Maîtrisez les options de verbosité d'Ansible (`-v`, `-vv`, `-vvv`, `-vvvv`) pour obtenir des informations de diagnostic détaillées lors de l'exécution de playbooks et commandes ad-hoc. Facilitez le débogage.

Lever le voile sur l'exécution Ansible : le pouvoir de la verbosité

Lorsque vous exécutez des commandes ad-hoc ou des playbooks Ansible, la sortie par défaut est conçue pour être concise, ne montrant que le résultat global de chaque tâche (ok, changed, failed, etc.). Cependant, lors du développement, du dépannage ou simplement pour mieux comprendre ce qu'Ansible fait en coulisses, cette concision peut s'avérer insuffisante. C'est là qu interviennent les options de verbosité, qui permettent d'augmenter la quantité d'informations affichées par Ansible.

Ansible propose plusieurs niveaux de verbosité, activables via l'option -v (ou --verbose) sur les commandes ansible et ansible-playbook. Chaque ajout de v augmente le niveau de détail, vous fournissant des informations précieuses pour le diagnostic des erreurs ou la compréhension du flux d'exécution.

Cette section détaille ce que chaque niveau de verbosité apporte et comment utiliser ces informations pour identifier et résoudre plus efficacement les problèmes dans vos automatisations Ansible.

Les différents niveaux de verbosité et leurs apports

Ansible supporte jusqu'à quatre niveaux de verbosité principaux, chacun ajoutant plus de détails à la sortie. Il existe même un niveau -vvvvv pour un débogage de connexion encore plus fin, mais les quatre premiers sont les plus couramment utilisés.

Niveau 0 (par défaut, pas de -v) :
C'est le mode de fonctionnement standard. Pour les playbooks, vous voyez le nom du jeu, le nom de la tâche, et le statut résumé pour chaque hôte (ok, changed, failed, skipped, unreachable). Pour les commandes ad-hoc, la sortie du module est généralement affichée directement.
# Exemple de sortie par défaut
PLAY [Configurer les serveurs web] ***

TASK [Installer nginx] ***
changed: [serveur1.example.com]

TASK [S'assurer que nginx est démarré] ***
ok: [serveur1.example.com]
Niveau 1 (-v) :
Ce premier niveau de verbosité ajoute les résultats des modules sous forme de structure JSON. Cela vous permet de voir les valeurs exactes retournées par chaque module, ce qui peut être utile si une tâche est ok mais que vous suspectez qu'elle n'a pas fait ce que vous attendiez, ou pour voir les détails d'un changement.
# Exemple avec -v
TASK [Installer nginx] ***
changed: [serveur1.example.com] => {"changed": true, "msg": "", "rc": 0, "stderr": "", "stderr_lines": [], "stdout": "...", "stdout_lines": [...]}
Vous voyez ici le `rc` (return code), `stdout`, `stderr`, etc., du module exécuté.Niveau 2 (-vv) :
Ce niveau ajoute des informations de débogage supplémentaires, notamment des détails sur les variables d'environnement et certains paramètres de configuration utilisés pour la tâche. Il peut être utile pour comprendre pourquoi certaines variables ne sont pas interprétées comme prévu. Les messages d'erreur des modules peuvent aussi être plus détaillés.Niveau 3 (-vvv) :
A ce niveau, Ansible devient beaucoup plus bavard concernant sa connexion aux hôtes distants. Pour les connexions SSH, il affiche des informations détaillées sur l'établissement de la connexion, l'authentification, et les commandes SSH exactes qu'il exécute. C'est extrêmement utile pour déboguer les problèmes de connectivité SSH, les erreurs d'authentification, ou les soucis avec become (sudo). Vous verrez des lignes comme :
 SSH: EXEC ssh -C -o ControlMaster=auto -o ControlPersist=60s -o StrictHostKeyChecking=no -o KbdInteractiveAuthentication=no ... '/bin/sh -c '"'"'echo ~utilisateur_ansible && sleep 0'"'"''
Cela montre la commande SSH brute envoyée par Ansible.Niveau 4 (-vvvv ou plus) :
Ce niveau ajoute encore plus de détails de bas niveau, principalement pour le débogage des plugins de connexion (comme SSH, winrm, etc.). Vous verrez des informations très granulaires sur chaque étape de la communication. Il est rarement nécessaire pour le dépannage quotidien de playbooks mais peut être indispensable pour diagnostiquer des problèmes complexes de connexion ou pour les développeurs de plugins Ansible.

Quand et comment utiliser les modes verbeux ?

L'utilisation des modes verbeux est une pratique courante lors du développement et du débogage de playbooks ou de commandes ad-hoc. Voici quelques scénarios typiques :

  • Une tâche échoue sans message clair : Commencez par -v. Si une tâche retourne FAILED, la sortie JSON fournie par -v contient souvent un champ "msg": "message d'erreur détaillé" qui explique la cause.
  • Une tâche est ok mais ne semble pas avoir eu l'effet escompté : Utilisez -v pour inspecter les valeurs de retour du module. Peut-être que la condition pour un changement n'a pas été remplie, ou que les paramètres n'ont pas été interprétés comme vous le pensiez.
  • Problèmes de connexion ou d'authentification SSH : Passez directement à -vvv. Les logs de connexion SSH détaillés vous aideront à voir si Ansible utilise la bonne clé, le bon utilisateur, ou s'il y a un problème au niveau du serveur SSH distant.
  • Problèmes avec become (sudo) : -vvv montrera comment Ansible tente d'exécuter les commandes avec élévation de privilèges et si des erreurs spécifiques à sudo se produisent.
  • Comprendre le comportement d'un nouveau module : Utiliser -v peut vous aider à voir quelles informations un module retourne, ce qui est utile pour utiliser la directive register et exploiter ces résultats plus tard.

Pour utiliser un mode verbeux, ajoutez simplement l'option correspondante à votre commande :

ansible-playbook mon_playbook.yml -v
ansible-playbook mon_playbook.yml -vvv
ansible mon_groupe -m ping -vvv

Bien que la sortie puisse devenir très volumineuse, surtout avec -vvv et sur de nombreux hôtes, ces informations sont souvent la clé pour débloquer une situation problématique. N'hésitez pas à rediriger la sortie vers un fichier (ansible-playbook ... -vvv > output.log) pour une analyse plus aisée si le volume d'informations est trop important pour être lu directement dans le terminal.

Interpréter la sortie verbeuse : ce qu'il faut chercher

Lorsque vous analysez une sortie verbeuse, voici quelques éléments clés à rechercher :

  • Avec -v : Cherchez le bloc JSON retourné par le module pour l'hôte qui pose problème. Les champs "msg", "stdout", "stderr", et "rc" (return code) sont particulièrement informatifs. Une valeur "changed": true indique qu'une modification a été apportée.
  • Avec -vvv (pour les problèmes SSH) :
    • Regardez les lignes commençant par SSH: EXEC ... pour voir la commande SSH exacte. Vérifiez l'utilisateur (-o User=...), le port (-o Port=...), et le chemin vers la clé privée (-o IdentityFile=...).
    • Cherchez les messages d'erreur SSH comme "Permission denied", "Connection refused", "Host key verification failed", etc.
    • Pour les problèmes de sudo, cherchez les tentatives d'exécution avec sudo et les messages d'erreur associés.
  • Avec -vvv (pour les problèmes de variables) : Ansible peut afficher les valeurs des variables qu'il utilise pour une tâche. Vérifiez si elles correspondent à ce que vous attendez.

En maîtrisant l'utilisation des options de verbosité, vous transformez Ansible d'une "boîte noire" en un outil plus transparent, ce qui accélère considérablement le cycle de développement, de test et de débogage de vos automatisations.