Chapter 9. Troubleshooting 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.

      Playbook results

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 environment 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 Section 8.2, “Automation content navigator general 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. (See Ansible Builder Guide for more information on 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.