Automation Content Navigator

Automation content navigator (ansible-navigator) is a new tool in Red Hat Ansible Automation Platform 2, and is designed to make it easier for you to write playbooks that can be
run in a reproducible manner. It combines the features formerly provided by ansible-playbook, ansible-inventory, ansible-config, and ansible-doc in one top-level interface.

Automation content navigator offers a new interactive mode with a text-based user interface (TUI), and can also be run using the --mode stdout (or -m stdout) option to provide output in the original format used by the earlier tools.

Here are its main features:

  1. Unified CLI Experience

    • Replaces multiple Ansible commands (ansible-playbook, ansible-inventory, ansible-config, ansible-doc) with a single interface.

    • Provides a streamlined and consistent way to interact with Ansible.

  2. Containerized Execution

    • Runs Ansible playbooks within a container, separating the control node from the execution environment.

    • Ensures compatibility across different Python versions and dependencies.

    • Reduces the need for local Ansible installations and dependencies.

  3. Interactive TUI (Text User Interface)

    • Offers an interactive, user-friendly text-based interface.

    • Enables easier navigation through playbook results, inventory, and documentation.

    • Provides real-time insights into playbook execution.

  4. Enhanced Playbook Execution and Debugging

    • Supports interactive viewing of playbook execution with detailed logs.

    • Allows users to explore playbook results step by step.

    • Helps in debugging with real-time feedback.

  5. Seamless Integration with Automation Hub

    • Can access certified and private content collections from Automation Hub.

    • Helps manage and distribute automation content efficiently.

  6. Supports Various Execution Environments

    • Works with Ansible execution environments (EEs), allowing flexibility in managing dependencies.

    • Users can switch between different execution environments as needed.

  7. Inventory and Documentation Management

    • Provides easy access to inventory information with interactive views.

    • Enables browsing of Ansible documentation and content collections directly from the CLI.

Compared with the original method, for example, to run a playbook with ansible-playbook, you might enter the following command:

1
[student@workstation ~]$ ansible-playbook -i inventory playbook.yml

Currently, You can use the ansible-navigator command to do the same thing and get output from the playbook in the same format, as follows:

1
[student@workstation ~]$ ansible-navigator run playbook.yml -i inventory -m stdout

However, if you omit the -m stdout option for the ansible-navigator command, it starts an interactive mode that summarizes the output of the playbook run in real time. This enables you to investigate the results in a TUI after the run completes.

Output of a playbook run with automation content navigator

In the preceding image, you can see that ansible-navigator ran a playbook containing three plays.

You can get more information about the tasks that were run by the first play by pressing 0, or by typing :0 in ansible-navigator:

Output of a playbook run with automation content navigator

You can also get detailed information about particular tasks. In the preceding example, if you press 2 or type :2, then details of the “Ensure HAProxy is started and enabled” task are displayed, and you can use the arrow keys to scroll through the results:

Output of a playbook run with automation content navigator

To go back to previous pages or exit from ansible-navigator at the top-level page, press Esc.

Using Automation Execution Environments to Improve Portability

Automation Execution Environments (EEs) enhance portability by providing a consistent and isolated environment for running Ansible automation. Here’s how they help:

  1. Consistency Across Different Systems

    • EEs encapsulate Ansible, dependencies, and Python libraries into a container image.

    • Ensures that automation runs the same way across different environments, avoiding “works on my machine” issues.

  2. Simplified Dependency Management

    • No need to install Ansible and its dependencies on each system manually.

    • Eliminates conflicts between different versions of Python and Ansible modules.

  3. Improved Reproducibility

    • Playbooks always run within a controlled, versioned environment.

    • Ensures that automation behaves predictably across development, testing, and production.

  4. Seamless Collaboration

    • Teams can share predefined execution environments, reducing setup inconsistencies.

    • Developers and operators can work with the same automation stack, minimizing configuration drift.

  5. Integration with Ansible Navigator

    • ansible-navigator uses execution environments to run playbooks, making automation portable and self-contained.

    • Users can easily switch between different EEs to match specific automation needs.

When you use ansible-navigator to run a playbook, and do not specify a particular automation execution environment, ansible-navigator automatically attempts to pull the default automation execution environment from registry.redhat.io if it is not already present on the system. For Red Hat Ansible Automation Platform 2.2, this default environment includes Ansible Core 2.13 and a standard set of Red Hat Ansible Certified Content Collections.

By default, the ansible-navigator command in Ansible Automation Platform 2.2 attempts to download and use the container image available at registry.redhat.io/ansible-automation-platform-22/ee-supported-rhel8:latests if the automation execution environment is not specified in some other way.

You can also use the --pull-policy (--pp) option to control how ansible-navigator pulls container images. When the value of this option is set to missing, automation content navigator only pulls the container image if the image does not exist on the local system.

Note:

Depending on your container runtime, use the corresponding command to log in to the image registry.

e.g. podman/docker login

Installing ansible-navigator

Ansible is a non-intrusive automation platform, meaning it only needs to be installed on the control node without requiring any software or agents on managed nodes.

Note:

Installation requires an active Red Hat subscription, but in our environment, it is already pre-configured.

1
[student@workstation ~]$ sudo yum -y install ansible-navigator

After installation, you also need to generate the ansible.cfg configuration file and the ansible-navigator.yml configuration file.

  • ansible.cfg is a crucial file that controls the core behavior of Ansible.

    ansible.cfg is the core configuration file for Ansible, used to define Ansible’s global behaviour. It mainly controls the execution of tasks, the method of connecting to remote hosts, and important parameters such as logging and role paths. This file is automatically read when running Ansible, and users can customise Ansible’s runtime environment through it.

    Main Functions:

    • Inventory Configuration: Specifies the default path for the inventory file.

    • Connection Management: Configures SSH connection parameters, such as timeout and control path.

    • Log Management: Defines the location and format of log files to record the execution process.

    • Role and Module Paths: Configures the search paths for custom roles and modules, facilitating the extension of functionalities.

    This file has a high priority and affects the operation of all Ansible tasks. It is the core tool for controlling Ansible’s behaviour.

  • ansible-navigator.yml is a customization tool for configuring the Navigator interface and interactive experience.

    ansible-navigator.yml is a configuration file designed specifically for Ansible Navigator, used to control the interactive interface behaviour, execution environment, and the interaction with inventories and content collections. It is more focused on optimising the user experience and providing a customised operational approach.

    Main Functions:

    • Interactive Mode: Specifies the operating mode of Navigator, such as interactive interface mode or standard output mode.

    • Execution Environment: Defines whether to enable a containerised execution environment and configures the container image and runtime engine (e.g., Podman or Docker).

    • Resource Management: Sets the default inventory file and playbook paths for quicker loading and usage.

    • Logging and Debugging: Controls the location and level of detail for logging, making it easier for users to trace and troubleshoot issues.

    • Interface Optimisation: Adjusts the behaviour and layout of the user interface to improve interaction efficiency.

    This file’s settings focus more on user experience, mainly influencing the operation of the Navigator tool, rather than the core execution logic of Ansible.

These two files complement each other, providing a flexible and efficient automation environment for users.

Configuring Authentication to Managed Hosts

Automation content navigator needs to be able to log in to managed hosts and gain superuser privileges on those hosts. The easiest way to implement this is by using SSH key-based authentication to an account that allows privilege escalation through sudo without a password.

To begin with, you need to generate an SSH key pair on the control node for the automation user, and then distribute the public key to the remote hosts. This enables passwordless SSH authentication between the control node and the remote systems, where user is the remote user and host is one of the managed hosts.

1
2
[student@workstation ~]$ ssh-keygen
[student@workstation ~]$ ssh-copy-id student@servera

Then configure ansible.cfg on the control node or have ansible.cfg in the current directory. Set a remote_user directive to the name of the user account you plan to use on the managed hosts in the [defaults] section of your Ansible configuration file on the control node.

1
vim /etc/ansible/ansible.cfg
1
2
[defaults]
remote_user=student

You need to configure sudo privilege escalation on all managed hosts.

1
2
3
[student@workstation ~]$ sudo vim /etc/sudoers
...
student ALL=(ALL)       NOPASSWD: ALL

The main difference between authenticating ansible-navigator and ansible-playbook to managed hosts is that ansible-navigator runs the playbook inside a container that cannot access your ~/.ssh directory. However, if you are running ssh-agent on your control node to store SSH private keys, when you run ansible-navigator it can automatically provide those keys to the execution environment.

If you logged in to the control node through the graphical desktop environment, ssh-agent is automatically started and the ssh-add command is automatically run to add your private keys to the agent. If any of your SSH private keys are passphrase protected, you are prompted for the password after you log in. Authentication then automatically works for all terminals in that graphical login session.

If you logged in to the control node through a text-based virtual console or remotely using ssh, you must start ssh-agent yourself by running the eval $(ssh-agent) command. In the same shell, you then run ssh-add and if necessary provide the passphrase for your private key. You can then run ansible-navigator in the same shell and authenticate.

1
2
[student@workstation ~]$ eval $(ssh-agent)
[student@workstation ~]$ ssh-add
Earlier Ansible command Automation content navigator subcommand
ansible-config ansible-navigator config
ansible-doc ansible-navigator doc
ansible-inventory ansible-navigator inventory
ansible-playbook ansible-navigator run

Automation content navigator also provides additional functionality. Most subcommands can be run from either the command line or from within an interactive automation content navigator session, but some commands do not support the -m stdout option.

When running a subcommand in an interactive session, type : to start the command, such as :config.

The following chart introduces some ansible-navigator subcommands.

Subcommand Description
collections Get information about installed collections.
config Examine the current Ansible configuration.
doc Examine the Ansible documentation for a plug-in.
help Display detailed help for ansible-navigator.
images Examine an execution environment.
inventory Explore an inventory.
log Review the current log file.
open Open the current page in a text editor.
replay Replay a playbook artifact.
run Run a playbook.

Reviewing Previous Playbook Runs

Automation content navigator provides a new replay feature that displays the output of a previous playbook run. If playbook artifacts are enabled (the default), then the ansible-navigator run command generates an artifact file, which use names such as PlaybookName-artifact-xxxxx.json or similar.

One advantage of the replay file is that if the playbook fails then you can share the replay file with another developer or a support team. They can proceed with troubleshooting without needing to have access to all the files in the project directory, such as playbooks, roles, inventory files, variable
files, and so on.