Chapter 9. Troubleshooting Ansible content with automation content navigator
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. USD ansible-navigator replay simple_playbook_artifact.json Review the playbook results that match when the playbook ran. You can now type the number to the plays and tasks to step into each to review the results, as you would after executing the playbook. Additional resources ansible-playbook Ansible playbooks 9.2. Frequently asked questions about automation content navigator 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 file is in the project directory to the playbook. The playbook directory is automatically mounted in the automation execution environment and automation content navigator finds the ansible.cfg file there. If the ansible.cfg file is in another directory, set the ANSIBLE_CONFIG variable, and specify the directory 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 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 Using Ansible collections 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 helps content creators author playbooks that are production ready. If you cannot avoid the use of vars_prompt or pause\prompt , 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. You can disable OSC4 detection by setting --osc4 false . (See 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 Automation content navigator general settings for how to handle this with an environment variable or in the settings file). What is 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 has the detailed information about every play and task, and the stdout from the playbook run. You can review playbook artifacts with ansible-navigator replay <filename> or :replay <filename> while in an automation content navigator session. You can review all playbook artifacts with both --mode stdout and --mode interactive , depending on the required view. You can disable playbook artifacts writing and the default file naming convention. (See 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 or terminal based. Here are examples of alternate settings that might 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 did not 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, log an issue and include the details from the log file.
ansible-navigator replay simple_playbook_artifact.json 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