Ansible Navigator Creator Guide

Red Hat Ansible Automation Platform 2.0-ea

Using Ansible Navigator in the Ansible Creator Workflow.

Red Hat Customer Content Services

Abstract

Providing Feedback:
If you have a suggestion to improve this documentation, or find an error, create an issue at http://issues.redhat.com. Select the Ansible Automation Platform project and use the Documentationcomponent.

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.
navigator stdout

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.

navigator welcome

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

CommandDescriptionCLI 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 commandAnsible 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

  1. Attach the Red Hat Ansible Automation Platform SKU.

    $ subscription-manager attach --pool=<sku-pool-id>
  2. Enable the repository for RHEL 8.

    $ sudo subscription-manager repos --enable ansible-automation-platform-2.0-early-access-for-rhel-8-x86_64-rpms
  3. 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

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

  1. Review the automation execution environments included in your Automation content navigator configuration.

    $ ansible-navigator images
    navigator images list
  2. Type the number of the automation execution environment you want to delve into for more details.

    navigator image details

    You can review the packages and versions of each installed automation execution environment as well as the Ansible version any included collections.

  3. 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.

    navigator image details

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

  1. 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.

  2. 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
  3. 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.

  4. 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
  5. 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

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.
navigator collections shadow

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

  1. Start Automation content navigator

    $ ansible-navigator
  2. Browse the collection. Alternately, you can type ansible-navigator collections to directly browse the collections.

    $ :collections
    navigator collection list
  3. Type the number of the collection you want to explore.

    :4
    navigator plugin list
  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...>
  5. 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│
  6. Optionally, open the example in your editor to copy it into a playbook.

    :open
    navigator vscode example

Verification

  • Browse the collection list.

    navigator collection list

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

  1. Start Automation content navigator

    $ ansible-navigator
  2. 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...>
  3. 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│
  4. Optionally, open the example in your editor to copy it into a playbook.

    :open
    navigator vscode example

    See Section 8.2, “Automation content navigator general settings” for details on how to set up your editor.

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

  1. Start Automation content navigator

    $ ansible-navigator
  2. Run the playbook. You can optionally type ansible-navigator run simple-playbook.yml -i inventory.yml to directly run the playbook.

    $ :run
  3. 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
  4. Tab to Submit and hit Enter. You should see the tasks executing.

    navigator play list
  5. Type the number next to a play to step into the play results, or type :<number> for numbers above 9.

    navigator task list

    Notice failed tasks show up in red if you have colors enabled for Automation content navigator.

  6. Type the number next to a task to review the task results, or type :<number> for numbers above 9.

    navigator task output failed
  7. 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 ...>

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.

      navigator artifact replay

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.

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

  1. Start Automation content navigator

    $ ansible-navigator

    You can optionally type ansible-navigator config from the command line to directly access the Ansible configuration settings.

  2. Review the Ansible configuration.

     :config
    navigator ansible 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.

  3. 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.

    navigator ansible config

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

ParameterDescriptionSetting 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

ParameterDescriptionSetting 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

ParameterDescriptionSetting 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

ParameterDescriptionSetting 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_COLUMNSSettings 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

ParameterDescriptionSetting 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

ParameterDescriptionSetting 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_COLUMNSSettings 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-enableENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_ENABLESettings 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.

      navigator artifact replay

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.

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):

  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. 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.

Legal Notice

Copyright © 2021 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.