Skip to content

Troubleshooting

Ansible can be configured to log its output to log files through the log_path parameter in the default section of the ansible.cfg configuration file.

Debug Module

The debug module provides insight into what is happening in the play.

Example:

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

Managing Errors

It is a good practice to run the --syntax-check option, which checks the YAML syntax for the playbook.

Use the --step option to step through a playbook one task at a time.

Use the --start-at-task option allows you to start execution of a playbook from a specific task.

Debugging

You can increase the verbosity of the output from ansible-playbook by adding one or more -v options.

Verbosity Description
-v The output data is displayed.
-vv The output and input data are displayed.
-vvv Includes information about connections to managed hosts.
-vvvv Includes additional information such scripts that are executed on each remote host.

Recommended Practices for Playbooks

  • Use a concise description of the play's or task's purpose to name plays and tasks.
  • Include comments to add additional inline documentation about tasks.
  • Make effective use of vertical white space.
  • Consistent horizontal indentation is critical using spaces, not tabs.
  • Try to keep the playbook as simple as possible.

Troubleshoot Managed Hosts

Use the ansible-playbook --check command to run smoke tests on a playbook, changes that would have been made to the managed hosts are displayed but not performed.

You can control whether individual tasks run in check mode with the check_mode setting. If a task has check_mode: yes set, it always runs in check mode, whether or not you passed the --check option to ansible-playbook. If a task has check_mode: no set, it always runs normally, even if you pass --check to ansible-playbook.

If you have older playbooks that use always_run: yes to force tasks to run normally even in check mode, you will have to replace that code with check_mode: no in Ansible 2.6 and later.

The ansible-playbook command also provides a --diff option. This option reports the changes made to the template files on managed hosts. If used with the --check option, those changes are displayed in the command's output but not actually made.

Example:

ansible-playbook --check --diff playbook.yml

Testing with Modules

Use uri, script, stat and assert for additional information about the status of a managed host.

**Troubleshooting Connections

Many common problems when using Ansible to manage hosts are associated with connections to the host and with configuration problems around the remote user and privilege escalation.

Make sure that:

  • remote_user set correctly in your configuration file or play
  • The become is set properly, and the correct become_user (root by default)
  • The sudo password is correct and that sudo on the managed host is configured correctly.

Using Ad Hoc Commands

You have used the ping module to test whether you can connect to managed hosts.

ansible all -m ping
ansible all -m ping --become

You can use various commands to check info:

Examples:

ansible all -m ping --become
ansible all -m command -a 'free -m'