ansible-validator

Ansible 验证器

概述

用于验证、检查和测试 Ansible playbook、角色及集合的综合工具包。此技能提供自动化工作流，确保 Ansible 代码质量、验证语法、使用检查模式和 Molecule 进行试运行，并支持根据版本查询自定义模块和集合的相关文档。

默认行为： 验证任何包含 molecule/ 目录的 Ansible 角色时，自动尝试运行 Molecule：bash scripts/test_role.sh <role-path>。如果因环境或运行时限制而无法运行 Molecule，请将 Molecule 标记为 BLOCKED，说明原因，并继续所有非 Molecule 验证步骤。

触发指南

当请求涉及验证或调试现有 Ansible 代码，而不是生成新代码时，使用此技能。

常见触发语句：

• “验证这个 playbook”
• “检查这个角色”
• “为什么 ansible-lint 会失败”
• “安全地运行检查模式”
• “用 molecule 测试这个角色”
• “查找这些 Ansible 文件中的安全问题”
• “在此集合中找不到模块”

何时使用此技能

遇到以下任一场景时，使用此技能：

• 处理 Ansible 文件（.yml、.yaml playbook、角色、清单、变量）
• 验证 Ansible playbook 的语法和结构
• 检查和格式化 Ansible 代码
• 使用 ansible-playbook --check 执行试运行测试
• 使用 Molecule 测试角色和 playbook
• 调试 Ansible 错误或配置问题
• 了解自定义 Ansible 模块、集合或角色
• 确保符合基础设施即代码最佳实践
• 对 Ansible playbook 进行安全验证
• 检查集合和模块的版本兼容性

预检（先运行）

验证前先运行预检，避免陷入困境：

bash scripts/setup_tools.sh

命令路径假设：从此技能根目录（devops-skills-plugin/skills/ansible-validator）运行命令，或使用绝对路径。

预检要求：

• 基础验证：ansible、ansible-playbook、ansible-lint（建议同时使用 yamllint）
• 执行 Molecule：molecule 和可用的运行时（docker 或 podman）
• 安全扫描：checkov（如果缺失，包装脚本可以自动安装）

确定性回退规则：

• 如果缺少基础工具，但 Python 和 pip 可用，包装脚本会自动设置临时环境。
• 如果包装脚本设置失败（索引离线、pip 失败、缺少 Python），则直接运行可用的命令，将缺失的阶段标记为 BLOCKED，并继续执行。
• 如果 Molecule 运行时不可用（缺少 Docker/Podman 或守护进程未运行），则跳过 Molecule 执行，将其标记为 BLOCKED，并继续其余阶段。

封装命令与直接命令的路由

默认使用封装命令，以确保行为一致并处理回退。

验证场景	默认命令	在以下情况下使用直接命令	命令无法运行时的回退方案
Playbook 语法／lint	bash scripts/validate_playbook.sh <playbook.yml>	用户只要求进行一项针对性检查（ansible-playbook --syntax-check、ansible-lint 或 yamllint）	运行所有可用的直接检查，并将跳过的检查报告为 BLOCKED
Role 结构验证	bash scripts/validate_role.sh <role-dir>	用户只要求特定的子检查（例如，仅检查结构）	运行可执行的结构／YAML 检查，并报告缺失的阶段
Role Molecule 执行	bash scripts/test_role.sh <role-dir> [scenario]	用户明确要求逐阶段手动执行 Molecule 命令	将 Molecule 标记为 BLOCKED 并说明原因，然后继续执行非 Molecule 的 Role 检查
安全扫描	bash scripts/validate_playbook_security.sh <path> 或 bash scripts/validate_role_security.sh <path>，以及 bash scripts/scan_secrets.sh <path>	用户要求原始 Checkov 输出格式或自定义标志	运行可用的扫描器；若缺少其中一个，则运行另一个并报告覆盖范围的缺口
Module／collection 发现	bash scripts/extract_ansible_info_wrapper.sh <path>	已确认 Python 环境正常，且用户需要直接的解析器输出	若提取失败，则手动检查 requirements.yml／galaxy.yml，并尽力继续查找

验证工作流

遵循此确定性工作流，遇到缺失的依赖项时绝不停止：

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

状态约定： BLOCKED 表示由于环境／运行时限制而无法执行验证；FAIL 表示 Ansible 代码或测试未通过。

错误类别参考路由

发现问题时，请查阅对应的参考资料，并在报告中附上具体的修复示例。

错误类别	常见检测器	必须参考的资料	必须采取的操作
YAML 解析／格式错误	yamllint、ansible-playbook --syntax-check	references/common_errors.md（Syntax Errors）	引用匹配的语法修复模式，并应用修正后的 YAML 结构
Module／操作解析错误	ansible-playbook、ansible-lint	references/common_errors.md（Module/Collection Errors）	提供安装／版本修复命令（ansible-galaxy collection install ...）
已弃用或非 FQCN 的 module 用法	ansible-lint、bash scripts/check_fqcn.sh	references/module_alternatives.md	针对每项发现提供准确的 FQCN／module 替换方案
模板／变量错误	ansible-playbook、检查模式	references/common_errors.md（Template/Variable Errors）、references/best_practices.md（Variable Management）	建议使用 default()、required() 或类型转换进行修复
连接／inventory／权限错误	ansible-playbook --check、运行时输出	references/common_errors.md（Connection、Inventory、Privilege 部分）	提供修正后的 inventory／身份验证／become 配置
安全策略失败（CKV_*）	validate_*_security.sh／Checkov	references/security_checklist.md	将失败的策略映射为安全的任务重写方案
硬编码密钥	bash scripts/scan_secrets.sh	references/security_checklist.md（Secrets Management）	改用 Vault／环境变量／外部密钥管理器方案
Role 结构／幂等性警告	validate_role.sh、Molecule 幂等性检查	references/best_practices.md	提供 Role 布局或幂等性修复步骤

外部文档查找触发条件：

• 如果问题涉及自定义／私有 collection，或本地资料未涵盖的未知 module 参数，请执行 module 发现和文档查找（见第 7 节）。

核心功能

1. YAML 语法验证

目的： 确保 YAML 文件在 Ansible 解析前语法正确。

工具：

• yamllint - 用于检查 YAML 语法和格式的 linter
• ansible-playbook --syntax-check - Ansible 专用语法验证

工作流：

# 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

检测到的常见问题：

• 缩进错误
• YAML 语法无效
• 重复的键
• 尾随空白
• 行长度超限
• 缺少冒号或引号

最佳实践：

• 始终在运行 ansible-lint 前运行 yamllint
• 始终使用 2 个空格缩进
• 在 .yamllint 中配置 yamllint 规则
• 先修复 YAML 语法错误，再处理 Ansible 专属问题

2. Ansible Lint

目的： 强制遵循 Ansible 最佳实践并捕获常见错误。

工作流：

# 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

检测到的常见问题：

• 已弃用的模块或语法
• 缺少任务名称
• command 与 shell 使用不当
• 模板表达式未加引号
• 应使用变量的硬编码值
• 缺少 become 指令
• 低效的任务模式
• Jinja2 模板错误
• 变量使用不正确
• 角色依赖问题

严重级别：

• 错误： 必须修复，否则会导致失败
• 警告： 应当修复，可能存在问题
• 信息： 建议修复，属于违反最佳实践的情况

自动修复方式：

• ansible-lint 支持使用 --fix 自动修复可修复的问题
• 应用更改前务必检查
• 某些问题需要手动处理

3. 安全扫描（Checkov）

用途： 使用 Checkov（基础设施即代码静态代码分析工具）识别 Ansible 代码中的安全漏洞和合规性违规。

Checkov 相比 ansible-lint 提供的额外功能：

ansible-lint 侧重于代码质量和最佳实践，而 Checkov 专门针对安全策略和合规性：

• SSL/TLS 安全性： 强制验证证书
• 强制使用 HTTPS： 确保下载使用安全协议
• 软件包安全性： 验证软件包的 GPG 签名
• 云安全： 检测 AWS、Azure、GCP 配置错误
• 合规性框架： 对应安全标准
• 网络安全： 验证防火墙和网络策略

工作流：

# 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

检测到的常见安全问题：

证书验证：

• CKV_ANSIBLE_1： URI 模块禁用了证书验证
• CKV_ANSIBLE_2： get_url 禁用了证书验证
• CKV_ANSIBLE_3： yum 禁用了证书验证
• CKV_ANSIBLE_4： yum 禁用了 SSL 验证

强制使用 HTTPS：

• CKV2_ANSIBLE_1： URI 模块使用 HTTP 而非 HTTPS
• CKV2_ANSIBLE_2： get_url 使用 HTTP 而非 HTTPS

软件包安全性：

• CKV_ANSIBLE_5： apt 安装软件包时未验证 GPG 签名
• CKV_ANSIBLE_6： apt 使用 force 参数绕过签名验证
• CKV2_ANSIBLE_4：* dnf 安装软件包时未验证 GPG 签名
• CKV2_ANSIBLE_5： dnf 禁用了 SSL 验证
• CKV2_ANSIBLE_6： dnf 禁用了证书验证

错误处理：

• CKV2_ANSIBLE_3： Block 缺少错误处理

云安全（管理云资源时）：

• CKV_AWS_88： EC2 实例具有公共 IP
• CKV_AWS_135： EC2 实例未启用 EBS 优化

违规示例：

# 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)

与验证工作流集成：

Checkov 与 ansible-lint 相辅相成：

1. ansible-lint 检查代码质量问题、已弃用模块和最佳实践
2. Checkov 检查安全漏洞、合规性违规和加密问题

最佳实践： 同时运行这两种工具，进行全面验证：

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

输出格式：

Checkov 会提供清晰的安全扫描结果：

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

修复资源：

• Checkov 策略索引：https://www.checkov.io/5.Policy%20Index/ansible.html
• Ansible 安全检查清单：references/security_checklist.md
• Ansible 最佳实践：references/best_practices.md

安装：

如果 Checkov 未在系统范围内安装，会自动在临时环境中安装。如需永久安装：

pip3 install checkov

适用场景：

• 部署到生产环境之前
• 在 CI/CD 流水线中执行自动化安全检查
• 处理敏感基础设施时
• 进行合规性审计和安全审查时
• 下载文件或安装软件包时
• 使用 Ansible 管理云资源时

4. Playbook 语法检查

用途： 验证 Playbook 语法，但不执行任务。

工作流：

# 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

验证检查项：

• YAML 解析
• Playbook 结构
• 任务定义
• 变量引用
• 模块参数语法
• Jinja2 模板语法
• Include/import 语句

错误处理：

• 根据解析错误消息定位具体问题
• 检查模块名称是否有拼写错误
• 验证变量定义
• 确保缩进正确
• 检查 include/import 的文件路径

5. Dry-Run 测试（检查模式）

**目的：**预览将要进行的更改，但不实际应用。

工作流：

# 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

检查模式分析：

查看检查模式的输出时，请重点关注：

1. 任务更改：

   • ok：无需更改
   • changed：将进行更改
   • failed：将失败（检查是否支持 check_mode）
   • skipped：条件跳过

2. 差异输出：

   • 显示文件的具体更改
   • 有助于识别意外修改
   • 便于审查模板更改

3. 处理程序：

   • 哪些处理程序会收到通知
   • 将执行哪些服务重启
   • 可能造成的停机时间

4. 失败的任务：

   • 某些模块不支持检查模式
   • 可能需要使用 check_mode: no 覆盖设置
   • 找出将会失败的任务

限制：

• 并非所有模块都支持检查模式
• 某些任务依赖之前的更改
• 可能无法准确反映所有更改
• 有状态操作可能会显示意外结果

安全注意事项：

• 实际执行前务必运行检查模式
• 仔细审查差异输出
• 先在非生产环境中测试
• 验证更改是否合理
• 检查是否有意外的副作用

6. Molecule 测试

**目的：**在隔离环境中通过多个场景测试 Ansible 角色。

**自动尝试策略：**验证任何包含 molecule/ 目录的 Ansible 角色时，自动尝试使用 bash scripts/test_role.sh <role-path> [scenario] 运行 Molecule 测试。

使用时机：

• 验证包含 molecule/ 目录的角色时自动触发
• 部署前测试角色
• 验证角色在不同 OS 版本上的兼容性
• 对复杂角色进行集成测试
• 验证 CI/CD 管道

工作流：

# 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

测试顺序：

1. dependency - 安装角色依赖项
2. lint - 运行 yamllint 和 ansible-lint
3. cleanup - 测试前清理
4. destroy - 销毁现有实例
5. syntax - 运行语法检查
6. create - 创建测试实例
7. prepare - 准备实例（安装所需内容）
8. converge - 运行角色
9. idempotence - 再次运行，验证没有更改
10. side_effect - 可选的副作用 playbook
11. verify - 运行验证测试（Testinfra 等）
12. cleanup - 最终清理
13. destroy - 销毁测试实例

Molecule 配置：

检查 molecule/default/molecule.yml：

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

验证测试：

Molecule 支持多个验证器：

• Ansible（内置）：使用 Ansible 任务进行验证
• Testinfra：基于 Python 的基础设施测试
• Goss：基于 YAML 的服务器验证

Ansible 验证器示例（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

常见 Molecule 错误：

• 未安装驱动程序（docker、podman、vagrant）
• 缺少 Python 依赖项
• 平台映像不可用
• 网络连接问题
• 驱动程序权限不足

Molecule 跳过/回退策略（必需）：

• 如果 molecule/ 不存在：将 Molecule 标记为 SKIPPED 并继续。
• 如果 test_role.sh 以 2 退出：将 Molecule 标记为 BLOCKED（运行时依赖项缺失/不可用）并继续。
• 如果 test_role.sh 以 1 退出：将 Molecule 标记为 FAIL（角色/测试问题）并继续。
• Molecule 受阻时，绝不要因此停止生成完整的验证报告。

Molecule 运行受阻时，请使用以下报告措辞：

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. 自定义模块和集合文档查询

用途： 使用网络搜索和 Context7 MCP，自动发现并检索特定版本的自定义模块和集合文档。

触发条件：

• 遇到不熟悉的模块用法
• 使用自定义／私有集合
• 调试模块特定错误
• 了解新的模块参数
• 检查版本兼容性
• 查找已弃用模块的替代方案

检测工作流：

1. 提取模块信息：

   • 使用 scripts/extract_ansible_info_wrapper.sh 解析 playbook 和角色
   • 识别模块用法和集合
   • 从 requirements.yml 中提取版本约束

2. 提取集合信息：

   • 识别集合命名空间（例如 community.general、ansible.posix）
   • 从 requirements.yml 或 galaxy.yml 中确定集合版本
   • 判断集合是自定义／私有还是公开

文档查询策略：

按以下固定顺序查询：

1. 对于公开集合／模块：
   • 解析库：mcp__context7__resolve-library-id
   • 查询文档：mcp__context7__query-docs
2. 如果 Context7 没有合适的结果：
   • 使用 web.search_query 进行网络搜索，并在查询中指定版本
   • 优先查阅官方文档（docs.ansible.com、galaxy.ansible.com、供应商文档）
3. 对于自定义／私有模块：
   • 优先查阅仓库内的文档（README、模块文档、角色文档）
   • 然后使用包含集合／模块／版本关键词的定向网络搜索
4. 在最终指南中始终注明所用来源和版本信息

搜索查询模板：

# 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"

示例工作流：

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 collection version 3.0 docker_container module documentation")

4. If official docs found:
   - Parse module parameters (required vs optional)
   - Identify return values
   - Find usage examples
   - Check version compatibility

5. Provide version-specific guidance to user

版本兼容性检查：

• 对比所需集合版本与可用版本
• 识别已弃用的模块或参数
• 如果使用的是过时版本，建议升级路径
• 提醒版本之间的破坏性变更
• 检查与 Ansible core 版本的兼容性

常见集合来源：

• Ansible Galaxy：官方社区集合
• Red Hat Automation Hub：认证集合
• GitHub：自定义／私有集合
• 内部仓库：公司专用集合

8. 安全性与最佳实践验证

目的： 识别 Ansible playbook 中的安全漏洞和反模式。

安全检查：

1. 机密信息检测：

   # Check for hardcoded credentials
   grep -r "password:" *.yml
   grep -r "secret:" *.yml
   grep -r "api_key:" *.yml
   grep -r "token:" *.yml
   

   修复方法： 使用 Ansible Vault、环境变量或外部机密管理工具

2. 权限提升：

   • 不必要地使用 become: yes
   • 未指定 become_user
   • sudo 规则权限过宽
   • 以 root 身份运行整个 playbook

3. 文件权限：

   • 敏感文件可被所有用户读取
   • 文件或模板任务缺少 mode 参数
   • 所有权设置不正确
   • 敏感文件未使用 vault 加密

4. 命令注入：

   • 在 shell/command 模块中使用未经验证的变量
   • 未使用 quote 过滤器处理用户输入
   • 在命令字符串中直接使用 {{ var }}

5. 网络安全：

   • 使用未加密的协议（HTTP 而非 HTTPS）
   • 未进行 SSL/TLS 验证
   • 在 0.0.0.0 上公开服务
   • 使用不安全的默认端口

最佳实践：

1. Playbook 组织：

   • 按逻辑划分任务
   • 使用可复用的角色实现常见模式
   • 目录结构清晰
   • Playbook 名称有意义

2. 变量管理：

   • 使用 Vault 加密敏感数据
   • 采用清晰的变量命名约定
   • 了解变量优先级
   • 组织 group/host 变量
   • 使用 default() 过滤器设置默认值

3. 任务命名：

   • 任务名称应具有描述性
   • 遵循一致的命名约定
   • 使用以操作为导向的描述
   • 在名称中注明发生变更的资源

4. 幂等性：

   • 所有任务都应具有幂等性
   • 使用适当的模块，而非 command/shell
   • 兼容检查模式
   • 为 command 任务正确使用 creates、removes
   • 除非必要，否则避免使用 changed_when: false

5. 错误处理：

   • 使用 failed_when 设置自定义失败条件
   • 使用 block/rescue/always 实现错误恢复
   • 合理设置 any_errors_fatal
   • 谨慎使用 ignore_errors

6. 文档：

   • 为每个角色提供 README
   • 在 defaults/main.yml 中记录变量
   • 在 meta/main.yml 中提供角色元数据
   • 添加 Playbook 文件头注释

参考文档：

如需了解详细的安全指南和最佳实践，请参阅：

• references/security_checklist.md - 常见安全漏洞
• references/best_practices.md - Ansible 编码标准
• references/common_errors.md - 常见错误和解决方案

工具前置条件

验证前请运行此预检：

# Preferred one-shot preflight
bash scripts/setup_tools.sh

# Check Ansible installation
ansible --version
ansible-playbook --version

# Check ansible-lint installation
ansible-lint --version

# Check yamllint installation
yamllint --version

# Check molecule installation (for role testing with molecule/)
molecule --version

# Check container runtime for Molecule
docker --version
docker info
# or
podman --version
podman info

# Install missing tools (example for pip)
pip install ansible ansible-lint yamllint ansible-compat

# Install molecule with docker driver
pip install molecule molecule-docker

# Install molecule with podman driver (alternative)
pip install molecule molecule-podman

最低版本要求：

• Ansible：>= 2.9（建议 >= 2.12）
• ansible-lint：>= 6.0.0
• yamllint：>= 1.26.0
• molecule：>= 3.4.0（用于测试角色时）

缺少工具时的执行策略：

• 如果缺少 ansible/ansible-lint，封装脚本（validate_playbook.sh、validate_role.sh）会尝试临时引导创建 venv。
• 如果 Molecule 运行时（docker info 或 podman info）不可用，则 Molecule 状态为 BLOCKED，并继续执行非 Molecule 检查。
• 如果缺少 checkov，安全封装脚本会在可能时引导安装该工具；否则运行 scan_secrets.sh，并报告安全覆盖范围有所缩减。

可选工具：

• ansible-inventory - 清单验证和绘图
• ansible-doc - 查询模块文档
• jq - 解析 JSON 格式的结构化输出

错误排查

常见错误和解决方案

错误：未找到模块

Solution: Install required collection with ansible-galaxy
Check collections/requirements.yml
Verify collection namespace and name

错误：变量未定义

Solution: Define variable in vars, defaults, or group_vars
Check variable precedence
Use default() filter for optional variables
Verify variable file is included

错误：模板语法错误

Solution: Check Jinja2 template syntax
Verify variable types match filters
Ensure proper quote escaping
Test template rendering separately

错误：连接失败

Solution: Verify inventory host accessibility
Check SSH configuration and keys
Verify ansible_host and ansible_port
Test with ansible -m ping

错误：权限被拒绝

Solution: Add become: yes for privilege escalation
Verify sudo/su configuration
Check file permissions
Verify user has necessary privileges

错误：模块已弃用

Solution: Check ansible-lint output for replacement
Consult module documentation for alternatives
Update to recommended module
Test functionality with new module

资源

scripts/

setup_tools.sh - Ansible 验证器依赖项的预检工具。它会验证基础工具（ansible、ansible-playbook、ansible-lint、yamllint）以及 Molecule 运行时就绪情况（docker/podman），并提供安装指南。

用法：

bash scripts/setup_tools.sh

extract_ansible_info_wrapper.sh - 用于 extract_ansible_info.py 的 Bash 包装脚本，可自动处理 PyYAML 依赖项。如果系统 Python 中没有 PyYAML，则会创建临时 venv。

用法：

bash scripts/extract_ansible_info_wrapper.sh <path-to-playbook-or-role>

输出：包含模块、集合和版本的 JSON 结构

extract_ansible_info.py - Python 脚本（由包装脚本调用），用于解析 Ansible playbook 和角色，以提取模块使用情况、集合依赖项和版本信息。包装脚本会自动处理依赖项管理。

validate_playbook.sh - 全面的验证脚本，会对 playbook 运行语法检查、yamllint 和 ansible-lint。如果系统中没有 ansible 和 ansible-lint，则会在临时 venv 中自动安装（有可用的系统版本时优先使用）。

用法：

bash scripts/validate_playbook.sh <playbook.yml>

validate_playbook_security.sh - 安全验证脚本，使用 Checkov 扫描 playbook 中的安全漏洞。如果系统中没有 checkov，则会在临时 venv 中自动安装。此脚本与 validate_playbook.sh 互为补充，重点检查 SSL/TLS 验证、HTTPS 强制执行和软件包签名验证等安全问题。

用法：

bash scripts/validate_playbook_security.sh <playbook.yml>
# Or scan entire directory
bash scripts/validate_playbook_security.sh /path/to/playbooks/

validate_role.sh - 全面的角色验证脚本，用于检查角色结构、YAML 语法、Ansible 语法、lint 和 molecule 配置。

用法：

bash scripts/validate_role.sh <role-directory>

验证内容：

• 角色目录结构（必需和建议的目录）
• 每个目录中是否存在 main.yml 文件
• 所有角色文件中的 YAML 语法
• 使用测试 playbook 检查 Ansible 语法
• 使用 ansible-lint 检查最佳实践
• Molecule 测试配置

validate_role_security.sh - 使用 Checkov 验证 Ansible 角色安全性的脚本。扫描整个角色目录以查找安全问题。如果系统中没有 checkov，则会在临时 venv 中自动安装。此脚本通过侧重安全的检查补充 validate_role.sh。

用法：

bash scripts/validate_role_security.sh <role-directory>

test_role.sh - 用于 Molecule 测试的包装脚本，可自动安装依赖项。如果缺少 molecule，则会创建临时 venv 并安装依赖项。遇到环境／运行时阻碍（例如缺少 Docker／Podman 运行时）时返回退出码 2；角色／测试失败时返回退出码 1。

用法：

bash scripts/test_role.sh <role-directory> [scenario]

scan_secrets.sh - 全面的密钥扫描器，使用基于 grep 的模式匹配来检测 Ansible 文件中硬编码的密钥。此脚本与 Checkov 安全扫描互为补充，可捕获静态分析可能遗漏的密钥，包括密码、API 密钥、令牌、AWS 凭证和私钥。

用法：

bash scripts/scan_secrets.sh <playbook.yml|role-directory|directory>

检测内容：

• 硬编码的密码和凭证
• API 密钥和令牌
• AWS 访问密钥和秘密密钥
• 内嵌凭证的数据库连接字符串
• 私钥内容（RSA、OpenSSH、EC、DSA）

重要： 为全面扫描安全问题，始终应将此脚本与 Checkov（validate_*_security.sh）一起运行。Checkov 可捕获 SSL/TLS 和协议问题；此脚本则可捕获硬编码的密钥。

check_fqcn.sh - 扫描 Ansible 文件，识别使用短名称而非完全限定集合名称（FQCN）的模块。建议迁移到 ansible.builtin.* 或相应的集合命名空间，以提高清晰度并确保未来兼容性。

用法：

bash scripts/check_fqcn.sh <playbook.yml|role-directory|directory>

检测内容：

• ansible.builtin 模块（apt、yum、copy、file、template、service 等）
• community.general 模块（ufw、docker_container、timezone 等）
• ansible.posix 模块（synchronize、acl、firewalld 等）

提供具体迁移建议，并给出 FQCN 替代方案。

validate_inventory.sh - 验证 Ansible inventory 文件和目录。检查 YAML 语法、解析主机／组层级，并指出常见的结构问题，例如明文凭证，以及 localhost 条目缺少 ansible_connection=local。如果系统中没有 ansible，则会在临时 venv 中自动安装。

用法：

bash scripts/validate_inventory.sh <inventory-file|inventory-directory>

验证阶段：

1. 对所有清单 YAML 文件进行 YAML 语法检查（yamllint）
2. 解析清单 — 使用 ansible-inventory --list 验证主机/组解析
3. 主机图 — 使用 ansible-inventory --graph 显示组层级
4. 结构检查 — 明文密码、本地主机连接设置、group_vars/host_vars 是否存在

references/

security_checklist.md - 全面的 Ansible 安全验证清单，涵盖密钥管理、权限提升、文件权限和命令注入。

best_practices.md - Ansible 编码标准和最佳实践，涵盖 playbook 组织、变量处理、任务命名、幂等性和文档编写。

common_errors.md - 常见 Ansible 错误数据库，包含详细的解决方案和预防策略。

module_alternatives.md - 使用当前替代方案替换已弃用模块的指南。

assets/

.yamllint - 为 Ansible YAML 文件预先配置的 yamllint 规则。

.ansible-lint - 预先配置的 ansible-lint 配置，包含合理的规则设置。

molecule.yml.template - 用于角色测试的 Molecule 配置模板。

工作流示例

示例 1：验证单个 Playbook

User: "Check if this playbook.yml file is valid"

Steps:
1. Run preflight: `bash scripts/setup_tools.sh`
2. Run wrapper: `bash scripts/validate_playbook.sh playbook.yml`
3. If inventory is provided, run check mode: `ansible-playbook -i <inventory> playbook.yml --check --diff`
4. Run security wrappers:
   - `bash scripts/validate_playbook_security.sh playbook.yml`
   - `bash scripts/scan_secrets.sh playbook.yml`
5. If custom modules are detected, run docs lookup workflow (Context7 first, web fallback)
6. Report results with PASS/FAIL/BLOCKED/SKIPPED counts and remediation steps

示例 2：验证 Ansible 角色

User: "Validate my ansible role in ./roles/webserver/"

Steps:
1. Run preflight: `bash scripts/setup_tools.sh`
2. Run role wrapper: `bash scripts/validate_role.sh ./roles/webserver/`
3. This checks:
   - Role directory structure (tasks/, defaults/, handlers/, meta/, etc.)
   - Required main.yml files
   - YAML syntax with yamllint
   - Ansible syntax with ansible-playbook
   - Best practices with ansible-lint
   - Molecule configuration (if present)
4. If `molecule/` exists, attempt Molecule automatically:
   - `bash scripts/test_role.sh ./roles/webserver/`
   - Exit `2`: report `Molecule Status: BLOCKED` with reason, continue remaining checks
   - Exit `1`: report `Molecule Status: FAIL` with debugging guidance
5. Run role security checks:
   - `bash scripts/validate_role_security.sh ./roles/webserver/`
   - `bash scripts/scan_secrets.sh ./roles/webserver/`
6. If custom modules detected, run documentation lookup workflow
7. Provide final report with severity, blockers, and rerun actions

示例 3：生产环境试运行测试

User: "Run playbook in check mode for production servers"

Steps:
1. Verify inventory file exists
2. Run ansible-playbook --check --diff -i production
3. Analyze check mode output
4. Highlight tasks that would change
5. Review handler notifications
6. Flag any security concerns
7. Provide recommendation on safety of applying

示例 4：了解自定义 Collection 模块

User: "I'm using community.postgresql.postgresql_db version 2.3.0, what parameters are available?"

Steps:
1. Try Context7 MCP: `mcp__context7__resolve-library-id("ansible community.postgresql")`
2. If found, query docs with `mcp__context7__query-docs` for `postgresql_db`
3. If not found, use `web.search_query`: "ansible community.postgresql version 2.3.0 postgresql_db module documentation"
4. Extract module parameters (required vs optional)
5. Provide examples of common usage patterns
6. Note any version-specific considerations

示例 5：使用 Molecule 测试角色

User: "Test my nginx role with molecule"

Steps:
1. Check if molecule is configured in role
2. Run preflight (`bash scripts/setup_tools.sh`) and confirm Docker/Podman runtime availability
3. Run `bash scripts/test_role.sh <role-path> [scenario]`
4. If exit code is `2`, mark Molecule `BLOCKED`, report reason, and continue non-Molecule checks
5. If exit code is `1`, inspect converge/verify output and report role issues
6. Analyze idempotency, syntax, and verification outcomes
7. Suggest improvements and exact rerun command

与其他技能集成

此技能可与以下技能配合使用：

• k8s-yaml-validator - Ansible 管理 Kubernetes 资源时使用
• terraform-validator - Ansible 和 Terraform 搭配使用时使用
• k8s-debug - 调试由 Ansible 管理的基础设施

备注

• 按顺序运行各阶段：预检 -> 语法 -> lint/FQCN -> 检查模式 -> Molecule（适用时）-> 安全 -> 参考资料路由 -> 最终报告。
• 默认使用包装脚本作为执行方式；仅在用户要求或包装脚本引导流程受阻时，才改用直接命令。
• 将缺少依赖项/运行时视为 BLOCKED（而非静默跳过），并继续执行其余阶段。
• 对于每一类检测到的问题，都要提供对应的参考指南（common_errors、best_practices、module_alternatives、security_checklist）。
• 对失败或受阻的阶段，始终提供明确的重新运行命令。

完成标准

满足以下条件时，此技能执行即告完成：

• 报告所需工具的预检状态（ansible、ansible-lint，以及在角色测试适用时的 Molecule 运行时状态）。
• 验证使用 PASS、FAIL、BLOCKED 和 SKIPPED 生成确定的阶段结果。
• Molecule 不会导致整个验证流程陷入停滞；应使用备用方案说明报告运行时受阻的情况。
• 明确说明选择包装脚本还是直接命令，并说明理由。
• 参考资料查找与实际发现的错误类别对应，并提供具体的修复建议。