Chapter 9: Troubleshooting Ansible

Ansible is beautifully simple, yet incredibly powerful. The simplicity of Ansible means that its operation is easy to understand and follow. However, even with the simplest and most user-friendly of systems, things do go wrong from time to time—perhaps as we are learning to write our own code (playbooks, roles, modules, or otherwise) and need to debug it, or, more rarely, when we might have found a bug in a released version of a collection or ansible-core.

Being able to understand and follow the operation of Ansible is critically important when debugging unexpected behavior, wherever it may arise. Ansible provides a number of options and tools to help you troubleshoot the operation of its core components, as well as your own playbook code. We will explore these in detail in this chapter, with the goal of empowering you to troubleshoot your own Ansible work with confidence.

Specifically, in this chapter, we will look at the following...

Technical requirements

To follow the examples presented in this chapter, you will need a Linux machine running Ansible 4.3 or a newer version. Almost any flavor of Linux should do—for those interested in specifics, all the code presented in this chapter was tested on Ubuntu Server 20.04 Long-Term Support (LTS) unless stated otherwise, and on Ansible 4.3. The example code that accompanies this chapter can be downloaded from GitHub at this link: https://github.com/PacktPublishing/Mastering-Ansible-Fourth-Edition/tree/main/Chapter09.

Check out the following video to see the Code in Action: https://bit.ly/2Xx46Ym

Playbook logging and verbosity

Increasing the verbosity of Ansible output can solve many problems. From invalid module arguments to incorrect connection commands, increased verbosity can be critical in pinpointing the source of an error. Playbook logging and verbosity were briefly discussed in Chapter 3, Protecting Your Secrets with Ansible, with regard to protecting secret values while executing playbooks. This section will cover verbosity and logging in further detail.

Verbosity

When executing playbooks with ansible-playbook, the output is displayed on standard output (stdout). With the default level of verbosity, very little information is displayed. As a play is executed, ansible-playbook will print a play header with the name of the play. Then, for each task, a task header is printed with the name of the task. As each host executes the task, the name of the host is displayed along with the task state, which...

Variable introspection

A common set of problems that are encountered when developing Ansible playbooks is the improper use, or invalid assumption, of the value of variables. This is particularly common when registering the results of one task in a variable, and later using that variable in a task or template. If the desired element of the result is not accessed properly, the end result will be unexpected, or perhaps even harmful.

To troubleshoot improper variable usage, an inspection of the variable value is the key. The easiest way to inspect a variable's value is with the ansible.builtin.debug module. The ansible.builtin.debug module allows the display of freeform text on screen, and as with other tasks, the arguments to the module can take advantage of the Jinja2 template syntax as well. Let's demonstrate this usage by creating a sample play that executes a task, registers the result, and then shows the result in an ansible.builtin.debug statement using...

Debugging code execution

Sometimes, the logging and inspection of variable data are not enough to troubleshoot a problem. When this happens, it can be necessary to interactively debug the playbook, or to dig deeper into the internals of Ansible code. There are two main sets of Ansible code: code that runs locally on the Ansible host, and module code that runs remotely on the target host.

Playbook debugging

Playbooks can be interactively debugged by using an execution strategy that was introduced in Ansible 2.1, the debug strategy. If a play uses this strategy when an error state is encountered, an interactive debugging session starts. This interactive session can be used to display variable data, display task arguments, update task arguments, update variables, redo task execution, continue execution, or exit the debugger.

Let's demonstrate this with a play that has a successful task, followed by a task with an error, followed by a final successful...

Summary

Ansible is a piece of software, and software breaks; it's not a matter of if, but when. Invalid input, improper assumptions, and unexpected environments are all things that can lead to a frustrating situation when tasks and plays are not performing as expected. Introspection and debugging are troubleshooting techniques that can quickly turn frustration into elation when a root cause is discovered.

In this chapter, we learned about how to get Ansible to log its actions to a file, and how to change the verbosity level of Ansible's output. We then learned how to inspect variables to ensure their values are in line with your expectations before we moved on to debugging Ansible code in detail. Furthermore, we walked through the process of inserting breakpoints into core Ansible code and executed both local and remote Python debugging sessions using standard Python tools.

In the next chapter, we will learn how to extend the functionality of Ansible...

Questions

1. What level of verbosity would you need to launch Ansible with to see details such as connection attempts?

   a) Level 3 or above

   b) Level 2 or above

   c) Level 1 or above

   d) Level 4

2. Why should you be careful with verbosity levels above level one if you are using sensitive data in your playbook?

   a) Higher verbosity levels don't support the use of vaults.

   b) Higher verbosity levels may log sensitive data to the console and/or log file.

   c) Higher verbosity levels will print SSH passwords.

3. Ansible can be centrally configured to log its output to a file by:

   a) Using the ANSIBLE_LOG_PATH environment variable

   b) Using the log_path directive in ansible.cfg

   c) Redirecting the output of each playbook run to a file

   d) All of these

4. The name of the module used for variable introspection is:

   a) ansible.builtin.analyze

   b) ansible.builtin.introspect

   c) ansible.builtin.debug

   d) ansible.builtin.print

5. When referencing subelements in Ansible variables, which syntax is the safest to...