Ce contenu n'est pas disponible dans la langue sélectionnée.
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
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 next to the playbook. The playbook directory is automatically mounted in the execution environment and theansible.cfg
file will be found. If theansible.cfg
file is in another directory, theANSIBLE_CONFIG
variable needs to be set and the directory specified as a custom volume mount. (See Automation content navigator general settings forexecution-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 by 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 theANSIBLE_COLLECTIONS_PATHS
variable and configure a custom volume mount for the directory. (See Automation content navigator general settings forexecution-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
orpause/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
orpause\prompt
can not be avoided, disablingplaybook-artifact
creation causes Automation content navigator to run the playbook in a manner that is compatible withansible-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 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’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 information about every play and task, and the
stdout
from the playbook run. You can review playbook artifacts withansible-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 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 theEDITOR
environment variable. Related to this is theeditor-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.