AAP 2.6 ansible-navigator: Modern CLI for Automation Development

By Luca Berton · Published 2024-01-01 · Category: installation

Master ansible-navigator for AAP 2.6 development. Interactive TUI, EE integration, playbook execution, inventory browsing, collection exploration.

What is ansible-navigator?

ansible-navigator is the modern replacement for ansible-playbook, ansible-doc, ansible-inventory, and ansible-config commands. It provides a text-based user interface (TUI) for interactive exploration and integrates natively with Execution Environments (EEs).

Installation

# RHEL/CentOS/Fedora
sudo dnf install ansible-navigator

# pip install
pip install ansible-navigator

# Verify
ansible-navigator --version

Configuration

ansible-navigator.yml

Create a project-level configuration:

---
ansible-navigator:
  ansible:
    config:
      path: ./ansible.cfg
    inventories:
      - ./inventory/
    playbook: site.yml

  execution-environment:
    container-engine: podman
    enabled: true
    image: registry.redhat.io/ansible-automation-platform-26/ee-supported-rhel9:latest
    pull:
      policy: missing
    volume-mounts:
      - src: /tmp/secrets/
        dest: /tmp/secrets/
        options: "ro"

  logging:
    level: warning
    file: /tmp/ansible-navigator.log

  mode: interactive  # or 'stdout' for CI/CD

  playbook-artifact:
    enable: true
    save-as: artifacts/{playbook_name}-{time_stamp}.json

  color:
    enable: true
    osc4: true

Configuration Hierarchy

Command-line arguments (highest priority)
Environment variables (ANSIBLE_NAVIGATOR_*)
Project ansible-navigator.yml (in current directory)
User ~/.ansible-navigator.yml
Defaults

Running Playbooks

Interactive Mode (TUI)

# Run with TUI
ansible-navigator run site.yml

# With inventory
ansible-navigator run site.yml -i inventory/production

# With extra vars
ansible-navigator run site.yml -e "env=production target=webservers"

# With specific EE
ansible-navigator run site.yml \
  --eei registry.redhat.io/ansible-automation-platform-26/ee-supported-rhel9:latest

# With vault
ansible-navigator run site.yml --ask-vault-pass

# Limit hosts
ansible-navigator run site.yml --limit webservers

The TUI shows real-time task execution. Navigate with:

Number keys — drill into specific plays/tasks
:back or Esc — go up a level
:stdout — view raw output
:open — open artifact in editor
:quit or q — exit

Stdout Mode (CI/CD)

# Non-interactive mode for pipelines
ansible-navigator run site.yml --mode stdout

# Equivalent to ansible-playbook
ansible-navigator run site.yml -m stdout -i inventory/production

Exploring Execution Environments

List EE Contents

# Interactive exploration
ansible-navigator images

# View specific image details
ansible-navigator images --eei ee-custom:1.0

The TUI shows:

Image name, tag, and size
Installed collections and versions
Python packages
System packages
Ansible version

Inspect EE

# Non-interactive image info
ansible-navigator images --mode stdout --details \
  --eei registry.redhat.io/ansible-automation-platform-26/ee-supported-rhel9:latest

Browsing Collections

# Interactive collection browser
ansible-navigator collections

# View specific collection
ansible-navigator doc ansible.builtin.copy

# List all modules in a collection
ansible-navigator collections --eei ee-custom:1.0

The TUI lets you:

Browse all installed collections
Drill into modules, roles, plugins
Read full documentation with examples
Search across collections

Inventory Management

# Interactive inventory browser
ansible-navigator inventory -i inventory/production

# View host details
ansible-navigator inventory -i inventory/production --host webserver01

# List mode
ansible-navigator inventory -i inventory/production --list --mode stdout

Navigate the TUI to explore:

Groups and their members
Host variables
Group variables
Dynamic inventory output

Configuration Inspection

# View effective ansible.cfg settings
ansible-navigator config

# Dump current config
ansible-navigator config dump --mode stdout

# Show only changed settings
ansible-navigator config dump --mode stdout --only-changed

Playbook Artifacts

ansible-navigator saves detailed execution artifacts:

{
  "playbook": "site.yml",
  "status": "successful",
  "duration": 145.2,
  "plays": [
    {
      "name": "Configure web servers",
      "tasks": [
        {
          "name": "Install nginx",
          "action": "ansible.builtin.dnf",
          "host_results": {
            "web01": {"changed": true, "rc": 0},
            "web02": {"changed": false, "rc": 0}
          }
        }
      ]
    }
  ]
}

Replay Artifacts

# Replay a previous run
ansible-navigator replay artifacts/site-2026-04-26.json

This opens the TUI with the saved run, letting you drill into tasks and review results without re-running.

Developer Workflow

Local Development Loop

# 1. Write playbook
vim roles/webserver/tasks/main.yml

# 2. Lint
ansible-navigator lint site.yml --mode stdout

# 3. Run with check mode
ansible-navigator run site.yml --check --diff

# 4. Run for real
ansible-navigator run site.yml

# 5. Review artifact
ansible-navigator replay artifacts/site-latest.json

Working Without EEs

# Disable EE (use local ansible)
ansible-navigator run site.yml --execution-environment false
# or
ansible-navigator run site.yml --ee false

Multiple EE Workflow

# ansible-navigator.yml for multi-EE project
---
ansible-navigator:
  execution-environment:
    enabled: true
    image: ee-base:latest  # Default EE

# Override per playbook:
# ansible-navigator run network.yml --eei ee-network:latest
# ansible-navigator run windows.yml --eei ee-windows:latest
# ansible-navigator run cloud.yml --eei ee-cloud:latest

CI/CD Integration

GitHub Actions

- name: Run Ansible playbook
  run: |
    ansible-navigator run deploy.yml \
      --mode stdout \
      --eei ee-deploy:latest \
      -i inventory/staging \
      -e "version=${{ github.sha }}"

GitLab CI

deploy:
  image: quay.io/ansible/ansible-navigator:latest
  script:
    - ansible-navigator run deploy.yml -m stdout -i inventory/production

Comparison with Legacy Commands

Legacy Command	Navigator Equivalent
`ansible-playbook site.yml`	`ansible-navigator run site.yml`
`ansible-doc ansible.builtin.copy`	`ansible-navigator doc ansible.builtin.copy`
`ansible-inventory --list`	`ansible-navigator inventory --list`
`ansible-config dump`	`ansible-navigator config dump`
`ansible-lint`	`ansible-navigator lint`

Key difference: Navigator runs inside EEs by default, ensuring your development environment matches production AAP.

FAQ

Do I need podman or docker for ansible-navigator?

You need a container runtime (podman or docker) only if using Execution Environments (--ee true, which is the default). Without EEs (--ee false), no container runtime is needed — it uses your local Ansible installation.

Can I use ansible-navigator with AAP?

ansible-navigator is for local development. AAP Controller runs jobs on execution nodes. The benefit: develop locally with the same EE image that AAP uses in production, ensuring consistent behavior.

How do I pass vault passwords?

Use --ask-vault-pass for interactive prompts, --vault-password-file for file-based passwords, or set ANSIBLE_VAULT_PASSWORD_FILE environment variable. These work the same as ansible-playbook.

Why is my playbook slower in navigator?

First run pulls the EE image (can be several GB). Subsequent runs are fast. If consistently slow, the EE might be oversized — build a minimal EE with only required collections.

Can I use custom ansible.cfg with navigator?

Yes. Set ansible.config.path in ansible-navigator.yml or use the ANSIBLE_CONFIG environment variable. The config is mounted into the EE automatically.

Conclusion

ansible-navigator is the standard CLI tool for AAP 2.6 development workflows. Its interactive TUI, EE integration, artifact replay, and collection browser make it far more powerful than the legacy ansible-playbook command. Use it locally to develop and test with the same Execution Environments that run in production AAP.

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton