Ansible Automation Platform 2 – Navigating Ansible

With the advent of containerized execution environments in Ansible Automation Platform (AAP) 2, proper Ansible tooling becomes increasingly important. Let’s have a look at the new ansible-navigator utility!

AAP 2 moved the ansible runtime environment from local binaries to dedicated containers called execution environments. In previous blogposts of this series, we’ve already covered migrating from Ansible Tower to Controller (in German), and took our first steps with ansible-builder to create our own, customized containers. More information on building these EEs can also be found in the official project documentation (public), and in the Ansible Builder Guide (RedHat customers only).

Now, what happens if you want to use your execution environment not only from an Ansible Controller, but straight from the command-line? That’s where ansible-navigator comes into play!


You can install ansible-navigator as a Python package (pip3 install ansible-navigator --user), or from the Red Hat repositories if you have a valid AAP subscription (dnf install ansible-navigator).

At first sight, ansible-navigator may seem like a mere wrapper for tools like ansible-doc, ansible-inventory and ansible-config. And indeed, with ansible-navigator, you have the same possibilities. In the default behavior, ansible-navigator acts as a text-based user interface (TUI), meaning you can navigate through the output of your Ansible command in a much more convenient way (see also below for an example running a playbook). These basic navigator features translate to their respective legacy commands as follows:

Navigator usage Legacy usage
ansible-navigator doc -t lookup dig ansible-doc -t lookup dig
ansible-navigator inventory -i hosts ansible-inventory -i hosts
ansible-navigator config ansible-config dump

But there are several handy, new features as well: ansible-navigator allows to create an artifact file (JSON) containing all information of an Ansible run. You can then use this file to replay a playbook run. This mode of operation does not actually run Ansible again, but shows you what happened the last time. Furthermore, with ansible-navigator, you can inspect the content of existing EE images, and find information about installed collections.

Command Description
ansible-navigator replay \
Replay a past Ansible run with the information stored in an artifact JSON file.
ansible-navigator images Inspect the content of an execution environment.
ansible-navigator collections Find information about installed collections.

The following example shows how to inspect the Ansible version and collections of a local execution environment named default-ee:

$ ansible-navigator images

Select 2 for inspecting the EE default-ee:

Select 2 again for inspecting the versions of Ansible and the collections:

Using Execution Environments

One of the important new features of ansible-navigator is the possibility to use execution environments to run playbooks. This means that Ansible is no longer run as a Python script on your computer, but the run is delegated to a container. When starting the container, the local directories with your SSH keys are mounted into the container, so it can connect to the hosts in your inventory. Note that when using EEs, the Ansible remote_user now defaults to root and not to the user that is running the ansible-navigator command. Therefore, if you want to run your playbook as eg. the user ansible, make sure to set remote_user = ansible in your ansible.cfg.

When using an EE, you can provide options at the command-line, or set up a local ansible-navigator.yml config file. The configuration file provides a lot of options to tune your Ansible run. The example below shows the required options for running Ansible in the EE default-ee with 20 forks, enabling colorful output, and using an ansible.cfg at a defined location:

$ cat ansible-navigator.yml
      path: /home/ansible/techlab/ansible.cfg
    cmdline: "--forks 20"
    enable: true
    enabled: true
    image: default-ee:latest
Now let’s run a sample playbook called container.yml!
$ ansible-navigator run container.yml
We can choose the first (and only) play in the sample playbook by pressing 0. Next, we can see all the tasks in this play:
We could go on from here, and drill down into the details of each task.

Do it yourself!

If you like to learn more about ansible-navigator and its companion ansible-builder, we recommend our labs at They are free to use. If you’d rather participate in a guided Ansible techlab with one of our experts, please get in touch!

Kommentare sind geschlossen.