ansible-navigator : modes interactif TUI et stdout, sous-commandes essentielles

ansible-navigator est l'outil unique qui remplace ansible-playbook quand on veut exécuter dans un EE. Il offre deux modes : TUI interactif pour le debug riche (drill-down task → host → JSON), et stdout pour la CI/CD (sortie identique à ansible-playbook classique). Cette page passe en revue les 7 sous-commandes essentielles (run, images, inventory, lint, doc, collections, config) avec exemples concrets, puis détaille la navigation clavier TUI et la fonctionnalité replay des artifacts.

À la fin, vous saurez choisir le bon mode selon le contexte et exploiter pleinement les capacités de debug de navigator.

Ce que vous allez apprendre

• Différence TUI vs stdout et quand utiliser chacun.
• Les 7 sous-commandes principales d'ansible-navigator.
• Navigation clavier TUI : drill-down, recherche, retour.
• Artifacts JSON : playbook-artifact.enable et replay.
• Variables d'environnement : ANSIBLE_NAVIGATOR_*.

Prérequis

• Avoir terminé Installation et configuration.
• creator-ee:latest pull localement.

TUI vs stdout, quand utiliser quoi

Mode	Usage typique	Avantage clé
-m stdout	CI/CD, scripts, redirection logs	Identique à ansible-playbook -v
TUI (défaut)	Debug local, formation	Drill-down task → host → JSON

Glissez pour voir

Règle : mettez mode: stdout dans votre ansible-navigator.yml projet, et passez en TUI explicitement quand vous debuggez un échec :

# Mode CI/CD habituel
ansible-navigator run site.yml

# Debug d'un échec
ansible-navigator run site.yml --mode interactive

Les 7 sous-commandes essentielles

run, exécuter un playbook

ansible-navigator run site.yml \
  -i inventory.yml \
  --eei quay.io/ansible/creator-ee:latest \
  -m stdout

Options fréquentes :

• -i / --inventory : inventaire (peut être répété).
• --eei / --execution-environment-image : surcharge l'EE par défaut.
• -m / --mode : stdout ou interactive.
• --pas / --playbook-artifact-save-as : nom du fichier artifact JSON.
• -e / --extra-vars : variables ad-hoc.
• --tags / --skip-tags : filtrer les tâches.

images, inspecter un EE

ansible-navigator images --eei quay.io/ansible/creator-ee:latest

Ouvre la TUI avec 8 vues : Image information, Image layers, OS release, System packages, Ansible version, Ansible collections, Python packages, Python version. Indispensable avant de consommer un EE.

inventory, explorer un inventaire

ansible-navigator inventory -i inventory.yml

TUI structurée : groupes, hosts, variables. Drill-down sur un host pour voir toutes les variables résolues (group_vars, host_vars, defaults).

lint, ansible-lint dans l'EE

ansible-navigator lint site.yml

Lance ansible-lint dans l'EE (la version creator-ee embarque ansible-lint). Évite les divergences entre lint local et EE de prod.

doc, documentation d'un module

ansible-navigator doc ansible.builtin.copy

TUI avec : Synopsis, paramètres typés, exemples YAML, return values. Doc embarquée dans l'EE, exactement la version qui s'exécutera.

collections, lister les collections

ansible-navigator collections --eei quay.io/ansible/creator-ee:latest

Liste structurée des collections + version de chacune. Plus lisible que ansible-galaxy collection list brut.

config, voir la config Ansible effective

ansible-navigator config dump

Affiche la configuration Ansible vue par l'EE : defaults.host_key_checking, ssh_connection.pipelining, etc. Différent de votre ansible.cfg local, c'est ce qui compte pour l'exécution.

Navigation TUI, clavier de référence

Une fois dans la TUI, les raccourcis :

Touche	Action
0-9	Sélectionner l'item numéroté
↑↓	Naviguer dans une liste
↵ (Entrée)	Drill-down (entrer dans l'item)
Esc	Remonter d'un niveau
:doc <module>	Doc d'un module à la volée
:help	Aide contextuelle
:q ou :quit	Quitter
/<terme>	Recherche

Glissez pour voir

Exemple drill-down : depuis run site.yml, vous voyez les plays (numérotés). 0 entre dans le premier play → liste des tasks. 2 entre dans la 3e task → liste des hosts. 0 entre dans le 1er host → JSON brut du résultat.

Artifacts JSON et replay

Ajoutez à ansible-navigator.yml :

ansible-navigator:
  playbook-artifact:
    enable: true
    save-as: '{playbook_name}-artifact-{ts_utc}.json'

À chaque run, navigator écrit un artifact JSON complet (toutes les tasks, tous les hosts, toutes les sorties).

Rejouer :

ansible-navigator replay site-artifact-2026-04-26T18-30-00.json

Ouvre la TUI sans réexécuter, exactement comme si vous étiez en train de regarder le run, mais à partir d'un fichier figé. Permet à un dev de partager un échec à un collègue : « tiens, voilà l'artifact, regarde l'erreur task #14 ».

Variables d'environnement utiles

Variable	Effet
ANSIBLE_NAVIGATOR_EE_IMAGE	Surcharge l'EE par défaut
ANSIBLE_NAVIGATOR_MODE	stdout ou interactive
ANSIBLE_NAVIGATOR_CONFIG	Chemin vers un ansible-navigator.yml
ANSIBLE_NAVIGATOR_LOG_LEVEL	debug / info / warning / error

Glissez pour voir

Pratique pour la CI/CD : ANSIBLE_NAVIGATOR_MODE=stdout dans le runner force la sortie texte sans toucher au fichier de config.

Cas pratique, debug d'une task qui échoue

Scénario : une task ansible.builtin.template échoue sur web1.lab mais pas web2.lab.

1. Lancer en TUI :

   ansible-navigator run site.yml --mode interactive

2. Drill-down : vous voyez le PLAY RECAP, web1.lab : failed=1. Tapez 0 pour entrer dans les plays, ↵ sur le play, descendez sur la task qui a [*] (status fail).

3. Voir le JSON : tapez ↵ sur la task → liste des hosts. Tapez 0 sur web1.lab → JSON brut de l'erreur.

4. Comparer : Esc, sélectionnez web2.lab, comparez les variables résolues.

5. Rejouer après fix : modifiez le template, :q, relancez.

🔍 Observation : ce workflow, voir le JSON brut directement, comparer hosts, est beaucoup plus rapide que ansible-playbook -vvv qui noie l'info utile.

Mettre en pratique

Ces sous-commandes prennent leur sens quand elles servent un besoin réel : retrouver un module dont on a oublié le nom, puis s'en servir sans changer d'outil. Ce lab vous fait chercher avec ansible-navigator doc le module qui gère les entrées sysctl, l'appliquer pour poser vm.swappiness = 42 de façon persistante et idempotente sur db1.lab, puis valider l'inventaire ciblé avec ansible-navigator inventory --list. La correction interroge l'état de la machine, pas la sortie affichée dans votre terminal.

Lab pratique

Automation content navigator : découvrir un module dans une collection et l'utiliser

$ dsoxlab run collections-navigator

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 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 collections-navigator
dsoxlab check collections-navigator

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.

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

• -m stdout pour CI/CD, TUI pour debug local.
• 7 sous-commandes : run, images, inventory, lint, doc, collections, config.
• Drill-down TUI : task → host → JSON, parfait pour debug.
• Artifacts JSON + replay : partager un échec sans relancer.
• ANSIBLE_NAVIGATOR_MODE=stdout dans le CI pour forcer la sortie texte.
• config dump affiche la config effective dans l'EE (différente du local).

Pour aller plus loin

• Construire un EE custom : Quand l'EE communautaire ne contient pas la collection dont vous avez besoin.
• Exécution en CI/CD : Le mode stdout prend tout son sens dans un pipeline, sur une image construite et signée.
• Debug d'un EE cassé : Lire une image qui démarre mais ne contient pas ce qu'elle devrait.

×

📖 Voir la documentation →