Developing Advanced Automation with Red Hat Ansible Automation Platform
Install automation content navigator and use it to run an existing playbook with a supported execution environment.
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.
For example, to run a playbook with ansible-playbook, you might enter the following command:
[user@host ~]$ ansible-playbook playbook.yml -i inventoryYou can use the ansible-navigator command to do the same thing and get output from the playbook in the same format, as follows:
[user@host ~]$ ansible-navigator run playbook.yml -i inventory -m stdoutHowever, 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.
In the preceding image, you can see that ansible-navigator ran a playbook containing three plays.
The first play, "Ensuring HAProxy is deployed", ran nine tasks, six of which made changes.
The second play, "Ensuring Apache HTTP Server is deployed", ran 14 tasks, eight of which made changes.
The third play, "Ensuring web content is deployed", ran four tasks, two of which made changes.
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:
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:
To go back to previous pages or exit from ansible-navigator at the top-level page, press .
One new feature of Red Hat Ansible Automation Platform 2 is support for automation execution environments.
An automation execution environment is a container image that includes Ansible Content Collections, their software dependencies, and a minimal Ansible engine that can run your playbooks and interact with Ansible.
Both ansible-navigator and automation controller (formerly known as Red Hat Ansible Tower) use automation execution environments to simplify the development, testing, and deployment of your automation code in a consistent Ansible environment.
Red Hat provides several supported automation execution environments consisting of slightly different Ansible deployments. You can also create your own customized automation execution environments.
With an automation execution environment, you can avoid creating multiple Python virtual environments on automation controller.
Red Hat Ansible Tower required multiple Python virtual environments to support different combinations of Ansible, modules, Python libraries, and other software dependencies.
This was hard to develop, hard to deploy, and hard to manage.
Red Hat Ansible Automation Platform 2 uses multiple automation execution environments rather than multiple Python virtual environments.
In Ansible Automation Platform, you can create the customized environment in a custom execution environment, test it with ansible-navigator, and distribute it to automation controller as a container image.
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:latest if the automation execution environment is not specified in some other way.
Important
For ansible-navigator to pull the container image for the default automation execution environment (or any other execution environment) from the container registry on registry.redhat.io, it needs to authenticate.
For this to succeed, you must be logged in to registry.redhat.io and have a valid subscription to Ansible Automation Platform.
Use the podman login registry.redhat.io command with your Customer Portal login credentials before running the ansible-navigator command.
You only need to do this once per session.
If the container image has already been downloaded, then ansible-navigator can use that without needing to pull the container image again.
In this course, the classroom might not have internet access in some delivery modes.
However, you can also download the supported container images in this course from a container registry on hub.lab.example.com.
You can use the podman login hub.lab.example.com command to authenticate in the classroom environment using admin as the username and redhat as the password.
After authenticating, you can manually download the available automation execution environments.
The hands-on activities provide detailed instructions.
When you run automation content navigator, you can use the --execution-environment-image (--eei) option to select a specific container image to use as the automation execution environment, such as the ee-supported-rhel8 container image.
Container images are also published with tags so that you can select a specific version of the container image.
For example, you could specify the ee-supported-rhel8:latest container image.
The latest tag indicates that you want the latest version of that image.
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.
You only need to install ansible-navigator on your control node.
You do not need to install ansible-navigator on managed hosts.
You need a valid Red Hat Ansible Automation Platform subscription to install automation content navigator on your control node.
If you are not yet using the product, trial entitlements are available through learn.spidernet.pl and developer entitlements are available through the Red Hat Developer program.
If you have activated Simple Content Access for your organization, then you do not need to attach the entitlement to your system. The installation process is as follows:
Register your system using Red Hat Subscription Manager.
[root@host ~]# subscription-manager registerEnable the Red Hat Ansible Automation Platform 2 repository.
[root@host ~]#subscription-manager repos \>--enable ansible-automation-platform-2.2-for-rhel-8-x86_64-rpms
Note
You do not need to run these subscription-manager commands in the classroom lab environment.
Install the
ansible-navigatorRPM package.
[root@host ~]# yum install ansible-navigatorAutomation 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.
The initial part of the configuration of your managed hosts is identical to the procedure you use for the ansible-playbook command:
Set a
remote_userdirective 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.Use the
ssh-keygencommand to generate an SSH key pair for the user account that you use to runansible-navigator.Install the public key of that key pair in the
~/.ssh/authorized_keysfile for theremote_useraccount on each managed host. You can use thessh-copy-idcommand to do this, whereuser@hostuserhostOn the managed hosts, configure
sudoto allow the remote user you specified to run all commands as any user without a password.
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.
Use the ansible-navigator command to run automation content navigator.
If you run the command with no arguments, or as ansible-navigator welcome, it starts in interactive mode.
This displays a help page describing the subcommands provided by the tool.
Many earlier Ansible commands can be replaced with an automation content navigator subcommand.
| 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.
The following table briefly describes the available 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. |
The help page displayed by ansible-navigator welcome is similar to the preceding table.
When running a subcommand in an interactive session, type : to start the command, such as :config.
The following sections introduce some ansible-navigator subcommands.
Run playbooks using automation content navigator from the command line with the ansible-navigator run command or interactively with the :run subcommand.
The ansible-navigator run command supports most of the same options as the ansible-playbook command.
When using the default interactive mode (rather than stdout mode), you can interactively examine playbook output, as previously discussed.
For example, you might display details for a failed play or for a specific task in a play that failed.
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 site-artifact-2022-10-25T20:09:57.939910+00:00.json or similar.
The first part of the file name refers to the playbook name, and so site is used for a run using the site.yml playbook.
The second part of the file name is the date and time with time zone offset from UTC (+00:00 indicates that the time was recorded in UTC).
Review a previous playbook run by using either the ansible-navigator replay command from the command line or the :replay subcommand in interactive mode.
Most replay files can be safely ignored or even deleted.
If you plan to save a replay file, then consider renaming it so that you can more easily identify it.
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.
Note
Automation content navigator can prompt for passwords, but only if playbook artifacts are disabled. Configuration settings for automation content navigator, including the ability to disable playbook artifacts, are discussed later in the course.
Automation content navigator provides access to documentation for plug-ins, such as modules, lookups, and callbacks, much like the ansible-doc command.
One major difference from the ansible-doc command is that ansible-navigator does not support the --list (-l) option to list all plug-ins of a particular type.
Instead you must explicitly specify the plug-in name.
For example, you can run ansible-navigator doc ansible.posix.firewalld from the command line to display documentation for the ansible.posix.firewalld module.
You can do the same thing by running the :doc ansible.posix.firewalld subcommand from within an interactive automation content navigator session.
Automation content navigator provides multiple ways to get help.
If you are running ansible-navigator in interactive mode, you can type :help to open a help page.
Alternatively, add the --help (-h) option to the ansible-navigator command.
Using this option displays command syntax and describes command options.
Important
Using the --help option does not always display all options.
For example, running the ansible-navigator run --help command displays the main options and then includes the following message:
...output omitted...
Note: 'ansible-navigator run' additionally supports the same parameters as the 'ansible-playbook' command. For more information about these, try 'ansible-navigator run --help-playbook --mode stdout'Provided you have logged in to the classroom's private automation hub, the following command displays additional options:
[student@workstation ~]$ansible-navigator run --help-playbook --mode stdout \>--eei ee-supported-rhel8:latest...output omitted...
