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.

# 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

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.

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

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`

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.

Lancer en TUI :

ansible-navigator run site.yml --mode interactive

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).
Voir le JSON : tapez ↵ sur la task → liste des hosts. Tapez 0 sur web1.lab → JSON brut de l'erreur.
Comparer : Esc, sélectionnez web2.lab, comparez les variables résolues.
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.