ansible-navigator Documentation

ansible-navigator is a command-line tool and a text-based user interface (TUI) designed for managing the lifecycle of Ansible content. It provides a unified interface for:

• Creating and reviewing Ansible content (inventories, playbooks, collections, and documentation).
• Running and troubleshooting Ansible content.
• Managing container images known as Execution Environments (EEs).

Settings in ansible-navigator are applied hierarchically. If a setting is defined in multiple places, the last one in this list takes precedence:

1. Default internal values
2. Values from a settings file
3. Values from environment variables
4. Flags and arguments specified on the command line
5. Commands issued via : within the Text User Interface (TUI)

ansible-navigator operates in two distinct modes:

1. interactive (default): A curses-based text-based user interface (TUI) that allows you to "zoom in" on data in real time, filter results, and navigate between Ansible components.
2. stdout: A non-interactive mode that does not use curses. It returns output directly to the terminal's standard output stream, mimicking the behavior of standard Ansible commands.

You can switch to stdout mode using the --mode stdout (or -m stdout) flag or by configuring the mode setting in your configuration file.

ansible-navigator generates a JSON artifact for every playbook run (e.g., site-artifact-TIMESTAMP.json). These files contain detailed task information and stdout.

You can review these artifacts using:

• The CLI: ansible-navigator replay <filename>
• The TUI: Use the :replay <filename> command.

Artifact writing and naming conventions can be customized in the settings file.

ansible-navigator replay site-artifact-2021-06-02T16:02:33.911259+00:00.json

You can run the ansible-test utility from within an execution environment without having it installed locally by using the exec subcommand.

$ cd  ./collections/ansible_collections/ansible/utils/
$ ansible-navigator exec -- ansible-test sanity --python 3.10

When using an execution environment (EE), the easiest way to provide an ansible.cfg file is to place it in the project directory adjacent to your playbook. ansible-navigator automatically mounts the playbook directory into the EE, allowing Ansible to find the configuration.

If your ansible.cfg is located elsewhere, you must:

1. Set the ANSIBLE_CONFIG environment variable to the file path.
2. Specify the directory containing the file as a custom volume mount using the execution-environment-volume-mounts setting.

When defining volume mounts using the ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_VOLUME_MOUNTS environment variable, you must use a semicolon (;) as a delimiter because the standard colon (:) is used within the mount definition itself.

export ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_VOLUME_MOUNTS /tmp/1:/tmp/1\;/tmp/2:/tmp/2:Z
ansible-navigator exec

Any parameters that are not direct ansible-navigator options will be passed through to the underlying ansible-playbook command. You can provide these inline or use the -- delimiter to separate ansible-navigator arguments from ansible-playbook arguments.

$ ansible-navigator run site.yml --forks 15
$ ansible-navigator run site.yml -- --forks 15

You can install ansible-navigator using pip. It is recommended to install it with the ansible-core extra to ensure compatibility.

By default, ansible-navigator uses a container runtime (podman or docker, whichever is found first) to run Ansible within an execution environment (a pre-built container image containing ansible-core and collections).

To disable the execution environment and run Ansible directly on your host system, use the --execution-environment false flag. In this mode, you must ensure ansible-core and all required collections are manually installed on your system.

pip3 install 'ansible-navigator[ansible-core]'
ansible-navigator --help

To execute complex piped commands inside an execution environment, use the -- delimiter. Everything following the -- is passed directly into the execution environment.

$ ansible-navigator exec -- ansible --version | head -n 1 | awk -F '\\[|\\\]|\\s' '{print $4}'