Topic 78

ansible-navigator

ToolingScale

ansible-navigator is the modern command-line runner that executes playbooks inside an execution environment by default, instead of using your local ansible install. It is the bridge between a laptop and EE-based execution: ansible-navigator run site.yml pulls the EE image, runs the play in that container, and hands you an interactive interface to drill from the play down to a single task's full result.

The point is that what you run locally matches what the controller runs in production, because both run the same image. The day-to-day Ansible experience shifts from "I ran it on my machine and it passed" to "I ran it in larkspur-ee:2026.04 and it passed" — and that second sentence means something the first never could.

EE-First Execution

By default ansible-navigator runs inside a container EE, not against your host's ansible. You pass --execution-environment-image larkspur-ee:2026.04 on the command line, or set it once in ansible-navigator.yml, and every run uses exactly that frozen toolchain — the same one AAP uses for the matching job template. Your laptop's collections and Python become irrelevant to the run; the image's contents are what apply, which is the entire reason results stop depending on whose machine ran them.

ansible-navigator.yml — pin the EE so every run uses the controller's toolchain

ansible-navigator:
  execution-environment:
    image: registry.larkspur.io/larkspur-ee:2026.04
    pull:
      policy: missing      # pull the image if it's not already local
  mode: interactive      # the TUI; use 'stdout' for plain scrolling output
  playbook-artifact:
    enable: true          # save each run so you can replay it later

With the image pinned in config, ansible-navigator run site.yml needs no flags — every developer who clones the repo runs the same toolchain, and the laptop-versus-controller gap closes by construction rather than by discipline.

run, and the Other Subcommands

ansible-navigator run executes a playbook, but the runner is more than a play launcher. inventory, config, collections, and doc inspect your inventory, the effective configuration, the installed collections, and module documentation — all from inside the EE. That last part matters: you see what the EE sees, not what your laptop has, so ansible-navigator collections lists the collections that will actually run, and ansible-navigator doc amazon.aws.ec2_instance shows the docs for the exact version baked into the image.

The Interactive TUI

Output is navigable rather than a wall of scrolling text. The interface opens on a play list, descends to per-host task results, and descends again to a single task's full JSON return. You type :0, :1 to step into a numbered item and press Esc to climb back out. A two-hundred-task run that would be an unreadable scroll-back in plain ansible-playbook becomes something you query — jump to the play that failed, then the host, then the one task, without re-running anything.

Inspecting Results

Because runs are saved as artifacts, you can replay a previous run, jump straight to its failed tasks, and read a task's complete return values — not just the one-line status. This is how you debug a changed or a failed after the fact: open the artifact, descend to the task, and read the full result Ansible captured, instead of re-running the whole play with -vvv hoping to reproduce it. The detail you would have gone fishing for is already on disk from the first run.

The Laptop-to-Controller Bridge

Because ansible-navigator runs the same EE the controller runs, "it passes for me" finally carries weight. It is the local development front end to the exact execution model AAP enforces — same image, same collections, same ansible-core — so there is no laptop-versus-controller gap left to chase down when a play behaves differently in production. The discipline boundary is worth keeping, though: navigator is the tool for developing and debugging locally, and the controller is where governed production runs belong, with their RBAC and audit. Running prod interactively from navigator works, and quietly sidesteps every control the controller exists to enforce.

Common Mistakes

Running ansible-navigator expecting it to use your local collections and Python, then being surprised it ignores them — it runs in the EE, and the EE's contents are what apply, not your shell's.
Pointing it at an EE image that lacks a collection the playbook needs, so the run fails inside the container even though ansible-galaxy list on the laptop shows the collection present.
Forgetting to pass or configure the EE image and getting the default base image, which may not contain your dependencies — the image is a required decision, not a detail you can leave blank.
Treating navigator output like ansible-playbook scrolling text and missing that failed-task detail is one keystroke away in the TUI, then re-running with -vvv for information already captured.
Using ansible-navigator run against production interactively as a habit, sidestepping the controller's RBAC and audit — local navigator is for development, the controller is for governed runs.

Best Practices

Pin the EE image in ansible-navigator.yml so every developer runs the same toolchain the controller runs, eliminating the laptop-versus-production gap by construction rather than by reminder.
Use the interactive TUI to descend into failed tasks and read full return values before reaching for -vvv, since the detail you need is already in the run artifact.
Run ansible-navigator inventory and config to confirm what the EE actually resolves, not what your shell has, when chasing a missing host or a wrong variable.
Keep ansible-navigator for local development and feed governed production runs through the controller, so audit and RBAC are never bypassed by an interactive run.
Enable run artifacts so every local run is replayable, turning "what did that failed task return last week?" into opening a file instead of reproducing the run.

Comparable tools plain ansible-playbook the local, non-EE runner it supersedes for EE workflows docker run wrapping a toolchain the manual version of EE execution terraform plan / apply in a pinned container the provisioning-side parallel

Knowledge Check

Why does ansible-navigator run inside an execution environment by default, and what does that guarantee?

It runs the play in the EE container rather than against your local ansible, so the local result matches what the controller runs in production
It uses the EE only to fetch module documentation, then quietly falls back to running the actual play against your local install on the laptop instead
The EE is required because navigator has no SSH client of its own and cannot reach managed hosts without the container
Running the play inside a container is the only way navigator can produce colored, formatted output in your terminal

How does the interactive TUI help you inspect a single task's result?

You descend from the play list to a host to one task's full JSON return, and can replay a saved run to read it without re-executing
It emails the full JSON return of every task straight to the run owner's inbox automatically after each play
It rewrites the playbook on disk to add -vvv verbosity to the failing task and then reruns the whole play
It shows only the one-line ok/changed status, because a single status line is genuinely all that any Ansible task ever returns to the controller

A play passes under ansible-playbook on your laptop but fails under ansible-navigator. What is the most likely reason?

Navigator runs in the EE, which lacks a collection or Python library your local install has, so the EE's contents differ from your laptop's
Navigator runs tasks in a random order, so timing-sensitive plays fail intermittently
Navigator always forces check mode on under the hood, so any task that tries to make a real change on a target host fails outright every time
Navigator silently ignores every become directive, so privileged tasks are denied and the play fails

Where is the line between local ansible-navigator runs and controller runs?

Navigator is for local development and debugging; governed production runs go through the controller, which enforces RBAC and audit
Navigator handles all the governed production runs, while the controller is only ever used for throwaway local development sandboxes
There is no line at all — navigator and the controller are fully interchangeable for any run you might want
Navigator can only ever run in check mode, so all of the real changes are forced to go through the controller

You got correct