Ansible Debug Module: Display Output During Playbook Execution
Troubleshoot your playbooks for errors with the debug module in Ansible.
The Ansible debug module is a simple but powerful tool used to display output directly during playbook execution. It allows you to print custom messages or variable values, making it easier to understand what’s happening at different points in your playbook.
The debug module is useful for troubleshooting errors, confirming data transformation, or just ensuring that variables are being set correctly.
In this guide, I’ll show you how to use the debug module with practical examples.
Why Use the Debug Module in Ansible Playbooks?
There are many situations where the debug module is invaluable:
- Variable Inspection: When working with complex data, such as facts or registered variables, it’s essential to see what’s stored in them.
- Task Tracking: Debugging helps you ensure that tasks are running as expected. You can see the flow of execution and check task-specific data.
- Troubleshooting Failures: When tasks fail, using the debug module can help you gather critical information about the failure and resolve issues faster.
Basic Syntax of Ansible Debug Module
The syntax for using the Ansible debug module is very easy. Below is an example playbook that shows the basic usage of the msg parameter:
---
- name: Basic usage of the debug module
hosts: localhost
tasks:
- name: Display a custom message
debug:
msg: "Hello, World!"
This playbook simply prints the message Hello, World! to the console when run. Let’s explore more advanced usage with practical examples.
Example 1: Debugging Variables in Ansible
One of the most common uses for the debug module is printing variables to check their values during playbook execution. Here’s how to display the contents of a variable.
---
- name: Debugging variables in Ansible
hosts: localhost
tasks:
- name: Display the value of ansible_facts
debug:
var: ansible_facts
This playbook will print out the ansible_facts variable, which contains information about the target host such as its operating system, memory, and network details. The output will look something like this:
ok: [localhost] => {
"ansible_facts": {
"ansible_distribution": "Ubuntu",
"ansible_os_family": "Debian",
"ansible_kernel": "5.4.0-74-generic",
...
}
}
Example 2: Debugging Complex Data Structures
In many cases, especially when working with lists or dictionaries, the debug output can get hard to read. Ansible provides the ability to print complex data structures cleanly using the debug module. Here’s how you can print a list of items in a structured manner:
---
- name: Debugging complex data structures
hosts: localhost
vars:
my_list:
- item1: "apple"
quantity: 5
- item1: "banana"
quantity: 10
tasks:
- name: Display the contents of a list
debug:
var: my_list
The output will look like this:
ok: [localhost] => {
"my_list": [
{
"item1": "apple",
"quantity": 5
},
{
"item1": "banana",
"quantity": 10
}
]
}
This format is easier to read and allows you to see the structure of your variables.
Example 3: Using Debug to Print Host-Specific Variables
When running playbooks on multiple hosts, it’s important to understand the differences in host-specific variables. The debug module can print out variables that differ across hosts. In this example, we’ll print the IP address of each host:
---
- name: Print host-specific variables
hosts: all
tasks:
- name: Display IP address of each host
debug:
msg: "The IP address is {{ ansible_default_ipv4.address }}"
When this playbook runs, it will print the IP address of each host in the inventory:
ok: [host1] => {
"msg": "The IP address is 192.168.1.10"
}
ok: [host2] => {
"msg": "The IP address is 192.168.1.11"
}
Example 4: Debugging Registered Variables
When using the register keyword in Ansible, it’s common to inspect the result of the task by printing the registered variable. Here’s an example where we register the result of a shell command and then use the debug module to inspect it:
---
- name: Debugging registered variables
hosts: localhost
tasks:
- name: Check disk usage
shell: df -h
register: disk_usage
- name: Display disk usage
debug:
var: disk_usage
This will display the output of the df -h command with metadata about the task's execution:
ok: [localhost] => {
"disk_usage": {
"changed": true,
"cmd": "df -h",
"stdout": "Filesystem Size Used Avail Use% Mounted on\n/dev/sda1 50G 25G 25G 50% /",
...
}
}
Example 5: Debugging Loops
You can also use the debug module to inspect variables inside loops. This is particularly useful when working with lists of items and you need to check values as the loop progresses.
---
- name: Debugging a loop in Ansible
hosts: localhost
vars:
fruit_list:
- "apple"
- "banana"
- "cherry"
tasks:
- name: Loop through the fruit list
debug:
msg: "Current item: {{ item }}"
loop: "{{ fruit_list }}"
This will print the current item being processed by the loop:
ok: [localhost] => {
"msg": "Current item: apple"
}
ok: [localhost] => {
"msg": "Current item: banana"
}
ok: [localhost] => {
"msg": "Current item: cherry"
}
Example 6: Debugging a Failed Task
Imagine you have a task that’s supposed to create a directory, but for some reason, it fails. You can use the debug module to print out the error message and the relevant variable values that might help identify the issue.
---
- name: Debugging a failed task
hosts: localhost
tasks:
- name: Attempt to create a directory
file:
path: /test_directory
state: directory
register: result
ignore_errors: yes
- name: Display the error message if the task failed
debug:
var: result
when: result.failed
This example checks if the task failed and then uses debug to display the output of the result variable, showing why the task didn’t succeed. You might see output like this:
ok: [localhost] => {
"result": {
"changed": false,
"msg": "There was an error creating /test_directory",
"failed": true
}
}
Learn Ansible with our course!
Conclusion
In this guide, we explored how to use Ansible debug module to handle error with practical examples. This module can make troubleshooting, development, and playbook writing much easier.
By leveraging the ability to print custom messages, variables, and task results, you can track the flow of data and identify issues in your playbooks with ease.
Combine it with the dry run feature of Ansible, and you will have a good way to troubleshoot your playbooks.
LHB Community
There are many more useful modules in Ansible. You should learn more about them, too.
LHB Community
LHB Community is made of readers like you who share their expertise by writing helpful tutorials. Contact us if you would like to contribute.