ansible-debug_skill

Overview

This skill helps diagnose and fix common Ansible failures like UNREACHABLE, permission denied, MODULE FAILURE, and undefined variable errors. It provides step-by-step checks for SSH/connectivity, authentication/sudo, module parameter issues, and variable/template problems. Use it to reduce troubleshooting time and recover failed playbook runs quickly.

How this skill works

The skill walks through targeted inspections: test SSH connectivity and ports, verify inventory parsing, and confirm key and sudo configuration. It then checks module compatibility and parameters, inspects variables and templates with debug tasks and defaults, and recommends verbosity levels and playbook commands for focused diagnosis. It also suggests config tweaks and performance options to prevent recurrence.

When to use it

• When playbooks report UNREACHABLE or SSH connection failures
• When you see Permission denied or Missing sudo password errors
• When MODULE FAILURE or unexpected module output appears
• When templates fail to render or variables are undefined
• When playbooks run slowly or tasks time out

Best practices

• Start by categorizing the error (connection, authentication, module, or syntax) before changing code
• Reproduce the problem manually: ssh -v user@host and nc -zv host 22 to isolate connectivity
• Use ansible-playbook flags (--syntax-check, --check, --step, --start-at-task, --limit) to narrow scope
• Increase verbosity progressively (-v, -vv, -vvv) and avoid -vvvv unless debugging internals
• Use defaults and ansible.builtin.debug to handle optional variables and surface values

Example use cases

• Fixing UNREACHABLE errors by validating inventory hostnames, SSH keys, and firewalls
• Resolving sudo password failures by running playbooks with --ask-become-pass or adjusting sudoers for NOPASSWD
• Diagnosing MODULE FAILURE by checking ansible-doc for parameter changes and verifying the control node Ansible version
• Tracking undefined variables and template errors using debug tasks and the default filter
• Speeding up playbooks by disabling fact gathering or enabling pipelining in ansible.cfg