After completing this section, you should be able to troubleshoot generic issues with a new playbook and repair them.

By default, Ansible is not configured to log its output to any log file. It provides a built-in logging infrastructure that can be configured through the log_path parameter in the default section of the ansible.cfg configuration file, or through the $ANSIBLE_LOG_PATH environment variable. If any or both are configured, Ansible stores output from both the ansible and ansible-playbook commands in the log file configured, either through the ansible.cfg configuration file or the $ANSIBLE_LOG_PATH environment variable.

If you configure Ansible to write log files to /var/log, then Red Hat recommends that you configure logrotate to manage the Ansible log files.

The debug module provides insight into what is happening in the play. This module can display the value for a certain variable at a certain point in the play. This feature is key to debugging tasks that use variables to communicate with each other (for example, using the output of a task as the input to the following one).

The following examples use the msg and var settings inside of debug tasks. The first example displays the value at run time of the ansible_facts['memfree_mb'] fact as part of a message printed to the output of ansible-playbook. The second example displays the value of the output variable.

- name: Display free memory
  debug:
    msg: "Free memory for this system is {{ ansible_facts['memfree_mb'] }}"

- name: Display the "output" variable
  debug:
    var: output
    verbosity: 2

There are several issues than can occur during a playbook run, mainly related to the syntax of either the playbook or any of the templates it uses, or due to connectivity issues with the managed hosts (for example, an error in the host name of the managed host in the inventory file). Those errors are issued by the ansible-playbook command at execution time.

Earlier in this course, you learned about the --syntax-check option, which checks the YAML syntax for the playbook. It is a good practice to run a syntax check on your playbook before using it or if you are having problems with it.

[student@demo ~]$ ansible-playbook play.yml --syntax-check

You can also use the --step option to step through a playbook one task at a time. The ansible-playbook --step command interactively prompts for confirmation that you want each task to run.

[student@demo ~]$ ansible-playbook play.yml --step

The --start-at-task option allows you to start execution of a playbook from a specific task. It takes as an argument the name of the task at which to start.

[student@demo ~]$ ansible-playbook play.yml --start-at-task="start httpd service"

The output given by a playbook that was run with the ansible-playbook command is a good starting point for troubleshooting issues related to hosts managed by Ansible. Consider the following output from a playbook execution:

PLAY [Service Deployment] ***************************************************
...output omitted...
TASK: [Install a service] ***************************************************
ok: [demoservera]
ok: [demoserverb]

PLAY RECAP ******************************************************************
demoservera                  : ok=2    changed=0    unreachable=0    failed=0
demoserverb                  : ok=2    changed=0    unreachable=0    failed=0

The previous output shows a PLAY header with the name of the play to be executed, followed by one or more TASK headers. Each of these headers represents their associated task in the playbook, and it is executed in all the managed hosts belonging to the group included in the playbook in the hosts parameter.

As each managed host executes each play's tasks, the name of the managed host is displayed under the corresponding TASK header, along with the task state on that managed host. Task states can appear as ok, fatal, changed, or skipping.

At the bottom of the output for each play, the PLAY RECAP section displays the number of tasks executed for each managed host.

As discussed earlier in the course, you can increase the verbosity of the output from ansible-playbook by adding one or more -v options. The ansible-playbook -v command provides additional debugging information, with up to four total levels.

Although the previously discussed tools can help to identify and fix issues in playbooks, when developing those playbooks it is important to keep in mind some recommended practices that can help ease the troubleshooting process. Some recommended practices for playbook development are listed below: