Ansible Debugger: Interactive Debug & Troubleshoot Playbooks

Introduction

In the rapidly evolving landscape of information technology, automation stands out as a beacon of efficiency, offering a promising avenue to streamline processes, enhance security, and elevate overall productivity. Ansible, an open-source automation tool, has garnered significant attention for its potent capabilities in managing complex IT environments. Through the lens of a playbook with a simple mistake, this article delves into the practical nuances of Ansible, shedding light on its powerful ecosystem and how it can transform IT operations.

Ansible: The Automation Powerhouse

At its core, Ansible by Red Hat simplifies cloud provisioning, configuration management, application deployment, intra-service orchestration, and many other IT needs. Leveraging SSH for Linux/Unix hosts and WinRM for Windows hosts, Ansible automates and streamlines tasks without the need for agents on the target servers. This agentless architecture not only enhances security but also simplifies management.

A Common Misstep: Variable Misnaming

Consider a playbook designed to display a message on localhost:

- name: "Playbook with a mistake"
  hosts: "localhost"
  debugger: "on_failed"
  vars:
    message: "A test message!"
  tasks:
    - name: "Display the message"
      ansible.builtin.debug:
        msg: "{{ massage }}"

The error in the playbook above lies in the misuse of a variable name. Instead of referencing the defined variable message, it mistakenly calls for {{ massage }}. This typo leads to an error during playbook execution, as the variable massage does not exist. Such mistakes, though seemingly minor, underscore the importance of accuracy in automation scripting.

Leveraging Ansible's Debugger for Error Handling

Ansible's debugger mode, as showcased in the playbook, serves as a robust tool for diagnosing and resolving errors. When set to on_failed, it initiates an interactive debugging session upon encountering a failure, allowing users to inspect the state of the playbook, examine variables, and test solutions in real-time. This feature not only aids in troubleshooting but also enhances the learning curve for Ansible users by providing immediate feedback on playbook execution issues.

Ansible and the Broader Ecosystem

Ansible extends its capabilities through a vast ecosystem that includes Ansible Tower (AWX for open source), providing a web-based console and REST API for task management. Additionally, Red Hat's Ansible Automation Platform integrates with various tools and services, facilitating a seamless automation experience across different environments and applications.

Integration with cloud services, virtualization platforms, and container orchestration systems like Kubernetes allows Ansible to automate across the entire application lifecycle, from deployment to management. This integration highlights Ansible's role not just in configuration management but in enabling DevOps practices, accelerating deployment cycles, and ensuring consistency across environments.

Conclusion

Ansible's simplicity, combined with its powerful features, makes it a cornerstone in the modern IT automation landscape. While the journey of mastering Ansible may encounter minor setbacks, such as the variable misnaming in our example playbook, the learning experience and efficiencies gained far outweigh these challenges. As IT landscapes continue to grow in complexity, embracing automation tools like Ansible will be key in navigating these complexities efficiently, securely, and reliably.

See also: Ansible Development: Write Custom Modules, Plugins & Collections

Enable Debugger on Failure

- name: Task that might fail
  ansible.builtin.command: /opt/scripts/deploy.sh
  debugger: on_failed

Debugger Keywords

| Value | Triggers On | |-------|------------| | always | Every task | | never | Disabled | | on_failed | Task failure | | on_unreachable | Host unreachable | | on_skipped | Task skipped |

See also: Ansible Troubleshooting: Fix ModuleNotFoundError 'ansible'

Play-Level Debugger

- hosts: webservers
  debugger: on_failed
  tasks:
    - apt: name=nginx
    - service: name=nginx state=started

Debug Strategy

# Pause on every task failure
- hosts: all
  strategy: debug
  tasks:
    - command: /bin/false
    # Drops into interactive debugger

See also: Automating Jenkins Installation with Ansible

Debugger Commands

When the debugger activates:

| Command | Description | |---------|-------------| | p task | Print task name and details | | p task.args | Print task arguments | | p task_vars | Print all variables | | p task_vars['ansible_host'] | Print specific variable | | p result | Print task result | | p result._result | Print raw result dict | | task.args['name'] = 'new_value' | Modify task args | | task_vars['my_var'] = 'new' | Modify variables | | r / redo | Re-run the task | | c / continue | Continue to next task | | q / quit | Quit the playbook | | u / update_task | Update task from modified args |

Debugging Workflow

[web1] TASK: Install package (debug)> p task.args
{'name': 'ngnix', 'state': 'present'}      ← typo!
[web1] TASK: Install package (debug)> task.args['name'] = 'nginx'
[web1] TASK: Install package (debug)> r     ← re-run with fix

Debug with Verbosity

# Increasing detail levels
ansible-playbook site.yml -v      # Task results
ansible-playbook site.yml -vv     # Task input parameters
ansible-playbook site.yml -vvv    # Connection details
ansible-playbook site.yml -vvvv   # Full SSH/connection debug

Debug Module

# Print variables and messages
- ansible.builtin.debug:
    msg: "Host: {{ inventory_hostname }}, IP: {{ ansible_host }}"
- ansible.builtin.debug:
    var: my_complex_variable
- ansible.builtin.debug:
    msg: "{{ groups | to_nice_json }}"
    verbosity: 2  # Only shows with -vv

Assert for Validation

- ansible.builtin.assert:
    that:
      - http_port is defined
      - http_port | int > 0
      - http_port | int < 65536
    fail_msg: "Invalid http_port: {{ http_port | default('undefined') }}"
    success_msg: "Port {{ http_port }} is valid"

FAQ

How do I debug variable values mid-play?

Add debug tasks: debug: var=my_variable. Or use debugger: always to pause and inspect with p task_vars.

Can I use the debugger in AWX/AAP?

No — the interactive debugger requires a terminal. Use debug module and -v flags instead.

How do I debug connection issues?

ansible host -m ping -vvvv
# Shows exact SSH command, key negotiation, and errors

Enable Debugger on Failure

- hosts: all
  debugger: on_failed
  tasks:
    - command: /opt/nonexistent-script.sh
    # Drops into debugger when this fails

Debugger Commands

# When debugger activates:
p task          # Print current task
p task.args     # Print task arguments
p result        # Print task result
p vars          # Print all variables
p host          # Print current host
p task_vars     # Print task variables
r               # Redo the task
c               # Continue to next task
q               # Quit the play
u key=value     # Update task args

Debugger Modes

# On any failure
- hosts: all
  debugger: on_failed
# On unreachable hosts
- hosts: all
  debugger: on_unreachable
# On skipped tasks
- hosts: all
  debugger: on_skipped
# Always (every task)
- hosts: all
  debugger: always
# Never (default)
- hosts: all
  debugger: never

Per-Task Debugger

- template:
    src: config.j2
    dest: /etc/myapp/config
  debugger: on_failed

Debug Strategy

# Step through every task interactively
- hosts: all
  strategy: debug
  tasks:
    - debug: msg="Step 1"
    - debug: msg="Step 2"

Modify Variables at Runtime

# In debugger prompt:
p task.args
# {'src': 'wrong.j2', 'dest': '/etc/config'}
u task.args.src = 'correct.j2'
r
# Re-runs task with corrected argument

Inspect Variable Values

# Check a specific variable
p vars['ansible_hostname']
# Check registered variable
p result
# Check hostvars
p task_vars['hostvars']['web1']['ansible_host']

debug Module (Different from Debugger)

# Print variables (not interactive)
- debug:
    msg: "Host: {{ ansible_hostname }}, IP: {{ ansible_default_ipv4.address }}"
- debug:
    var: my_complex_variable
# Verbosity control
- debug:
    msg: "Only shows with -vv"
    verbosity: 2

assert Module

# Validate assumptions
- assert:
    that:
      - ansible_memtotal_mb >= 2048
      - ansible_distribution == "Ubuntu"
      - app_version is defined
    fail_msg: "Server doesn't meet requirements"
    success_msg: "All checks passed"

Common Debugging Techniques

# Print variable type
- debug: msg="{{ my_var | type_debug }}"
# Print all facts
- setup:
  register: all_facts
- copy:
    content: "{{ all_facts | to_nice_json }}"
    dest: /tmp/facts.json
  delegate_to: localhost
# Fail with message
- fail:
    msg: "Expected {{ expected }} but got {{ actual }}"
  when: actual != expected

FAQ

How to enable debugger globally?

# ansible.cfg
[defaults]
enable_task_debugger = true

Debugger vs debug module?

debugger is interactive (breakpoint-style). debug module just prints values. Use debugger for troubleshooting, debug module for logging.

Can I use debugger in AWX/AAP?

No — debugger requires interactive terminal input. Use verbose logging (-vvv) and callback plugins instead.

Related Articles

• managing Docker with Ansible • role directory layout in Ansible • getting started with Ansible AWX • desired-state Windows config with Ansible