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.

Pressé ? Les commandes ansible-navigator essentielles

# Run (TUI par défaut — drill-down task → host → JSON)
ansible-navigator run site.yml

# Run (stdout = identique à ansible-playbook, pour CI/CD)
ansible-navigator run site.yml --mode stdout

# Inspecter les images EE disponibles
ansible-navigator images

# Voir les collections embarquées dans l'EE
ansible-navigator collections

# Doc d'un module dans l'EE actif
ansible-navigator doc ansible.posix.firewalld

# Lint (ansible-lint dans l'EE)
ansible-navigator lint site.yml

# Inventaire (graph + détails par host)
ansible-navigator inventory --graph

# Replay d'un run précédent (depuis artifact JSON)
ansible-navigator replay /tmp/ansible-navigator-artifact.json

Sécurité & ergonomie :

• TUI en local pour debug (drill-down, recherche, replay) ; stdout en CI/CD (logs concaténés, parsable).
• replay sur un artifact d’un échec en prod = analyse post-mortem complète sans avoir à rejouer le playbook.
• ansible-navigator doc lit la doc dans l’EE actif — garantit la cohérence de la doc avec la version d’Ansible utilisée (pas la doc web qui peut être plus récente).
• ansible-navigator.yml au projet plutôt que CLI args partout — config reproductible, lisible en revue.

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.

Lab pratique

Le lab ee/hello (labs/ee/hello/README.md) inclut les exercices comparant ansible-playbook classique vs ansible-navigator run (mode stdout puis TUI), avec 6 tests pytest validant la structure (config navigator + EE pinning).

À 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).

Prochaines étapes

Inspecter un EE existant Approfondissement de ansible-navigator images, doc, collections.

Construire son EE custom execution-environment.yml v3, ansible-builder, multi-stage.

Pipeline CI/CD EE GitHub Actions + GitLab CI : build, scan Trivy, push, cosign.

×

📖 Voir la documentation →