Introduction
Debugging is a critical aspect of working with Ansible, as it allows you to monitor the behavior of your playbooks and identify issues without stopping their execution. One of the most useful tools for debugging in Ansible is the ansible.builtin.debug module. This module provides a flexible way to print messages and variable values during playbook execution, which can be invaluable for troubleshooting.
Overview of ansible.builtin.debug
The ansible.builtin.debug module is used to output messages or variable values to the console during playbook execution. This can help you understand the state of your playbook, inspect variable values, and verify the flow of logic.
Parameters
msg(string):- Description: Custom message to print.
- Default: “Hello world!”
- Usage: If omitted, a generic message is printed. This is useful for displaying custom messages or for debugging specific information.
- Example:
yaml
- name: Print a custom message
ansible.builtin.debug:
msg: "The value of my variable is {{ my_variable }}"
var(string):- Description: The name of the variable to debug.
- Mutually Exclusive with:
msg - Usage: Prints the value of the specified variable. Be aware that this option operates within the Jinja2 context and does not require Jinja2 delimiters.
- Example:
yaml
- name: Print the value of a variable
ansible.builtin.debug:
var: my_variable
verbosity(integer):- Description: Controls when the debug message is printed.
- Default: 0
- Usage: The debug message will only be printed if the verbosity level (
-v,-vv,-vvv, etc.) meets or exceeds the specified number. - Example:
yaml
- name: Print message only with verbosity level 2 or higher
ansible.builtin.debug:
msg: "This message is visible only with verbosity -vv"
verbosity: 2
Attributes
action: Full support. Indicates that there is a corresponding action plugin, so some parts of the options can be executed on the controller.async: None. Does not support asynchronous execution.become: None. Usable alongsidebecomekeywords.bypass_host_loop: None. Forces a global task that does not execute per host.check_mode: Full. Can run in check mode and predict changes without modifying the target.connection: None. Uses the target’s connection information to execute code.delegation: Partial. Has little effect except withdelegate_toand related keywords.diff_mode: None. Will not return details on changes in diff mode.platform: Supported on all platforms.
Examples
Here are some practical examples demonstrating how to use the ansible.builtin.debug module:
1. Print a Custom Message
- name: Print a custom message with a variable
ansible.builtin.debug:
msg: "System {{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }}"
when: ansible_default_ipv4.gateway is defined
This example prints a message containing the gateway of each host, but only if the gateway is defined.
2. Print Return Information from a Task
- name: Get uptime information
ansible.builtin.shell: /usr/bin/uptime
register: result
- name: Print return information from the previous task
ansible.builtin.debug:
var: result
verbosity: 2
In this example, the ansible.builtin.debug module prints the result of the uptime command, but only if the verbosity level is -vv or higher.
3. Display All Variables/Facts Known for a Host
- name: Display all variables and facts for the host
ansible.builtin.debug:
var: hostvars[inventory_hostname]
verbosity: 4
This example displays all variables and facts known for the current host, useful for comprehensive debugging.
4. Print Multiple Messages Conditionally
- name: Prints two lines of messages if an environment value is set
ansible.builtin.debug:
msg:
- "Provisioning based on YOUR_KEY which is: {{ lookup('ansible.builtin.env', 'YOUR_KEY') }}"
- "These servers were built using the password of '{{ password_used }}'. Please retain this for later use."
This example prints two lines of messages, including values from environment variables and other playbook variables.
Conclusion
The ansible.builtin.debug module is a powerful tool for debugging Ansible playbooks. By using its parameters and attributes effectively, you can gain insights into variable values, control the verbosity of debug messages, and enhance your troubleshooting process. Whether you’re working on complex playbooks or simple tasks, incorporating debug statements can significantly improve your ability to diagnose and resolve issues.
