agentsclimarketplace
Sign in

Ansible navigator config

Skill stoleas/ansible-skills/skills/ansible-navigator-config

Configure ansible-navigator for optimal workflow, execution environment integration, and troubleshooting. Use this skill when the user asks to: "configure ansible-navigator", "setup navigator", "navigator config", "ansible-navigator settings", "navigator ee integration", "navigator troubleshooting", "ansible-navigator.yml", "set up ansible navigator", or wants to configure or optimize their ansible-navigator workflow. Always invoke this skill for ansible-navigator configuration and usage guidance.From its SKILL.md

Install
npx -y skills add stoleas/ansible-skills --skill ansible-navigator-config

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

18.0 KB, as published. Nobody here has run it

Ansible Navigator Configuration Skill

Configure ansible-navigator for optimal workflow, execution environment integration, log management, and troubleshooting.

What is ansible-navigator?

ansible-navigator is a text-based user interface (TUI) for Ansible that provides:

  • Interactive playbook execution with real-time exploration
  • Execution environment integration for containerized runs
  • Log replay and analysis
  • Collection/inventory browsing
  • Enhanced debugging capabilities
  • Artifact generation for CI/CD integration

Key Benefits:

  • Consistent runtime environments (via EEs)
  • Better visibility into playbook execution
  • Improved troubleshooting workflow
  • CI/CD friendly (stdout mode)
  • Log replay for post-execution analysis

Installation

# Install ansible-navigator
pip install ansible-navigator

# Verify installation
ansible-navigator --version

# Optional: Install execution environment support
pip install ansible-builder

# Container runtime (one of these)
# Podman (recommended)
sudo dnf install podman

# Or Docker
sudo apt-get install docker.io

Configuration File: ansible-navigator.yml

Place in project root or home directory (~/.ansible-navigator.yml).

Basic Configuration

---
ansible-navigator:
  # Execution environment settings
  execution-environment:
    enabled: true
    image: quay.io/ansible/creator-ee:latest
    pull:
      policy: missing  # missing, always, never, tag
    container-engine: podman  # podman or docker
    
  # Mode settings
  mode: interactive  # interactive or stdout
  
  # Playbook execution settings
  playbook-artifact:
    enable: true
    replay: artifacts/
    save-as: "{playbook_dir}/artifacts/{playbook_name}-artifact-{time_stamp}.json"
  
  # Logging
  logging:
    level: info  # debug, info, warning, error, critical
    append: true
    file: ansible-navigator.log
  
  # Editor for interactive mode
  editor:
    command: vim {filename}
    console: true
  
  # Inventory settings
  inventories:
    - inventory/production
    - inventory/staging

Advanced Configuration

---
ansible-navigator:
  # Execution environment configuration
  execution-environment:
    enabled: true
    image: my-custom-ee:1.0.0
    
    pull:
      policy: missing
      arguments:
        - "--tls-verify=false"  # For internal registries
    
    container-engine: podman
    container-options:
      - "--net=host"           # Use host networking
      - "--privileged"         # If needed (use cautiously)
    
    environment-variables:
      set:
        ANSIBLE_CONFIG: /runner/project/ansible.cfg
        CUSTOM_VAR: value
      pass:
        - HTTP_PROXY
        - HTTPS_PROXY
    
    volume-mounts:
      - src: /local/path
        dest: /runner/local
        options: Z  # SELinux label
  
  # Ansible configuration
  ansible:
    config: ansible.cfg
    cmdline: "--forks 15 --timeout 60"
    inventories:
      - inventory/
  
  # Playbook configuration
  playbook-artifact:
    enable: true
    replay: artifacts/
    save-as: "artifacts/{playbook_name}-{time_stamp}.json"
  
  # Documentation settings
  documentation:
    plugin:
      name: shell
      type: module
  
  # Collection settings
  collection-doc-cache-path: ~/.cache/ansible-navigator/collection_doc_cache
  
  # Color settings
  color:
    enable: true
    osc4: true  # Terminal color change support
  
  # Display settings
  display-color:
    changed: yellow
    debug: dark_gray
    ok: green
    skip: cyan
  
  # Editor configuration
  editor:
    command: code -w {filename}  # VS Code
    console: false
  
  # Format settings
  format: yaml  # yaml or json
  
  # Logging
  logging:
    level: debug
    append: true
    file: ~/.ansible-navigator.log
  
  # Mode
  mode: interactive
  
  # Images
  images:
    details:
      - ansible_version
      - python_version
      - collections
  
  # Time zone
  time-zone: UTC

Execution Environment Integration

Using Custom EE

---
ansible-navigator:
  execution-environment:
    enabled: true
    image: quay.io/myorg/my-custom-ee:1.0.0
    pull:
      policy: missing
    
    # Mount project directory
    volume-mounts:
      - src: "{project_dir}"
        dest: /runner/project
        options: Z
      
      # Mount SSH keys
      - src: ~/.ssh
        dest: /home/runner/.ssh
        options: ro,Z
      
      # Mount custom inventory
      - src: /etc/ansible/inventory
        dest: /runner/inventory
        options: ro,Z

Environment Variables

execution-environment:
  environment-variables:
    # Set variables
    set:
      ANSIBLE_VAULT_PASSWORD_FILE: /runner/.vault_pass
      ANSIBLE_FORCE_COLOR: "true"
      CUSTOM_API_KEY: "${API_KEY}"  # From host environment
    
    # Pass through from host
    pass:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - HTTP_PROXY
      - HTTPS_PROXY
      - NO_PROXY

Without Execution Environment

For local Ansible installation:

---
ansible-navigator:
  execution-environment:
    enabled: false  # Use local Ansible
  
  ansible:
    config: ansible.cfg
    playbook: playbooks/site.yml

Mode Configuration

Interactive Mode (Development)

Best for development and troubleshooting:

ansible-navigator:
  mode: interactive
  
  editor:
    command: vim {filename}
    console: true
  
  playbook-artifact:
    enable: true
    save-as: "artifacts/{playbook_name}-artifact.json"

Features:

  • Navigate through playbook execution
  • Drill into tasks, hosts, results
  • Review documentation inline
  • Replay from artifacts

Usage:

ansible-navigator run playbook.yml
# Interactive TUI launches
# Use arrow keys to navigate
# Press number keys to drill down
# Press ESC to go back
# Press :q to quit

Stdout Mode (CI/CD)

Best for automation and CI/CD:

ansible-navigator:
  mode: stdout
  
  playbook-artifact:
    enable: true
    save-as: "artifacts/{playbook_name}-{time_stamp}.json"
  
  logging:
    level: info
    file: ansible-navigator.log

Features:

  • Standard output (like ansible-playbook)
  • Artifact generation for later review
  • CI/CD friendly
  • Non-interactive

Usage:

ansible-navigator run playbook.yml --mode stdout
# Output goes to stdout like normal
# Artifact saved for replay

Command Patterns

Running Playbooks

# Interactive mode
ansible-navigator run playbook.yml

# Stdout mode (CI/CD)
ansible-navigator run playbook.yml --mode stdout

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

# With extra vars
ansible-navigator run playbook.yml -e "env=production"

# With tags
ansible-navigator run playbook.yml --tags install,configure

# Check mode
ansible-navigator run playbook.yml --check

# With custom EE
ansible-navigator run playbook.yml \
  --execution-environment-image my-ee:1.0.0

# Replay from artifact
ansible-navigator replay artifacts/site-artifact-2026-04-25.json

Exploring Collections

# Browse collections
ansible-navigator collections

# View specific collection
ansible-navigator collections ansible.posix

# View module documentation
ansible-navigator doc ansible.builtin.copy

# Search modules
ansible-navigator doc -l | grep copy

Exploring Inventory

# Browse inventory
ansible-navigator inventory

# View specific host
ansible-navigator inventory --host server01

# List all hosts
ansible-navigator inventory --list

# Graph view
ansible-navigator inventory --graph

Exploring Images

# List EE images
ansible-navigator images

# Inspect specific image
ansible-navigator images my-custom-ee:1.0.0

# Show image details (collections, python version, etc.)
ansible-navigator images my-custom-ee:1.0.0 --details

Configuration

# Show current configuration
ansible-navigator config

# Dump configuration
ansible-navigator config dump

# Show configuration sources
ansible-navigator config dump --mode stdout

Artifact Analysis

Artifacts are JSON files containing complete playbook execution details.

Artifact Structure

{
  "version": "1.0",
  "plays": [
    {
      "play": {
        "name": "Configure web servers",
        "id": "uuid",
        "duration": {"start": "...", "end": "..."}
      },
      "tasks": [
        {
          "task": {
            "name": "Install Apache",
            "id": "uuid"
          },
          "hosts": {
            "server01": {
              "action": "ansible.builtin.package",
              "changed": true,
              "failed": false,
              "result": {...}
            }
          }
        }
      ]
    }
  ]
}

Replay Artifacts

# Replay in interactive mode
ansible-navigator replay artifacts/playbook-artifact.json

# Extract specific information with jq
jq '.plays[0].tasks[] | select(.task.name == "Install Apache")' \
  artifacts/playbook-artifact.json

# Count changed tasks
jq '[.plays[].tasks[].hosts[] | select(.changed == true)] | length' \
  artifacts/playbook-artifact.json

# List failed tasks
jq -r '.plays[].tasks[] | select(.hosts[].failed == true) | .task.name' \
  artifacts/playbook-artifact.json

Logging and Debugging

Log Configuration

ansible-navigator:
  logging:
    level: debug  # For troubleshooting
    append: true
    file: ~/.ansible-navigator/navigator.log

Log Analysis

# View recent logs
tail -f ~/.ansible-navigator/navigator.log

# Search for errors
grep -i error ~/.ansible-navigator/navigator.log

# Filter by log level
grep "ERROR\|CRITICAL" ~/.ansible-navigator/navigator.log

Debug Output

# Run with increased verbosity
ansible-navigator run playbook.yml -vvv

# Debug mode in config
ansible-navigator:
  logging:
    level: debug
  ansible:
    cmdline: "-vvv"

CI/CD Integration

GitHub Actions

name: Run Ansible Playbook

on:
  push:
    branches: [main]

jobs:
  ansible:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install ansible-navigator
        run: pip install ansible-navigator
      
      - name: Run playbook
        run: |
          ansible-navigator run playbook.yml \
            --mode stdout \
            --pull-policy always \
            --execution-environment-image my-ee:latest
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playbook-artifact
          path: artifacts/*.json

GitLab CI

ansible-playbook:
  stage: deploy
  image: quay.io/ansible/creator-ee:latest
  script:
    - pip install ansible-navigator
    - |
      ansible-navigator run site.yml \
        --mode stdout \
        --execution-environment-image ${CI_REGISTRY_IMAGE}/ansible-ee:latest \
        --pull-policy always
  artifacts:
    paths:
      - artifacts/*.json
    when: always

Jenkins

pipeline {
  agent any
  
  stages {
    stage('Run Ansible') {
      steps {
        sh '''
          pip install ansible-navigator
          ansible-navigator run playbook.yml \
            --mode stdout \
            --execution-environment-image my-ee:1.0.0
        '''
      }
    }
  }
  
  post {
    always {
      archiveArtifacts artifacts: 'artifacts/*.json'
    }
  }
}

Troubleshooting

Common Issues

1. EE Image Not Found

Problem:

Error: image not found: my-custom-ee:1.0.0

Solutions:

# Pull the image first
execution-environment:
  pull:
    policy: always  # Force pull

# Or use full registry path
execution-environment:
  image: quay.io/myorg/my-custom-ee:1.0.0

# Manually pull image
podman pull my-custom-ee:1.0.0

# Check available images
podman images

2. Volume Mount Permission Denied

Problem:

Error: Permission denied accessing /runner/project

Solutions:

# Add SELinux label (on RHEL/Fedora)
volume-mounts:
  - src: "{project_dir}"
    dest: /runner/project
    options: Z  # Relabel for container

# Or run with privileged
container-options:
  - "--privileged"  # Use cautiously

3. SSH Key Access

Problem:

Error: SSH key not accessible in container

Solutions:

# Mount SSH directory
volume-mounts:
  - src: ~/.ssh
    dest: /home/runner/.ssh
    options: ro,Z

# Or use ssh-agent forwarding
environment-variables:
  set:
    SSH_AUTH_SOCK: /run/user/1000/ssh-agent.sock

volume-mounts:
  - src: /run/user/1000/ssh-agent.sock
    dest: /run/user/1000/ssh-agent.sock

4. Inventory Not Found

Problem:

Error: Unable to find inventory

Solutions:

# Specify inventory explicitly
ansible:
  inventories:
    - inventory/production

# Or mount external inventory
volume-mounts:
  - src: /etc/ansible/inventory
    dest: /runner/inventory
    options: ro,Z

5. Collection Not Found in EE

Problem:

Error: collection not found in execution environment

Solutions:

# Verify collections in EE
ansible-navigator images my-ee:1.0.0 --details

# Or run with local collections
execution-environment:
  volume-mounts:
    - src: ~/.ansible/collections
      dest: /runner/collections
      options: ro,Z

Project Configuration Examples

Development Setup

---
# ansible-navigator.yml (development)
ansible-navigator:
  execution-environment:
    enabled: true
    image: quay.io/ansible/creator-ee:latest
    pull:
      policy: missing
    volume-mounts:
      - src: "{project_dir}"
        dest: /runner/project
        options: Z
  
  mode: interactive
  
  editor:
    command: code -w {filename}
    console: false
  
  playbook-artifact:
    enable: true
    save-as: "artifacts/{playbook_name}-artifact.json"
  
  logging:
    level: info
    file: navigator.log

Production/CI Setup

---
# ansible-navigator.yml (production)
ansible-navigator:
  execution-environment:
    enabled: true
    image: quay.io/myorg/prod-ee:1.0.0
    pull:
      policy: always
    
    environment-variables:
      pass:
        - VAULT_PASSWORD
        - AWS_ACCESS_KEY_ID
        - AWS_SECRET_ACCESS_KEY
  
  mode: stdout
  
  ansible:
    config: ansible.cfg
    cmdline: "--forks 20"
  
  playbook-artifact:
    enable: true
    save-as: "artifacts/{playbook_name}-{time_stamp}.json"
  
  logging:
    level: warning
    file: /var/log/ansible-navigator.log

Multi-Environment Setup

---
# ansible-navigator.yml (multi-env)
ansible-navigator:
  execution-environment:
    enabled: true
    image: my-ee:${ENV_TAG:-latest}  # Environment-specific tag
    
    volume-mounts:
      - src: "{project_dir}"
        dest: /runner/project
        options: Z
      - src: "inventory/${ENV:-dev}"
        dest: /runner/inventory
        options: ro,Z
  
  ansible:
    inventories:
      - inventory/${ENV:-dev}
  
  mode: ${NAVIGATOR_MODE:-interactive}

Usage:

# Development
ENV=dev ansible-navigator run playbook.yml

# Staging
ENV=staging NAVIGATOR_MODE=stdout ansible-navigator run playbook.yml

# Production
ENV=production ENV_TAG=1.0.0 NAVIGATOR_MODE=stdout \
  ansible-navigator run playbook.yml

Best Practices

1. Always Use Artifacts

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

Benefits:

  • Post-execution analysis
  • Debugging failed runs
  • Audit trail
  • CI/CD integration

2. Pin EE Versions in Production

# Good - specific version
execution-environment:
  image: my-ee:1.2.3

# Bad - unpredictable
execution-environment:
  image: my-ee:latest

3. Use Appropriate Mode

  • Development: mode: interactive
  • CI/CD: mode: stdout
  • Debugging: mode: interactive + logging.level: debug

4. Organize Artifacts

artifacts/
├── development/
├── staging/
└── production/

playbook-artifact:
  save-as: "artifacts/${ENV}/{playbook_name}-{time_stamp}.json"

5. Secure Sensitive Data

# Never commit passwords
# Use environment variables
environment-variables:
  pass:
    - VAULT_PASSWORD
    - API_TOKEN
    - AWS_SECRET_ACCESS_KEY

# Mount secrets securely
volume-mounts:
  - src: ~/.vault_pass
    dest: /runner/.vault_pass
    options: ro,Z

Quick Reference

Common Commands

# Run playbook interactively
ansible-navigator run playbook.yml

# Run in CI/CD mode
ansible-navigator run playbook.yml --mode stdout

# Replay artifact
ansible-navigator replay artifacts/playbook-artifact.json

# Browse collections
ansible-navigator collections

# View documentation
ansible-navigator doc ansible.builtin.copy

# Check inventory
ansible-navigator inventory --list

# Inspect EE image
ansible-navigator images my-ee:1.0.0

# Show config
ansible-navigator config dump

Interactive Mode Keys

  • Arrow keys: Navigate
  • Number keys: Drill down (0-9)
  • ESC: Go back
  • : : Command mode
  • :q: Quit
  • :help: Show help
  • :o: Open in editor
  • :f: Filter
  • :write: Save output

Output Template

When configuring ansible-navigator, provide:

  1. ansible-navigator.yml with appropriate settings
  2. Explanation of key configuration choices
  3. Usage examples for common scenarios
  4. Troubleshooting guidance for likely issues
  5. Integration examples (CI/CD if applicable)

Explain:

  • Why specific settings were chosen
  • How to run in different modes
  • How to analyze artifacts
  • How to troubleshoot common issues
  • How to integrate with workflows

When asked to configure ansible-navigator, analyze requirements, generate appropriate configuration, and provide comprehensive usage and troubleshooting guidance.

Keep looking

Skills are one crate of 628,971. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.