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
   ├─> 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.

| Error class | Typical detector | Required reference | Required action | |---|---|---|---| | YAML parse/format errors | yamllint, ansible-playbook --syntax-check | references/common_errors.md (Syntax Errors) | Quote the matching syntax fix pattern and apply corrected YAML structure | | Module/action resolution errors | ansible-playbook, ansible-lint | references/common_errors.md (Module/Collection Errors) | Provide install/version fix commands (ansible-galaxy collection install ...) | | Deprecated or non-FQCN module usage | ansible-lint, bash scripts/check_fqcn.sh | references/module_alternatives.md | Provide exact FQCN/module replacement per finding | | Template/variable errors | ansible-playbook, check mode | references/common_errors.md (Template/Variable Errors), references/best_practices.md (Variable Management) | Recommend default(), required(), or type conversion fixes | | Connection/inventory/privilege errors | ansible-playbook --check, runtime output | references/common_errors.md (Connection, Inventory, Privilege sections) | Provide corrected inventory/auth/become configuration | | Security policy failures (CKV_*) | validate_*_security.sh / Checkov | references/security_checklist.md | Map failed policy to a secure task rewrite | | Hardcoded secrets | bash scripts/scan_secrets.sh | references/security_checklist.md (Secrets Management) | Replace with Vault/env/external secret manager approach | | Role structure/idempotency warnings | validate_role.sh, Molecule idempotence | references/best_practices.md | Provide role layout or idempotency remediation steps |

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

# Scan entire directory
bash scripts/validate_playbook_security.sh /path/to/playbooks/

# Scan role for security issues
bash scripts/validate_role_security.sh roles/webserver/

# Direct checkov usage
checkov -d . --framework ansible

# Scan with specific output format
checkov -d . --framework ansible --output json

# Scan and skip specific checks
checkov -d . --framework ansible --skip-check CKV_ANSIBLE_1

Common Security Issues Detected:

Certificate Validation:

• CKV_ANSIBLE_1: URI module disabling certificate validation
• CKV_ANSIBLE_2: get_url disabling certificate validation
• CKV_ANSIBLE_3: yum disabling certificate validation
• CKV_ANSIBLE_4: yum disabling SSL verification

HTTPS Enforcement:

• CKV2_ANSIBLE_1: URI module using HTTP instead of HTTPS
• CKV2_ANSIBLE_2: get_url using HTTP instead of HTTPS

Package Security:

• CKV_ANSIBLE_5: apt installing packages without GPG signature
• CKV_ANSIBLE_6: apt using force parameter bypassing signatures
• CKV2_ANSIBLE_4:* dnf installing packages without GPG signature
• CKV2_ANSIBLE_5: dnf disabling SSL verification
• CKV2_ANSIBLE_6: dnf disabling certificate validation

Error Handling:

• CKV2_ANSIBLE_3: Block missing error handling

Cloud Security (when managing cloud resources):

• CKV_AWS_88: EC2 instances with public IPs
• CKV_AWS_135: EC2 instances without EBS optimization

Example Violation:

# BAD - Disables certificate validation
- name: Download file
  get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
    validate_certs: false  # Security issue!

# GOOD - Certificate validation enabled
- name: Download file
  get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
    validate_certs: true  # Or omit (true by default)

Integration with Validation Workflow:

Checkov complements ansible-lint:

1. ansible-lint catches code quality issues, deprecated modules, best practices
2. Checkov catches security vulnerabilities, compliance violations, cryptographic issues

Best Practice: Run both tools for comprehensive validation:

# Complete validation workflow
bash scripts/validate_playbook.sh playbook.yml         # Syntax + Lint
bash scripts/validate_playbook_security.sh playbook.yml  # Security

Output Format:

Checkov provides clear security scan results:

Security Scan Results:
  Passed:  15 checks
  Failed:  2 checks
  Skipped: 0 checks

Failed Checks:
  Check: CKV_ANSIBLE_2 - "Ensure that certificate validation isn't disabled with get_url"
    FAILED for resource: tasks/main.yml:download_file
    File: /roles/webserver/tasks/main.yml:10-15

Remediation Resources:

• Checkov Policy Index: https://www.checkov.io/5.Policy%20Index/ansible.html
• Ansible Security Checklist: references/security_checklist.md
• Ansible Best Practices: references/best_practices.md

Installation:

Checkov is automatically installed in a temporary environment if not available system-wide. For permanent installation:

pip3 install checkov

When to Use:

• Before deploying to production
• In CI/CD pipelines for automated security checks
• When working with sensitive infrastructure
• For compliance audits and security reviews
• When downloading files or installing packages
• When managing cloud resources with Ansible

4. Playbook Syntax Check

Purpose: Validate playbook syntax without executing tasks.

Workflow:

# Basic syntax check
ansible-playbook playbook.yml --syntax-check

# Syntax check with inventory
ansible-playbook -i inventory playbook.yml --syntax-check

# Syntax check with extra vars
ansible-playbook playbook.yml --syntax-check -e @vars.yml

# Check all playbooks
for file in *.yml; do
  ansible-playbook "$file" --syntax-check
done

Validation Checks:

• YAML parsing
• Playbook structure
• Task definitions
• Variable references
• Module parameter syntax
• Jinja2 template syntax
• Include/import statements

Error Handling:

• Parse error messages for specific issues
• Check for typos in module names
• Verify variable definitions
• Ensure proper indentation
• Check file paths for includes/imports

5. Dry-Run Testing (Check Mode)

Purpose: Preview changes that would be made without actually applying them.

Workflow:

# Run in check mode (dry-run)
ansible-playbook -i inventory playbook.yml --check

# Check mode with diff
ansible-playbook -i inventory playbook.yml --check --diff

# Check mode with verbose output
ansible-playbook -i inventory playbook.yml --check -v

# Check mode for specific hosts
ansible-playbook -i inventory playbook.yml --check --limit webservers

# Check mode with tags
ansible-playbook -i inventory playbook.yml --check --tags deploy

# Step through tasks
ansible-playbook -i inventory playbook.yml --check --step

Check Mode Analysis:

When reviewing check mode output, focus on:

1. Task Changes:

   • ok: No changes needed
   • changed: Would make changes
   • failed: Would fail (check for check_mode support)
   • skipped: Conditional skip

2. Diff Output:

   • Shows exact changes to files
   • Helps identify unintended modifications
   • Useful for reviewing template changes

3. Handlers:

   • Which handlers would be notified
   • Service restarts that would occur
   • Potential downtime

4. Failed Tasks:

   • Some modules don't support check mode
   • May need check_mode: no override
   • Identify tasks that would fail

Limitations:

• Not all modules support check mode
• Some tasks depend on previous changes
• May not accurately reflect all changes
• Stateful operations may show unexpected results

Safety Considerations:

• Always run check mode before real execution
• Review diff output carefully
• Test in non-production first
• Validate changes make sense
• Check for unintended side effects

6. Molecule Testing

Purpose: Test Ansible roles in isolated environments with multiple scenarios.

Automatic attempt policy: When validating any Ansible role with a molecule/ directory, automatically attempt Molecule tests using bash scripts/test_role.sh <role-path> [scenario].

When to Use:

• Automatically triggered when validating roles with molecule/ directory
• Testing roles before deployment
• Validating role compatibility across different OS versions
• Integration testing for complex roles
• CI/CD pipeline validation

Workflow:

# Initialize molecule for a role
cd roles/myrole
molecule init scenario --driver-name docker

# List scenarios
molecule list

# Run full test sequence
molecule test

# Individual test stages
molecule create      # Create test instances
molecule converge    # Run Ansible against instances
molecule verify      # Run verification tests
molecule destroy     # Destroy test instances

# Test with specific scenario
molecule test -s alternative

# Debug mode
molecule --debug test

# Keep instances for debugging
molecule converge
molecule login       # SSH into test instance

Test Sequence:

1. dependency - Install role dependencies
2. lint - Run yamllint and ansible-lint
3. cleanup - Clean up before testing
4. destroy - Destroy existing instances
5. syntax - Run syntax check
6. create - Create test instances
7. prepare - Prepare instances (install requirements)
8. converge - Run the role
9. idempotence - Run again, verify no changes
10. side_effect - Optional side effect playbook
11. verify - Run verification tests (Testinfra, etc.)
12. cleanup - Final cleanup
13. destroy - Destroy test instances

Molecule Configuration:

Check molecule/default/molecule.yml:

dependency:
  name: galaxy
driver:
  name: docker
platforms:
  - name: instance
    image: ubuntu:22.04
provisioner:
  name: ansible
verifier:
  name: ansible

Verification Tests:

Molecule supports multiple verifiers:

• Ansible (built-in): Use Ansible tasks to verify
• Testinfra: Python-based infrastructure tests
• Goss: YAML-based server validation

Example Ansible verifier (molecule/default/verify.yml):

---
- name: Verify
  hosts: all
  tasks:
    - name: Check service is running
      service:
        name: nginx
        state: started
      check_mode: true
      register: result
      failed_when: result.changed

Common Molecule Errors:

• Driver not installed (docker, podman, vagrant)
• Missing Python dependencies
• Platform image not available
• Network connectivity issues
• Insufficient permissions for driver

Molecule Skip/Fallback Policy (Required):

• If molecule/ does not exist: mark Molecule as SKIPPED and continue.
• If test_role.sh exits 2: mark Molecule as BLOCKED (missing/unavailable runtime dependency) and continue.
• If test_role.sh exits 1: mark Molecule as FAIL (role/test issue) and continue.
• Never stop the full validation report because Molecule is blocked.

Use this reporting language for blocked Molecule runs:

Molecule Status: BLOCKED
Reason: <missing dependency/runtime and failing command>
Fallback Applied: Completed syntax, lint, check-mode, and security validation without Molecule runtime tests.
Next Action: <install/start dependency>; rerun `bash scripts/test_role.sh <role-path> [scenario]`

7. Custom Module and Collection Documentation Lookup

Purpose: Automatically discover and retrieve version-specific documentation for custom modules and collections using web search and Context7 MCP.

When to Trigger:

• Encountering unfamiliar module usage
• Working with custom/private collections
• Debugging module-specific errors
• Understanding new module parameters
• Checking version compatibility
• Deprecated module alternatives

Detection Workflow:

1. Extract Module Information:

   • Use scripts/extract_ansible_info_wrapper.sh to parse playbooks and roles
   • Identify module usage and collections
   • Extract version constraints from requirements.yml

2. Extract Collection Information:

   • Identify collection namespaces (e.g., community.general, ansible.posix)
   • Determine collection versions from requirements.yml or galaxy.yml
   • Detect custom/private vs. public collections

Documentation Lookup Strategy:

Use this deterministic lookup order:

1. For public collections/modules:
   • Resolve library: mcp__context7__resolve-library-id
   • Query docs: mcp__context7__query-docs
2. If Context7 has no suitable result:
   • Use web search via web.search_query with versioned queries
   • Prioritize official docs (docs.ansible.com, galaxy.ansible.com, vendor docs)
3. For custom/private modules:
   • Prefer in-repo docs (README, module docs, role docs) first
   • Then use targeted web search with collection/module/version terms
4. Always report source + version context used in final guidance

Search Query Templates:

# For custom modules
"[module-name] ansible module version [version] documentation"
"[module-name] ansible [module-type] example"
"ansible [collection-name].[module-name] parameters"

# For custom collections
"ansible collection [collection-name] version [version]"
"[collection-namespace].[collection-name] ansible documentation"
"ansible galaxy [collection-name] modules"

# For specific errors
"ansible [module-name] error: [error-message]"
"ansible [collection-name] module failed"

Example Workflow:

User working with: community.docker.docker_container version 3.0.0

1. Extract module info from playbook:
   tasks:
     - name: Start container
       community.docker.docker_container:
         name: myapp
         image: nginx:latest

2. Detect collection: community.docker

3. Search for documentation:
   - Try Context7: mcp__context7__resolve-library-id("ansible community.docker")
   - Fallback to web.search_query("ansible community.docker col

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->