akin-ozer/cc-devops-skills/ansible-validator

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 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
   ├─> Identify versions
   ├─> Lookup documentation (Context7 first, then web.search_query fallback)
   └─> Provide version-specific guidance
 
7. Security and Best Practices Review - DUAL SCANNING DEFAULT
   ├─> Run bash scripts/validate_playbook_security.sh or validate_role_security.sh (Checkov)
   ├─> Run bash scripts/scan_secrets.sh for hardcoded secret detection
   │   └─> This catches secrets Checkov may miss (passwords, API keys, tokens)
   ├─> If one scanner is unavailable, run the other and report reduced coverage
   ├─> Validate privilege escalation
   ├─> Review file permissions
   └─> Identify common anti-patterns
 
8. Reference Routing
   ├─> Map each error/warning class to the matching reference file
   ├─> Extract concrete remediation from references (not file-name-only mention)
   └─> Include source section + fix guidance in final report
 
9. Final Report (required format)
   ├─> Summary counts: PASS / FAIL / BLOCKED / SKIPPED
   ├─> Findings grouped by severity
   ├─> Tool/runtime blockers with exact command that failed
   └─> Next actions to reach full validation coverage

Status contract: BLOCKED means validation could not run due to environment/runtime constraints; FAIL means the Ansible code or tests failed.

Error-Class Reference Routing

When issues are detected, consult the mapped reference and include a specific remediation excerpt in the report.

External documentation lookup trigger:

• If the issue involves a custom/private collection or unknown module parameters not covered locally, run module discovery + documentation lookup (see section 7).

Core Capabilities

1. YAML Syntax Validation

Purpose: Ensure YAML files are syntactically correct before Ansible parsing.

Tools:

• yamllint - YAML linter for syntax and formatting
• ansible-playbook --syntax-check - Ansible-specific syntax validation

Workflow:

# Check YAML syntax with yamllint
yamllint playbook.yml
 
# Or for entire directory
yamllint -c .yamllint .
 
# Check Ansible playbook syntax
ansible-playbook playbook.yml --syntax-check

Common Issues Detected:

• Indentation errors
• Invalid YAML syntax
• Duplicate keys
• Trailing whitespace
• Line length violations
• Missing colons or quotes

Best Practices:

• Always run yamllint before ansible-lint
• Use 2-space indentation consistently
• Configure yamllint rules in .yamllint
• Fix YAML syntax errors first, then Ansible-specific issues

2. Ansible Lint

Purpose: Enforce Ansible best practices and catch common errors.

Workflow:

# Lint a single playbook
ansible-lint playbook.yml
 
# Lint all playbooks in directory
ansible-lint .
 
# Lint with specific rules
ansible-lint -t yaml,syntax playbook.yml
 
# Skip specific rules
ansible-lint -x yaml[line-length] playbook.yml
 
# Output parseable format
ansible-lint -f pep8 playbook.yml
 
# Show rule details
ansible-lint -L

Common Issues Detected:

• Deprecated modules or syntax
• Missing task names
• Improper use of command vs shell
• Unquoted template expressions
• Hard-coded values that should be variables
• Missing become directives
• Inefficient task patterns
• Jinja2 template errors
• Incorrect variable usage
• Role dependencies issues

Severity Levels:

• Error: Must fix - will cause failures
• Warning: Should fix - potential issues
• Info: Consider fixing - best practice violations

Auto-fix approach:

• ansible-lint supports --fix for auto-fixable issues
• Always review changes before applying
• Some issues require manual intervention

3. Security Scanning (Checkov)

Purpose: Identify security vulnerabilities and compliance violations in Ansible code using Checkov, a static code analysis tool for infrastructure-as-code.

What Checkov Provides Beyond ansible-lint:

While ansible-lint focuses on code quality and best practices, Checkov specifically targets security policies and compliance:

• SSL/TLS Security: Certificate validation enforcement
• HTTPS Enforcement: Ensures secure protocols for downloads
• Package Security: GPG signature verification for packages
• Cloud Security: AWS, Azure, GCP misconfiguration detection
• Compliance Frameworks: Maps to security standards
• Network Security: Firewall and network policy validation

Workflow:

# Scan playbook for security issues
bash scripts/validate_playbook_security.sh playbook.yml