/ansible-validator

name: ansible-validator
description: Validate, lint, audit, or debug Ansible playbooks, roles, inventories, FQCN, tasks.

Ansible Validator

Overview

Comprehensive toolkit for validating, linting, and testing Ansible playbooks, roles, and collections. This skill provides automated workflows for ensuring Ansible code quality, syntax validation, dry-run testing with check mode and molecule, and intelligent documentation lookup for custom modules and collections with version awareness.

**Default behavior:** When validating any Ansible role with a `molecule/` directory, attempt Molecule automatically using `bash scripts/test_role.sh <role-path>`. If Molecule cannot run due to environment/runtime limits, mark Molecule as `BLOCKED`, report why, and continue all non-Molecule validation steps.

Trigger Guidance

Use this skill when the request is about validating or debugging existing Ansible code, not generating new code.

Common trigger phrases:

• "validate this playbook"
• "lint this role"
• "why is ansible-lint failing"
• "run check mode safely"
• "test this role with molecule"
• "find security issues in these Ansible files"
• "module not found in this collection"

When to Use This Skill

Apply this skill when encountering any of these scenarios:

• Working with Ansible files (`.yml`, `.yaml` playbooks, roles, inventories, vars)
• Validating Ansible playbook syntax and structure
• Linting and formatting Ansible code
• Performing dry-run testing with `ansible-playbook --check`
• Testing roles and playbooks with Molecule
• Debugging Ansible errors or misconfigurations
• Understanding custom Ansible modules, collections, or roles
• Ensuring infrastructure-as-code best practices
• Security validation of Ansible playbooks
• Version compatibility checks for collections and modules

Preflight (Run First)

Run preflight before validation to avoid dead ends:

bash scripts/setup_tools.sh

Command path assumption: run commands from this skill root (`devops-skills-plugin/skills/ansible-validator`) or use absolute paths.

Preflight requirements:

• Baseline validation: `ansible`, `ansible-playbook`, `ansible-lint` (plus `yamllint` recommended)
• Molecule execution: `molecule` plus an available runtime (`docker` or `podman`)
• Security scanning: `checkov` (wrapper can bootstrap if missing)

Deterministic fallback rules:

• If baseline tools are missing but Python + pip are available, wrapper scripts bootstrap temporary environments automatically.
• If wrapper bootstrap fails (offline index, pip failure, missing Python), run direct commands for available tools, mark missing stages as `BLOCKED`, and continue.
• If Molecule runtime is unavailable (Docker/Podman missing or daemon not running), skip Molecule execution, mark as `BLOCKED`, and continue remaining stages.

Wrapper vs Direct Command Routing

Use wrappers by default for consistent behavior and fallback handling.

| Validation scenario | Default command | Use direct command when | Fallback if command cannot run | |---|---|---|---| | Playbook syntax/lint | `bash scripts/validate_playbook.sh <playbook.yml>` | User asks for a single focused check only (`ansible-playbook --syntax-check`, `ansible-lint`, or `yamllint`) | Run any available direct checks and report skipped checks as `BLOCKED` | | Role structural validation | `bash scripts/validate_role.sh <role-dir>` | User asks only for specific sub-checks (for example, structure only) | Run structure/YAML checks that are possible and report missing stages | | Role Molecule execution | `bash scripts/test_role.sh <role-dir> [scenario]` | User explicitly asks for manual stage-by-stage Molecule commands | Mark Molecule `BLOCKED` with reason and continue non-Molecule role checks | | Security scanning | `bash scripts/validate_playbook_security.sh <path>` or `bash scripts/validate_role_security.sh <path>` plus `bash scripts/scan_secrets.sh <path>` | User requests raw Checkov output formatting or custom flags | Run whichever scanner is available; if one is missing, run the other and report coverage gap | | Module/collection discovery | `bash scripts/extract_ansible_info_wrapper.sh <path>` | Python environment is already known-good and user wants direct parser output | If extraction fails, manually inspect `requirements.yml`/`galaxy.yml` and continue with best-effort lookup |

Validation Workflow

Follow this deterministic workflow and never stop at a missing dependency:

0. Preflight
   ├─> Run: bash scripts/setup_tools.sh
   ├─> Record tool/runtime readiness
   └─> Continue even when optional tools are missing

1. Identify scope
   ├─> Single playbook validation
   ├─> Role validation
   ├─> Collection validation
   └─> Multi-playbook/inventory validation

2. Syntax Validation
   ├─> Run ansible-playbook --syntax-check
   ├─> Run yamllint for YAML syntax
   └─> Report as PASS/FAIL/BLOCKED

3. Lint and Best Practices
   ├─> Run ansible-lint (comprehensive linting)
   ├─> Check for deprecated modules (see references/module_alternatives.md)
   ├─> **DETECT NON-FQCN MODULE USAGE** (apt vs ansible.builtin.apt)
   │   └─> Run bash scripts/check_fqcn.sh to identify short module names
   │   └─> Recommend FQCN alternatives from references/module_alternatives.md
   ├─> Verify role structure
   └─> Report linting issues

4. Dry-Run Testing (check mode)
   ├─> Run ansible-playbook --check (if inventory available)
   ├─> Analyze what would change
   └─> Report potential issues

5. Molecule Testing (for roles with molecule/) - AUTOMATIC ATTEMPT
   ├─> Check if molecule/ directory exists in role
   ├─> If present, run: bash scripts/test_role.sh <role-path> [scenario]
   ├─> If script exits 2, mark Molecule as BLOCKED (environment/runtime issue)
   ├─> If script exits 1, mark Molecule as FAIL (role/test issue)
   └─> Continue remaining validation regardless of Molecule outcome

6. Custom Module/Collection Analysis (if detected)
   ├─> Extract module/collection information
   ├─> Iden