Ansible Navigator Creator Guide

Chapter 1. Ansible content navigator

As a content creator, you can use Automation content navigator to develop Ansible playbooks, collections, and roles that are compatible with the Red Hat Ansible Automation Platform. You can use Automation content navigator on local development machines, Automation execution environments or the Red Hat Ansible Automation Platform, with seamless and predictable results across them all. Automation content navigator also produces an artifact file you can use to help you develop your playbooks and troubleshoot problem areas.

1.1. About Automation content navigator

Automation content navigator is a command line, content creator focused tool with a text-based user interface that allows you to:

Launch and watch jobs and playbooks.
Share stored, completed playbook and job run artifacts in JSON format.
Browse and introspect automation execution environments.
Browse your file-based inventory.
Render Ansible module documentation and extract examples you can use in your playbooks.

1.1.1. Why use Automation content navigator?

Currently, the Ansible commands that are part of Ansible core, such as the ansible-playbook command, cannot execute in containers. To fill this need, Automation content navigator enables a set of these Ansible CLI commands within automation execution environments. Automation content navigator includes a more detailed output within its text-based user interface.

1.2. Automation content navigator modes

Automation content navigator operates in two modes:

stdout mode: Accepts most of the existing Ansible commands and extensions at the command line.
text-based user interface mode: Provides an interactive, text-based interface to the Ansible commands for an enhanced set of capabilities that allow you to evaluate content, run playbooks, and troubleshoot playbooks after they run using artifact files.

1.2.1. stdout mode

If you use the -m stdout subcommand, Automation content navigator uses the familiar Ansible commands, such as ansible-playbook within automation execution environments, or on your local development environment. This mode allows you to continue using commands you are familiar with for quick tasks.

Automation content navigator also provides extensive help in this mode:

--help: Accessible from ansible-navigator command or from any subcommand, such as ansible-navigator config --help.
subcommand help: Accessible from the subcommand, for example ansible-navigator config --help-config. This subcommand specific help brings in the details of all the parameters supported from the related Ansible command, in this example, ansible-config.

1.2.2. Text-based user interface mode

The text-based user interface mode provides enhanced interaction with automation execution environments, collections, playbooks, and inventory. This mode is compatible with integrated development environments (IDE), such as Visual Studio Code.

This mode includes a number of helpful user interface options:

colon commands: You can access all the Automation content navigator commands with a colon, such as :run or :collections
navigating the text-based interface: The screen shows how to page up or down, scroll, escape to a prior screen or access :help.
output by line number: You can access any line number in the displayed output by preceding it with a colon, for example :12.
color-coded output: With colors enabled, Automation content navigator displays items such as deprecated modules in red.
pagination and scrolling: You can page up or down or scroll and escape using the options displayed at the bottom of each Automation content navigator screen.

You cannot switch between modes once Automation content navigator is running.

1.3. Automation content navigator commands

The Automation content navigator commands run familiar Ansible CLI commands in -m stdout mode. You can use all of the subcommands and options allowed in the related Ansible CLI command. Use ansible-navigator --help for details.

Table 1.1. Automation content navigator command table
Command	Description	CLI example
collections	Explore available collections	`ansible-navigator collections --help`
config	Explore the current ansible configuration	`ansible-navigator config --help`
doc	Review documentation for a module or plugin	`ansible-navigator doc --help`
images	Explore execution environment images	`ansible-navigator images --help`
inventory	Explore an inventory	`ansible-navigator inventory --help`
replay	Explore a previous run using a playbook artifact	`ansible-navigator replay --help`
run	Run a playbook	`ansible-navigator run --help`
welcome	Start at the welcome page	`ansible-navigator welcome --help`

1.4. Automation content navigator command comparison

The Automation content navigator commands run familiar Ansible CLI commands in -m stdout mode. You can use all of the subcommands and options allowed in the related Ansible CLI command. Use ansible-navigator --help for details.

Table 1.2. Comparing Automation content navigator and Ansible CLI commands table
Ansible navigator command	Ansible CLI command
`ansible-navigator collections`	`ansible-galaxy collection`
`ansible-navigator config`	`ansible-config`
`ansible-navigator doc`	`ansible-doc`
`ansible-navigator inventory`	`ansible-inventory`
`ansible-navigator run`	`ansible-playbook`

Chapter 2. Installing Automation content navigator on RHEL

As a content creator, you can install Automation content navigator on Red Hat Enterprise Linux (RHEL) 8.

2.1. Prerequisites

You have installed RHEL 8 or later.

2.2. Installing Automation content navigator on RHEL from an RPM

You can install Automation content navigator on Red Hat Enterprise Linux (RHEL) from an RPM.

Prerequisites

You registered your system with Red Hat Subscription Manager.

Procedure

Attach the Red Hat Ansible Automation Platform SKU.
```
$ subscription-manager attach --pool=<sku-pool-id>
```

Enable the repository for RHEL 8.

$ sudo subscription-manager repos --enable ansible-automation-platform-2.0-early-access-for-rhel-8-x86_64-rpms

Install Automation content navigator.
```
$ dnf install ansible-navigator
```

Verification

Verify your Automation content navigator installation:
```
$ ansible-navigator --help
```

You should see the help output describing the main functions of Automation content navigator.

You have now installed Automation content navigator and can use this tool to evaluate your playbooks, view your collections and inventories, and delve into the module-level documentation.

Chapter 3. Review Automation execution environments with Automation content navigator

As a content developer, you can review your automation execution environment with Automation content navigator and display the packages and collections included in the automation execution environments. Automation content navigator runs a playbook to extract and display the results.

3.1. Prerequisites

You have authenticated to the Red Hat registry if you need to access additional automation execution environments. See Red Hat Container Registry Authentication for details.

3.2. Reviewing Automation execution environments from Automation content navigator

You can review your Automation execution environments with the Automation content navigator text-based user interface.

Prerequisites

automation execution environments

Procedure

Review the automation execution environments included in your Automation content navigator configuration.
```
$ ansible-navigator images
```
Type the number of the automation execution environment you want to delve into for more details.
You can review the packages and versions of each installed automation execution environment as well as the Ansible version any included collections.
Optionally, you can pass in the automation execution environment you want to use. This becomes the primary and is the automation execution environment that Automation content navigator uses.
```
$ ansible-navigator images --eei  registry.example.com/example-enterprise-ee:latest
```

Verification

Review the automation execution environment output.

Chapter 4. Review inventories with Automation content navigator

As a content creator, you can review your Ansible inventory with Automation content navigator and interactively delve into the groups and hosts.

4.1. Reviewing inventory from Automation content navigator

You can review Ansible inventories with the Automation content navigator text-based user interface in interactive mode and delve into groups and hosts for more details.

Prerequisites

A valid inventory file or an inventory plugin.

Procedure

Start Automation content navigator
```
$ ansible-navigator
```
You can optionally type ansible-navigator inventory -i simple_inventory.yml from the command line to directly view the inventory.

Review the inventory.

 :inventory -i simple_inventory.yml

   TITLE            DESCRIPTION
0│Browse groups    Explore each inventory group and group members members
1│Browse hosts     Explore the inventory with a list of all hosts

Type 0 to brows the groups.

  NAME               TAXONOMY                      TYPE
0│general            all                           group
1│nodes              all                           group
2│ungrouped          all                           group

The TAXONOMY field details the heirarchy of groups the selected group or node belongs to.

Type the number corresponding to the group you want to delve into.

  NAME              TAXONOMY                        TYPE
0│node-0            all▸nodes                       host
1│node-1            all▸nodes                       host
2│node-2            all▸nodes                       host

Type the number corresponding to the host you want to delve into, or type :<number> for numbers greater than 9.
```
[node-1]
0│---
1│ansible_host: node-1.example.com
2│inventory_hostname: node-1
```

Verification

Review the inventory output.

  TITLE            DESCRIPTION
0│Browse groups   Explore each inventory group and group members members
1│Browse hosts    Explore the inventory with a list of all hosts

Additional resources

Chapter 5. Browse collections with Automation content navigator

As a content creator, you can browse your Ansible collections with Automation content navigator and interactively delve into each collection developed locally or within Automation execution environments.

5.1. Automation content navigator collections display

Automation content navigator displays information about your collections with the following details for each collection:

SHADOWED: Indicates that an additional copy of the collection is higher in the search order, and playbooks prefer that collection.
TYPE: Shows if the collection is contained within an automation execution environment or volume mounted on onto the automation execution environment as a bind_mount.
PATH: Reflects the collections location within the automation execution environment or local file system based on the collection TYPE field.

5.2. Browsing collections from Automation content navigator

You can browse Ansible collections with the Automation content navigator text-based user interface in interactive mode and delve into each collection. Automation content navigator shows collections within the current project directory and those available in the automation execution environments

Prerequisites

A locally accessible collection or installed automation execution environments.

Procedure

Start Automation content navigator
```
$ ansible-navigator
```
Browse the collection. Alternately, you can type ansible-navigator collections to directly browse the collections.
```
$ :collections
```
Type the number of the collection you want to explore.
```
:4
```

Type the number corresponding to the module you want to delve into.

ANSIBLE.UTILS.IP_ADDRESS: Test if something in an IP address
 0│---
 1│additional_information: {}
 2│collection_info:
 3│  authors:
 4│  - Ansible Community
 5│  dependencies: {}
 6│  description: Ansible Collection with utilities to ease the management, manipulation,
 7│    and validation of data within a playbook
 8│  documentation: null
 9│  homepage: null
10│  issues: null
11│  license: []
12│  license_file: LICENSE
13│  name: ansible.utils
14│  namespace: ansible
15│  path:/usr/share/ansible/collections/ansible_collections/ansible/utils/
16│  readme: README.md
<... output truncated...>

Optionally, jump to the documentation examples for this module.

:{{ examples }}

0│
1│
2│#### Simple examples
3│
4│- name: Check if 10.1.1.1 is a valid IP address
5│  ansible.builtin.set_fact:
6│    data: "{{ '10.1.1.1' is ansible.utils.ip_address }}"
7│
8│# TASK [Check if 10.1.1.1 is a valid IP address] *********************
9│# ok: [localhost] => {
10│#     "ansible_facts": {
11│#         "data": true
12│#     },
13│#     "changed": false
14│# }
15│

Optionally, open the example in your editor to copy it into a playbook.
```
:open
```

Verification

Browse the collection list.

Additional resources

5.3. Review documentation from Automation content navigator

You can review Ansible documentation for collections and plugins with the Automation content navigator text-based user interface in interactive mode. Automation content navigator shows collections within the current project directory and those available in the automation execution environments

Prerequisites

A locally accessible collection or installed automation execution environments.

Procedure

Start Automation content navigator
```
$ ansible-navigator
```

Review the module you are interested in. Alternately, you can type ansible-navigator doc to directly access the documentation.

:doc ansible.utils.ip_address

ANSIBLE.UTILS.IP_ADDRESS: Test if something in an IP address
 0│---
 1│additional_information: {}
 2│collection_info:
 3│  authors:
 4│  - Ansible Community
 5│  dependencies: {}
 6│  description: Ansible Collection with utilities to ease the management, manipulation,
 7│    and validation of data within a playbook
 8│  documentation: null
 9│  homepage: null
10│  issues: null
11│  license: []
12│  license_file: LICENSE
13│  name: ansible.utils
14│  namespace: ansible
15│  path:/usr/share/ansible/collections/ansible_collections/ansible/utils/
16│  readme: README.md
<... output truncated...>

Jump to the documentation examples for this module.

:{{ examples }}

0│
1│
2│#### Simple examples
3│
4│- name: Check if 10.1.1.1 is a valid IP address
5│  ansible.builtin.set_fact:
6│    data: "{{ '10.1.1.1' is ansible.utils.ip_address }}"
7│
8│# TASK [Check if 10.1.1.1 is a valid IP address] *********************
9│# ok: [localhost] => {
10│#     "ansible_facts": {
11│#         "data": true
12│#     },
13│#     "changed": false
14│# }
15│

Optionally, open the example in your editor to copy it into a playbook.
```
:open
```
See Section 8.2, “Automation content navigator general settings” for details on how to set up your editor.

Additional resources

Chapter 6. Execute Ansible playbooks with Automation content navigator

As a content creator, you can execute your Ansible playbooks with Automation content navigator and interactively delve into the results of each play and task to verify or troubleshoot the playbook. You can also execute your Ansible playbooks inside an execution environment and without an execution environment to compare and troubleshoot any problems.

6.1. Executing a playbook from Automation content navigator

You can run Ansible playbooks with the Automation content navigator text-based user interface to follow the execution of the tasks and delve into the results of each task.

Prerequisites

A playbook.
A valid inventory file if not using localhost or an inventory plugin.

Procedure

Start Automation content navigator
```
$ ansible-navigator
```
Run the playbook. You can optionally type ansible-navigator run simple-playbook.yml -i inventory.yml to directly run the playbook.
```
$ :run
```

Verify or add the inventory and any other command line parameters.

INVENTORY OR PLAYBOOK NOT FOUND, PLEASE CONFIRM THE FOLLOWING
─────────────────────────────────────────────────────────────────────────
   Path to playbook: /home/ansible-navigator_demo/simple_playbook.yml
   Inventory source: /home/ansible-navigator-demo/inventory.yml
  Additional command line parameters: Please provide a value (optional)
──────────────────────────────────────────────────────────────────────────
                                                           Submit Cancel

Tab to Submit and hit Enter. You should see the tasks executing.
Type the number next to a play to step into the play results, or type :<number> for numbers above 9.
Notice failed tasks show up in red if you have colors enabled for Automation content navigator.
Type the number next to a task to review the task results, or type :<number> for numbers above 9.

Optionally, type :doc bring up the documentation for the module or plugin used in the task to aid in troubleshooting.

ANSIBLE.BUILTIN.PACKAGE_FACTS (MODULE)
  0│---
  1│doc:
  2│  author:
  3│  - Matthew Jones (@matburt)
  4│  - Brian Coca (@bcoca)
  5│  - Adam Miller (@maxamillion)
  6│  collection: ansible.builtin
  7│  description:
  8│  - Return information about installed packages as facts.
<... output omitted ...>
 11│  module: package_facts
 12│  notes:
 13│  - Supports C(check_mode).
 14│  options:
 15│    manager:
 16│      choices:
 17│      - auto
 18│      - rpm
 19│      - apt
 20│      - portage
 21│      - pkg
 22│      - pacman

<... output truncated ...>

Additional resources

6.2. Reviewing playbook results with an Automation content navigator artifact file

Automation content navigator saves the results of the playbook run in a JSON artifact file. You can use this file to share the playbook results with someone else, save it for security or compliance reasons, or review and troubleshoot later. You only need the artifact file to review the playbook run. You do not need access to the playbook itself or inventory access.

Prerequisites

A Automation content navigator artifact JSON file from a playbook run.

Procedure

Start Automation content navigator with the artifact file
```
$ ansible-navigator replay simple_playbook_artifact.json
```
1. Review the playbook results that match when the playbook ran.

You can now type the number next to the plays and tasks to step into each to review the results, as you would after executing the playbook.

Additional resources

Chapter 7. Review your Ansible configuration with Automation content navigator

As a content creator, you can review your Ansible configuration with Automation content navigator and interactively delve into settings.

7.1. Reviewing your Ansible configuration from Automation content navigator

You can review your Ansible configuration with the Automation content navigator text-based user interface in interactive mode and delve into the settings. Automation content navigator pulls in the results from an accessible Ansible configuration file, or returns the defaults if no configuration file is present.

Procedure

Start Automation content navigator
```
$ ansible-navigator
```
You can optionally type ansible-navigator config from the command line to directly access the Ansible configuration settings.
Review the Ansible configuration.
```
 :config
```
Some values reflect settings from within the automation execution environments needed for the automation execution environments to function. These display as non-default settings you cannot set in your Ansible configuration file.

Type the number corresponding to the setting you want to delve into, or type :<number> for numbers greater than 9.

ANSIBLE COW ACCEPTLIST (current: ['bud-frogs', 'bunny', 'cheese']) (default:
 0│---
 1│current:
 2│- bud-frogs
 3│- bunny
 4│- cheese
 5│default:
 6│- bud-frogs
 7│- bunny
 8│- cheese
 9│- daemon

The output shows the current setting as well as the default. Note the source in this example is env since the setting comes from the automation execution environments.

Verification

Review the configuration output.

Additional resources

Chapter 8. Automation content navigator configuration settings

As a content creator, you can configure Automation content navigator to suit your development environment.

8.1. About Automation content navigator settings

You can alter the default Automation content navigator settings through:

The command line
Within a settings file
As an environment variable

Automation content navigator checks for a settings file in the following order and uses the first match:

ANSIBLE_NAVIGATOR_CONFIG - The settings file path environment variable if set.
./ansible-navigator.<ext> - The settings file within the current project directory, with no dot in the file name.
~/.ansible-navigator.<ext> - Your home directory, with a dot in the file name.

Consider the following when you create an Automation content navigator settings file:

The settings file can be in JSON or YAML format.
For settings in JSON format, the extension must be .json.
For settings in YAML format, the extension must be .yml or .yaml.
The project and home directories can only contain one settings file each.
If Automation content navigator finds more than one settings file in either directory, it results in an error.

You can copy the example settings file below into one of those paths to start your ansible-navigator settings file.

    ---
    ansible-navigator:
    #   ansible:
    #     config: /tmp/ansible.cfg
    #     cmdline: "--forks 15"
    #     inventories:
    #     - /tmp/test_inventory.yml
    #     playbook: /tmp/test_playbook.yml
    #   ansible-runner:
    #     artifact-dir: /tmp/test1
    #     rotate-artifacts-count: 10
    #     timeout: 300
    #   app: run
    #   collection-doc-cache-path: /tmp/cache.db
    #   color:
    #     enable: False
    #     osc4: False
    #   editor:
    #     command: vim_from_setting
    #     console: False
    #   documentation:
    #     plugin:
    #       name: shell
    #       type: become
    #   execution-environment:
    #     container-engine: podman
    #     enabled: False
    #     environment-variables:
    #       pass:
    #         - ONE
    #         - TWO
    #         - THREE
    #       set:
    #         KEY1: VALUE1
    #         KEY2: VALUE2
    #         KEY3: VALUE3
    #     image: test_image:latest
    #     pull-policy: never
    #     volume-mounts:
    #     - src: "/test1"
    #       dest: "/test1"
    #       label: "Z"
    #   help-config: True
    #   help-doc: True
    #   help-inventory: True
    #   help-playbook: False
    #   inventory-columns:
    #     - ansible_network_os
    #     - ansible_network_cli_ssh_type
    #     - ansible_connection
      logging:
    #     append: False
        level: critical
    #     file: /tmp/log.txt
    #   mode: stdout
    #   playbook-artifact:
    #     enable: True
    #     replay: /tmp/test_artifact.json
    #     save-as: /tmp/test_artifact.json

8.2. Automation content navigator general settings

The following table describes each general parameter and setting options for Automation content navigator.

Table 8.1. Automation content navigator general parameters settings table
Parameter	Description	Setting options
ansible-runner-artifact-dir	The directory path to store artifacts generated by ansible-runner.	Default: No default value set CLI: `--rad` or `--ansible-runner-artifact-dir` ENV: `ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_ARTIFACT_DIR` Settings file: ansible-navigator: ansible-runner: artifact-dir:
ansible-runner-rotate-artifacts-count	Keep ansible-runner artifact directories, for last n runs. If set to 0, artifact directories are not deleted.	Default: No default value set CLI: `--rac` or `--ansible-runner-rotate-artifacts-count` ENV: `ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_ROTATE_ARTIFACTS_COUNT` Settings file: ansible-navigator: ansible-runner: rotate-artifacts-count:
ansible-runner-timeout	The timeout value after which `ansible-runner` force stops the execution.	Default: No default value set CLI: `--rt` or `--ansible-runner-timeout` ENV: `ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_TIMEOUT` Settings file: ansible-navigator: ansible-runner: timeout:
app	Entry point for Automation content navigator.	Choices: `collections`, `config`, `doc`, `images`, `inventory`, `replay`, `run` or `welcome` Default: `welcome` CLI example: `ansible-navigator collections` ENV: `ANSIBLE_NAVIGATOR_APP` Settings file: ansible-navigator: app:
cmdline	Extra parameters passed to the corresponding command.	Default: No default value CLI: positional ENV: `ANSIBLE_NAVIGATOR_CMDLINE` Settings file: ansible-navigator: ansible: cmdline:
collection-doc-cache-path	The path to the collection doc cache.	Default: `$HOME/.cache/ansible-navigator/collection_doc_cache.db` CLI: `--cdcp` or `--collection-doc-cache-path` ENV: `ANSIBLE_NAVIGATOR_COLLECTION_DOC_CACHE_PATH` Settings file: ansible-navigator: collection-doc-cache-path:
container-engine	Specify the container engine (`auto`=`podman` then `docker`).	Choices: `auto`, `podman` or `docker` Default: `auto` CLI: `--ce` or `--container-engine` ENV: `ANSIBLE_NAVIGATOR_CONTAINER_ENGINE` Settings file: ansible-navigator: execution-environment: container-engine:
display-color	Enable the use of color in the display.	Choices: `True` or `False` Default: `True` CLI: `--dc` or `--display-color` ENV: `NO_COLOR` Settings file: ansible-navigator: color: enable:
editor-command	Specify the editor used by Automation content navigator	Default:* vi +{line_number} {filename} CLI: `--ecmd` or `--editor-command` ENV: `ANSIBLE_NAVIGATOR_EDITOR_COMMAND` Settings file: ansible-navigator: editor: command:
editor-console	Specify if the editor is console based.	Choices: `True` or `False` Default: `True` CLI: `--econ` or `--editor-console` ENV: `ANSIBLE_NAVIGATOR_EDITOR_CONSOLE` Settings file: ansible-navigator: editor: console:
execution-environment	Enable or disable the use of an automation execution environment.	Choices: `True` or `False` Default: `True` CLI: `--ee` or `--execution-environment` ENV:* `ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT` Settings file: ansible-navigator: execution-environment: enabled:
execution-environment-image	Specify the name of the automation execution environment image.	Default: `quay.io/ansible/ansible-runner:devel` CLI: `--eei` or `--execution-environment-image` ENV: `ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_IMAGE` Settings file: ansible-navigator: execution-environment: image:
execution-environment-volume-mounts	Specify volume to be bind mounted within an automation execution environment (`--eev /home/user/test:/home/user/test:Z`)	Default: No default value set CLI: `--eev` or `--execution-environment-volume-mounts` ENV: `ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_VOLUME_MOUNTS` Settings file: ansible-navigator: execution-environment: volume-mounts:
log-append	Specify if log messages should be appended to an existing log file, otherwise a new log file is created per session.	Choices: `True` or `False` Default: True CLI: `--la` or `--log-append` ENV: `ANSIBLE_NAVIGATOR_LOG_APPEND` Settings file: ansible-navigator: logging: append:
log-file	Specify the full path for the Automation content navigator log file.	Default: `$PWD/ansible-navigator.log` CLI: `--lf` or `--log-file` ENV: `ANSIBLE_NAVIGATOR_LOG_FILE` Settings file: ansible-navigator: logging: file:
log-level	Specify the Automation content navigator log level.	Choices: `debug`, `info`, `warning`, `error` or `critical` Default: `warning` CLI: `--ll` or `--log-level` ENV: `ANSIBLE_NAVIGATOR_LOG_LEVEL` Settings file: ansible-navigator: logging: level:
mode	Specify the user-interface mode.	Choices: `stdout` or `interactive` Default: `interactive` CLI: `-m` or `--mode` ENV: `ANSIBLE_NAVIGATOR_MODE` Settings file: ansible-navigator: mode:
osc4	Enable or disable terminal color changing support with OSC 4.	Choices: `True` or `False` Default: `True` CLI: `--osc4` or `--osc4` ENV: `ANSIBLE_NAVIGATOR_OSC4` Settings file: ansible-navigator: color: osc4:
pass-environment-variable	Specify an exiting environment variable to be passed through to and set within the automation execution environment (`--penv MY_VAR`)	Default: No default value set CLI: `--penv` or `--pass-environment-variable` ENV: `ANSIBLE_NAVIGATOR_PASS_ENVIRONMENT_VARIABLES` Settings file: ansible-navigator: execution-environment: environment-variables: pass:
pull-policy	Specify the image pull policy. `always` - Always pull the image `missing` - Pull if not locally available `never` - Never pull the image `tag` - If the image tag is `latest` always pull the image, otherwise pull if not locally available	Choices: `always`, `missing`, `never`, or `tag` Default: `tag` CLI: `--pp` or `--pull-policy` ENV: `ANSIBLE_NAVIGATOR_PULL_POLICY` Settings file: ansible-navigator: execution-environment: pull-policy:
set-environment-variable	Specify an environment variable and a value to be set within the automation execution environment `(--senv MY_VAR=42`)	Default: No default value set CLI: `--senv` or `--set-environment-variable` ENV: `ANSIBLE_NAVIGATOR_SET_ENVIRONMENT_VARIABLES` Settings file: ansible-navigator: execution-environment: environment-variables: set:

8.3. Automation content navigator `config` subcommand settings

The following table describes each parameter and setting options for the Automation content navigator config subcommand.

Table 8.2. Automation content navigator config subcommand parameters settings table
Parameter	Description	Setting options
config	Specify the path to the Ansible configuration file.	Default: No default value set CLI: `-c` or `--config` ENV: `ANSIBLE_CONFIG` Settings file: ansible-navigator: ansible: config:
help-config	Help options for the `ansible-config` command in `stdout` mode.	Choices:* `True` or `False` Default: `False` CLI: `--hc` or `--help-config` ENV: `ANSIBLE_NAVIGATOR_HELP_CONFIG` Settings file: ansible-navigator: help-config:

8.4. Automation content navigator `doc` subcommand settings

The following table describes each parameter and setting options for the Automation content navigator doc subcommand.

Table 8.3. Automation content navigator doc subcommand parameters settings table
Parameter	Description	Setting options
help-doc	Help options for the `ansible-doc` command in `stdout` mode.	Choices: `True` or `False` Default: `False` CLI: `--hd` or `--help-doc` ENV: `ANSIBLE_NAVIGATOR_HELP_DOC` Settings file: ansible-navigator: help-doc:
plugin-name	Specify the plugin name.	Default: No default value set CLI: positional ENV: `ANSIBLE_NAVIGATOR_PLUGIN_NAME` Settings file: ansible-navigator: documentation: plugin: name:
plugin-type	Specify the plugin type.	Choices: `become`, `cache`, `callback`, `cliconf`, `connection`, `httpapi`, `inventory`, `lookup`, `module`, `netconf`, `shell`, `strategy`, or `vars` Default: `module` CLI: `-t` or `----type` ENV: `ANSIBLE_NAVIGATOR_PLUGIN_TYPE` Settings file: ansible-navigator: documentation: plugin: type:

8.5. Automation content navigator `inventory` subcommand settings

The following table describes each parameter and setting options for the Automation content navigator inventory subcommand.

Table 8.4. Automation content navigator inventory subcommand parameters settings table
Parameter	Description	Setting options
help-inventory	Help options for the `ansible-inventory` command in `stdout` mode.	Choices: `True` or `False` Default: `False` CLI: `--hi` or `--help-inventory` ENV: `ANSIBLE_NAVIGATOR_INVENTORY_DOC` Settings file: ansible-navigator: help-inventory:
inventory	Specify an inventory file path or comma separated host list.	Default: no default value set CLI: `--i` or `--inventory` ENV: `ANSIBLE_NAVIGATOR_INVENTORIES` Settings file: ansible-navigator: inventories:
inventory-column	Specify a host attribute to show in the inventory view.	Default: No default value set CLI: `--ic` or `--inventory-column` ENV:* `ANSIBLE_NAVIGATOR_INVENTORY_COLUMNS`Settings file: ansible-navigator: inventory-columns:

8.6. Automation content navigator `replay` subcommand settings

The following table describes each parameter and setting options for the Automation content navigator replay subcommand.

Table 8.5. Automation content navigator replay subcommand parameters settings table
Parameter	Description	Setting options
playbook-artifact-replay	Specify the path for the playbook artifact to replay.	Default: No default value set CLI: positional ENV: `ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_REPLAY` Settings file: ansible-navigator: playbook-artifact: replay:

8.7. Automation content navigator `run` subcommand settings

The following table describes each parameter and setting options for the Automation content navigator run subcommand.

Table 8.6. Automation content navigator run subcommand parameters settings table
Parameter	Description	Setting options
playbook-artifact-replay	Specify the path for the playbook artifact to replay.	Default: No default value set CLI: positional ENV: `ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_REPLAY` Settings file: ansible-navigator: playbook-artifact: replay:
help-playbook	Help options for the `ansible-playbook` command in `stdout` mode.	Choices: `True` or `False` Default: `False` CLI: `--hp` or `--help-playbook` ENV: `ANSIBLE_NAVIGATOR_HELP_PLAYBOOK` Settings file: ansible-navigator: help-playbook:
inventory	Specify an inventory file path or comma separated host list.	Default: no default value set CLI: `--i` or `--inventory` ENV: `ANSIBLE_NAVIGATOR_INVENTORIES` Settings file: ansible-navigator: inventories:
inventory-column	Specify a host attribute to show in the inventory view.	Default: No default value set CLI: `--ic` or `--inventory-column` ENV:* `ANSIBLE_NAVIGATOR_INVENTORY_COLUMNS`Settings file: ansible-navigator: inventory-columns:
playbook	Specify the playbook name.	Default: No default value set CLI: positional ENV: `ANSIBLE_NAVIGATOR_PLAYBOOK` Settings file:* ansible-navigator: ansible: playbook:
playbook-artifact-enable	Enable or disable the creation of artifacts for completed playbooks. Note: not compatible with `--mode stdout` when playbooks require user input.	Choices: `True` or `False` Default: `True` CLI: `--pae` or `--playbook-artifact-enable`ENV: `ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_ENABLE`Settings file: ansible-navigator: playbook-artifact: enable:
playbook-artifact-save-as	Specify the name for artifacts created from completed playbooks.	Default: `{playbook_dir}/{playbook_name}-artifact-{ts_utc}.json` CLI: `--pas` or `--playbook-artifact-save-as` ENV: `ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_SAVE_AS` Settings file: ansible-navigator: playbook-artifact: save-as:

Chapter 9. Troubleshoot Ansible content with Automation content navigator

As a content creator, you can troubleshoot your Ansible content (collections, automation execution environments, and playbooks) with Automation content navigator and interactively troubleshoot the playbook. You can also compare results inside or outside an automation execution environment and troubleshoot any problems.

9.1. Reviewing playbook results with an Automation content navigator artifact file

Automation content navigator saves the results of the playbook run in a JSON artifact file. You can use this file to share the playbook results with someone else, save it for security or compliance reasons, or review and troubleshoot later. You only need the artifact file to review the playbook run. You do not need access to the playbook itself or inventory access.

Prerequisites

A Automation content navigator artifact JSON file from a playbook run.

Procedure

Start Automation content navigator with the artifact file
```
$ ansible-navigator replay simple_playbook_artifact.json
```
1. Review the playbook results that match when the playbook ran.

You can now type the number next to the plays and tasks to step into each to review the results, as you would after executing the playbook.

Additional resources

9.2. Automation content navigator Frequently asked questions

Use the following Automation content navigator FAQ to help you troubleshoot problems in your environment.

Where should the ansible.cfg file go when using an automation execution environment?

The easiest place to have the ansible.cfg is in the project directory adjacent to the playbook. The playbook directory is automatically mounted in the execution enviroment and the ansible.cfg file will be found. If the ansible.cfg file is in another directory, the ANSIBLE_CONFIG variable needs to be set and the directory specified as a custom volume mount. (See Automation content navigator settings for execution-environment-volume-mounts)

Where should the ansible.cfg file go when not using an automation execution environment Ansible looks for the ansible.cfg in the typical locations when not using an automation execution environment. See Ansible configuration settings for details.

Where should Ansible collections be placed when using an automation execution environment?

The easiest place to have Ansible collections is in the project directory, in a playbook adjacent collections directory (for example, ansible-galaxy collections install ansible.utils -p ./collections). The playbook directory is automatically mounted in the automation execution environment and Automation content navigator finds the collections there. Another option is to build the collections into an automation execution environment using Ansible Builder. This helps content creators author playbooks that are production ready, since automation controller supports playbook adjacent collection directories. If the collections are in another directory, set the ANSIBLE_COLLECTIONS_PATHS variable and configure a custom volume mount for the directory. (See Section 8.2, “Automation content navigator general settings” for execution-environment-volume-mounts).

Where should ansible collections be placed when not using an automation execution environment?

When not using an automation execution environment, Ansible looks in the default locations for collections. See the Ansible Collections User Guide.

Why does the playbook hang when vars_prompt or pause/prompt is used?

By default, Automation content navigator runs the playbook in the same manner that automation controller runs the playbook. This was done to help content creators author playbooks that would be ready for production. If the use of vars_prompt or pause\prompt can not be avoided, disabling playbook-artifact creation causes Automation content navigator to run the playbook in a manner that is compatible with ansible-playbook and allows for user interaction.

Why does Automation content navigator change the terminal colors or look terrible?

Automation content navigator queries the terminal for its OSC4 compatibility. OSC4, 10, 11, 104, 110, 111 indicate the terminal supports color changing and reverting. It is possible that the terminal is misrepresenting its ability. OSC4 detection can be disabled by setting --osc4 false. (See Section 8.2, “Automation content navigator general settings” for how to handle this with an environment variable or in the settings file).

How can I change the colors used by Automation content navigator?

Use --osc4 false to force Automation content navigator to use the terminal defined colors. (See Section 8.2, “Automation content navigator general settings” for how to handle this with an environment variable or in the settings file).

What’s with all these site-artifact-2021-06-02T16:02:33.911259+00:00.json files in the playbook directory?

Automation content navigator creates a playbook artifact for every playbook run. These can be helpful for reviewing the outcome of automation after it is complete, sharing and troubleshooting with a colleague, or keeping for compliance or change-control purposes. The playbook artifact file contains the detailed information about every play and task, as well as the stdout from the playbook run. UYou can review playbook artifacts with ansible-navigator replay <filename> or :replay <filename> while in an Automation content navigator session. All playbook artifacts can be reviewed with both --mode stdout and --mode interactive, depending on the desired view. You can disable playbook artifacts writing and the default file naming convention. (See Section 8.2, “Automation content navigator general settings” for how to handle this with an environment variable or in the settings file).

Why does vi open when I use :open?

Automation content navigator opens anything showing in the terminal in the default editor. The default is set to either vi +{line_number} {filename} or the current value of the EDITOR environment variable. Related to this is the editor-console setting which indicates if the editor is console/terminal based. Here are examples of alternate settings that may be useful:

# emacs
ansible-navigator:
  editor:
    command: emacs -nw +{line_number} {filename}
    console: true

# vscode
ansible-navigator:
  editor:
    command: code -g {filename}:{line_number}
    console: false

#pycharm
ansible-navigator:
  editor:
    command: charm --line {line_number} {filename}
    console: false

What is the order in which configuration settings are applied?

The Automation content navigator configuration system pulls in settings from various sources and applies them hierarchically in the following order (where the last applied changes are the most prevalent):

Default internal values
Values from a settings file
Values from environment variables
Flags and arguments specified on the command line
While issuing : commands within the text-based user interface

Something didn’t work, how can I troubleshoot it?

Automation content navigator has reasonable logging messages. You can enable debug logging with --log-level debug. If you think you might have found a bug, please log an issue and include the details from the log file.

Using Ansible Navigator in the Ansible Creator Workflow.

Chapter 1. Ansible content navigator

1.1. About Automation content navigator

1.1.1. Why use Automation content navigator?

1.2. Automation content navigator modes

1.2.1. stdout mode

1.2.2. Text-based user interface mode

1.3. Automation content navigator commands

1.4. Automation content navigator command comparison

Chapter 2. Installing Automation content navigator on RHEL

2.1. Prerequisites

2.2. Installing Automation content navigator on RHEL from an RPM

Chapter 3. Review Automation execution environments with Automation content navigator

3.1. Prerequisites

3.2. Reviewing Automation execution environments from Automation content navigator

Chapter 4. Review inventories with Automation content navigator

4.1. Reviewing inventory from Automation content navigator

Chapter 5. Browse collections with Automation content navigator

5.1. Automation content navigator collections display

5.2. Browsing collections from Automation content navigator

5.3. Review documentation from Automation content navigator

Chapter 6. Execute Ansible playbooks with Automation content navigator

6.1. Executing a playbook from Automation content navigator

6.2. Reviewing playbook results with an Automation content navigator artifact file

Chapter 7. Review your Ansible configuration with Automation content navigator

7.1. Reviewing your Ansible configuration from Automation content navigator

Chapter 8. Automation content navigator configuration settings

8.1. About Automation content navigator settings

8.2. Automation content navigator general settings

8.3. Automation content navigator config subcommand settings

8.4. Automation content navigator doc subcommand settings

8.5. Automation content navigator inventory subcommand settings

8.6. Automation content navigator replay subcommand settings

8.7. Automation content navigator run subcommand settings

Chapter 9. Troubleshoot Ansible content with Automation content navigator

9.1. Reviewing playbook results with an Automation content navigator artifact file

9.2. Automation content navigator Frequently asked questions

Legal Notice

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

8.3. Automation content navigator `config` subcommand settings

8.4. Automation content navigator `doc` subcommand settings

8.5. Automation content navigator `inventory` subcommand settings

8.6. Automation content navigator `replay` subcommand settings

8.7. Automation content navigator `run` subcommand settings