验证与调试现有 Ansible…

当需要校验、lint、审计或调试已有 Ansible 代码时，按预检、语法、lint、FQCN、check mode、Molecule、安全扫描、参考路由和报告流程执行。

适用场景

解决思路

1. 预检：运行 `bash scripts/setup_tools.sh`；命令假设从 skill 根目录 `devops-skills-plugin/skills/ansible-validator` 执行，或使用绝对路径。
2. 预检要求：基线验证需 `ansible`、`ansible-playbook`、`ansible-lint`，推荐 `yamllint`；Molecule 执行需 `molecule` 加可用 runtime（`docker` 或 `podman`）；安全扫描需 `checkov`，缺失时 wrapper 可尝试 bootstrap。
3. 预检确定性回退：若基线工具缺失但 Python + pip 可用，wrapper 脚本自动 bootstrap 临时环境；若 wrapper bootstrap 失败（离线 index、pip 失败、缺 Python），对可用工具运行 direct 命令，将缺失阶段标记 `BLOCKED` 并继续；若 Molecule runtime 不可用（Docker/Podman 缺失或 daemon 未运行），跳过 Molecule 执行，标记 `BLOCKED` 并继续剩余阶段。
4. 默认使用 wrapper 以保证一致行为和回退处理：playbook 语法/lint 用 `bash scripts/validate_playbook.sh <playbook.yml>`；role 结构验证用 `bash scripts/validate_role.sh <role-dir>`；role Molecule 执行用 `bash scripts/test_role.sh <role-dir> [scenario]`；安全扫描用 `bash scripts/validate_playbook_security.sh <path>` 或 `bash scripts/validate_role_security.sh <path>` 加 `bash scripts/scan_secrets.sh <path>`；模块/collection 发现用 `bash scripts/extract_ansible_info_wrapper.sh <path>`。
5. 当用户只要求单一聚焦检查时改用 direct 命令：例如仅 `ansible-playbook --syntax-check`、`ansible-lint`、`yamllint`；当用户明确要求手动分阶段 Molecule 命令时，改用 direct Molecule 命令；当用户要求原始 Checkov 输出格式或自定义 flag 时，直接运行 Checkov。
6. 按 Validation Workflow 顺序执行：0 Preflight；1 识别范围（单 playbook、role、collection、多 playbook/inventory）；2 语法验证（`ansible-playbook --syntax-check`、`yamllint`，报告 PASS/FAIL/BLOCKED）；3 lint 和最佳实践（`ansible-lint`、废弃模块检查、FQCN 检测 `bash scripts/check_fqcn.sh`、角色结构验证，报告问题）；4 Dry-Run 测试（`ansible-playbook --check`，分析变更，报告潜在问题）；5 Molecule 测试（若 role 有 `molecule/` 目录，自动运行 `bash scripts/test_role.sh <role-path> [scenario]`；退出码 2 标记 `BLOCKED`，退出码 1 标记 `FAIL`，无论结果继续剩余验证）；6 自定义模块/collection 分析（提取模块/collection 信息、识别版本、查文档，Context7 优先，`web.search_query` 回退，提供版本特定指导）；7 安全与最佳实践（默认双重扫描：Checkov wrapper + `scan_secrets.sh`；若一个不可用，运行另一个并报告覆盖缺口；验证提权、文件权限、常见反模式）；8 参考路由（将每个错误/警告类映射到匹配 reference 文件，提取具体修复，报告中包含来源章节 + 修复指导）；9 最终报告（必须包含 PASS/FAIL/BLOCKED/SKIPPED 汇总计数、按严重级别分组发现、工具/运行时阻塞及失败命令、达到完整验证覆盖的下一步）。
7. 状态契约：`BLOCKED` 表示因环境/运行时限制无法运行验证；`FAIL` 表示 Ansible 代码或测试失败。
8. 错误类参考路由：YAML parse/format 错误 -> `references/common_errors.md` 的 Syntax Errors，引用匹配的语法修复模式并应用修正后的 YAML 结构；Module/action resolution 错误 -> `references/common_errors.md` 的 Module/Collection Errors，提供安装/版本修复命令（`ansible-galaxy collection install ...`）；Deprecated 或 non-FQCN 模块使用 -> `references/module_alternatives.md`，提供精确 FQCN/模块替换；Template/variable 错误 -> `references/common_errors.md` 的 Template/Variable Errors 和 `references/best_practices.md` 的 Variable Management，推荐 `default()`、`required()` 或类型转换修复；Connection/inventory/privilege 错误 -> `references/common_errors.md` 的 Connection、Inventory、Privilege 章节，提供修正后的 inventory/auth/become 配置；Security policy 失败（CKV_*）-> `references/security_checklist.md`，将失败策略映射到安全 task 重写；Hardcoded secrets -> `references/security_checklist.md` 的 Secrets Management，替换为 Vault/env/external secret manager 方案；Role structure/idempotency 警告 -> `references/best_practices.md`，提供角色布局或幂等性修复步骤。外部文档查找触发：若问题涉及自定义/私有 collection 或未知模块参数且本地未覆盖，运行模块发现 + 文档查找。
9. YAML 语法验证：运行 `yamllint playbook.yml`、`yamllint -c .yamllint .`、`ansible-playbook playbook.yml --syntax-check`；检测缩进错误、无效 YAML 语法、重复键、行尾空格、行长度违规、缺失冒号或引号；最佳实践：始终先运行 yamllint 再运行 ansible-lint，统一使用 2 空格缩进，在 `.yamllint` 中配置规则，先修 YAML 语法错误再修 Ansible 特定问题。
10. Ansible Lint：运行 `ansible-lint playbook.yml`、`ansible-lint .`、`ansible-lint -t yaml,syntax playbook.yml`、`ansible-lint -x yaml[line-length] playbook.yml`、`ansible-lint -f pep8 playbook.yml`、`ansible-lint -L`；检测废弃模块/语法、缺失 task name、`command` 与 `shell` 误用、未加引号的模板表达式、应变量化的硬编码值、缺失 `become` 指令、低效 task 模式、Jinja2 模板错误、变量误用、role 依赖问题；严重级别为 Error（必须修）、Warning（应该修）、Info（考虑修）；自动修复：`ansible-lint --fix` 可自动修复部分问题，应用前审查变更，部分问题需手动处理。
11. Security Scanning (Checkov)：运行 `bash scripts/validate_playbook_security.sh playbook.yml`、`bash scripts/validate_playbook_security.sh /path/to/playbooks/`、`bash scripts/validate_role_security.sh roles/webserver/`、`checkov -d . --framework ansible`、`checkov -d . --framework ansible --output json`、`checkov -d . --framework ansible --skip-check CKV_ANSIBLE_1`；检测证书验证、HTTPS 强制、包签名、云安全配置、合规映射、网络安全等；典型修复示例：`validate_certs: false` 改为 `validate_certs: true` 或省略（默认 true）；Checkov 与 ansible-lint 互补，最佳实践是同时运行 `bash scripts/validate_playbook.sh playbook.yml` 和 `bash scripts/validate_playbook_security.sh playbook.yml`；安装可用 `pip3 install checkov`；使用时机：生产部署前、CI/CD 自动化安全检查、敏感基础设施、合规审计、下载文件或安装包、用 Ansible 管理云资源。
12. Playbook Syntax Check：运行 `ansible-playbook playbook.yml --syntax-check`、`ansible-playbook -i inventory playbook.yml --syntax-check`、`ansible-playbook playbook.yml --syntax-check -e @vars.yml`、`for file in *.yml; do ansible-playbook "$file" --syntax-check; done`；验证 YAML 解析、playbook 结构、task 定义、变量引用、模块参数语法、Jinja2 模板语法、include/import 语句；错误处理：解析错误消息定位具体问题，检查模块名拼写，验证变量定义，确保正确缩进，检查 include/import 文件路径。
13. Dry-Run Testing (Check Mode)：运行 `ansible-playbook -i inventory playbook.yml --check`、`ansible-playbook -i inventory playbook.yml --check --diff`、`ansible-playbook -i inventory playbook.yml --check -v`、`ansible-playbook -i inventory playbook.yml --check --limit webservers`、`ansible-playbook -i inventory playbook.yml --check --tags deploy`、`ansible-playbook -i inventory playbook.yml --check --step`；分析 task 变更（`ok`、`changed`、`failed`、`skipped`）、diff 输出、handlers 通知与重启、失败 task；注意限制：不是所有模块支持 check mode，部分 task 依赖前序变更，可能不能准确反映所有变更，状态性操作可能显示意外结果；安全考虑：真实执行前始终运行 check mode，仔细审查 diff 输出，先在非生产测试，验证变更合理，检查意外副作用。
14. Molecule Testing：自动尝试策略：验证任何带 `molecule/` 目录的 Ansible role 时，自动尝试 `bash scripts/test_role.sh <role-path> [scenario]`；工作流：`cd roles/myrole` 后 `molecule init scenario --driver-name docker`、`molecule list`、`molecule test`、`molecule create`、`molecule converge`、`molecule verify`、`molecule destroy`、`molecule test -s alternative`、`molecule --debug test`、`molecule converge` 后 `molecule login`；测试序列：dependency、lint、cleanup、destroy、syntax、create、prepare、converge、idempotence、side_effect、verify、cleanup、destroy；检查 `molecule/default/molecule.yml` 的 dependency、driver、platforms、provisioner、verifier；验证器可用 Ansible、Testinfra、Goss；常见错误：driver 未安装、Python 依赖缺失、平台镜像不可用、网络连接问题、driver 权限不足；跳过/回退策略：无 `molecule/` 时标记 `SKIPPED` 并继续；`test_role.sh` 退出 2 标记 `BLOCKED`（缺失/不可用 runtime 依赖）并继续；退出 1 标记 `FAIL`（role/test 问题）并继续；绝不因 Molecule 阻塞而停止完整验证报告；使用给定 reporting language 报告 BLOCKED 原因、fallback 和下一步。
15. Custom Module and Collection Documentation Lookup：触发条件：遇到不熟悉模块用法、自定义/私有 collection、模块特定错误、新模块参数、版本兼容检查、废弃模块替代；检测工作流：用 `scripts/extract_ansible_info_wrapper.sh` 解析 playbook 和 role，识别模块使用和 collections，从 `requirements.yml` 提取版本约束，识别 collection namespace（如 `community.general`、`ansible.posix`），从 `requirements.yml` 或 `galaxy.yml` 确定 collection 版本，区分自定义/私有与公共 collection；文档查找顺序：公共 collection/module 先用 `mcp__context7__resolve-library-id` 和 `mcp__context7__query-docs`；Context7 无合适结果则用 `web.search_query` 带版本查询，优先官方 docs.ansible.com、galaxy.ansible.com、vendor docs；自定义/私有模块先查仓库内文档（README、module docs、role docs），再用定向 web 搜索带 collection/module/version 词；始终在最终指导中报告来源 + 版本上下文。搜索查询模板：`"[module-name] ansible module version [version] documentation"`、`"[module-name] ansible [module-type] example"`、`"ansible [collection-name].[module-name] parameters"`、`"ansible collection [collection-name] version [version]"`、`"[collection-namespace].[collection-name] ansible documentation"`、`"ansible galaxy [collection-name] modules"`、`"ansible [module-name] error: [error-message]"`、`"ansible [collection-name] module failed"`。版本兼容检查：比较所需 collection 版本与可用版本，识别废弃模块或参数，建议升级路径，警告版本间破坏性变更，检查 Ansible core 版本兼容性。常见 collection 来源：Ansible Galaxy、Red Hat Automation Hub、GitHub、内部仓库。
16. Security and Best Practices Validation：Secrets Detection：运行 `grep -r 'password:' *.yml`、`grep -r 'secret:' *.yml`、`grep -r 'api_key:' *.yml`、`grep -r 'token:' *.yml`；修复用 Ansible Vault、环境变量或外部 secret 管理。Privilege Escalation：检查不必要的 `become: yes`、缺失 `become_user` 指定、过度宽松 sudo 规则、整个 playbook 以 root 运行。File Permissions：检查 world-readable 敏感文件、缺失 `mode` 参数的 file/template task、错误 ownership 设置、敏感文件未用 vault 加密。Command Injection：检查 shell/command 模块中未验证变量、用户输入缺少 `quote` filter、直接在命令字符串使用 `{{ var }}`。Network Security：检查未加密协议（HTTP 代替 HTTPS）、缺失 SSL/TLS 验证、服务暴露在 `0.0.0.0`、不安全默认端口。
17. Best Practices：Playbook Organization：逻辑任务分离、可复用 roles、清晰目录结构、有意义的 playbook 名称。Variable Management：Vault 加密敏感数据、清晰变量命名约定、变量优先级意识、group/host vars 组织、使用 `default()` filter 提供默认值。Task Naming：描述性 task 名称、一致命名约定、动作导向描述、名称中包含变更资源。Idempotency：所有 task 应幂等、使用合适模块替代 command/shell、check mode 兼容、command task 使用 `creates`/`removes`、避免不必要 `changed_when: false`。Error Handling：使用 `failed_when` 自定义失败条件、实现 `block/rescue/always` 错误恢复、设置适当 `any_errors_fatal`、谨慎使用 `ignore_errors`。Documentation：每个 role 有 README、在 `defaults/main.yml` 文档化变量、在 `meta/main.yml` 写 role metadata、playbook 头部注释。
18. 工具前置：运行 `ansible --version`、`ansible-playbook --version`、`ansible-lint --version`、`yamllint --version`、`molecule --version`、`docker --version` 和 `docker info`，或 `podman --version` 和 `podman info`；安装缺失工具示例：`pip install ansible ansible-lint yamllint ansible-compat`、`pip install molecule molecule-docker`、`pip install molecule molecule-podman`；最低版本：Ansible >= 2.9（推荐 >= 2.12）、ansible-lint >= 6.0.0、yamllint >= 1.26.0、molecule >= 3.4.0（若测试 role）；工具缺失执行策略：若 `ansible`/`ansible-lint` 缺失，wrapper（`validate_playbook.sh`、`validate_role.sh`）尝试临时 venv bootstrap；若 Molecule runtime（`docker info` 或 `podman info`）不可用，Molecule 标记 `BLOCKED` 并继续非 Molecule 检查；若 `checkov` 缺失，安全 wrapper 尽可能 bootstrap，否则运行 `scan_secrets.sh` 并报告安全覆盖减少；可选工具：`ansible-inventory`、`ansible-doc`、`jq`。
19. 错误排查：Module Not Found -> 用 `ansible-galaxy` 安装所需 collection，检查 `collections/requirements.yml`，验证 collection namespace 和 name。Undefined Variable -> 在 vars、defaults 或 group_vars 中定义变量，检查变量优先级，对可选变量用 `default()` filter，验证变量文件已包含。Template Syntax Error -> 检查 Jinja2 模板语法，验证变量类型与 filter 匹配，确保正确转义引号，单独测试模板渲染。Connection Failed -> 验证 inventory 主机可达性，检查 SSH 配置和密钥，验证 `ansible_host` 和 `ansible_port`，用 `ansible -m ping` 测试。Permission Denied -> 添加 `become: yes` 提权，验证 sudo/su 配置，检查文件权限，验证用户有必需权限。Deprecated Module -> 查看 ansible-lint 输出中的替代建议，查阅模块文档找替代，更新到推荐模块，用新模块测试功能。
20. 脚本使用：`setup_tools.sh` 预检 Ansible validator 依赖，验证基线工具和 Molecule runtime 就绪并提供安装指导；`extract_ansible_info_wrapper.sh <path-to-playbook-or-role>` 自动处理 PyYAML 依赖，输出包含 modules、collections、versions 的 JSON；`extract_ansible_info.py` 被 wrapper 调用，解析 Ansible playbook 和 role 提取模块使用、collection 依赖和版本信息；`validate_playbook.sh <playbook.yml>` 运行 syntax check、yamllint、ansible-lint，缺失时自动在临时 venv 安装；`validate_playbook_security.sh <playbook.yml|dir>` 用 Checkov 扫描 playbook 安全漏洞，自动在临时 venv 安装 checkov；`validate_role.sh <role-directory>` 检查 role 目录结构、各目录 main.yml、YAML 语法、Ansible 语法、ansible-lint 最佳实践、Molecule 测试配置；`validate_role_security.sh <role-directory>` 用 Checkov 扫描整个 role 目录安全；`test_role.sh <role-directory> [scenario]` 包装 Molecule 测试并自动安装依赖，退出码 2 表示环境/runtime 阻塞，退出码 1 表示 role/test 失败；`scan_secrets.sh <path>` 用 grep 模式匹配检测硬编码密码、凭证、API key、token、AWS access key、数据库连接串、私钥，必须始终与 Checkov 一起运行；`check_fqcn.sh <path>` 扫描短模块名并推荐迁移到 `ansible.builtin.*` 或合适 collection namespace；`validate_inventory.sh <inventory-file|dir>` 检查 YAML 语法、`ansible-inventory --list` 解析、`ansible-inventory --graph` 分组层级、结构问题如明文密码和 localhost 缺失 `ansible_connection=local`。
21. References 和 assets 使用：`references/security_checklist.md` 覆盖 secrets 管理、提权、文件权限、命令注入的安全验证清单；`references/best_practices.md` 覆盖 playbook 组织、变量处理、task 命名、幂等性、文档的编码标准；`references/common_errors.md` 常见 Ansible 错误、详细解决方案和预防策略；`references/module_alternatives.md` 废弃模块到当前替代的指南；`assets/.yamllint` 预配置 yamllint 规则；`assets/.ansible-lint` 预配置 ansible-lint 规则；`assets/molecule.yml.template` Molecule 配置模板。
22. Workflow 示例执行：单 playbook：运行 preflight -> `bash scripts/validate_playbook.sh playbook.yml` -> 若提供 inventory 运行 `ansible-playbook -i <inventory> playbook.yml --check --diff` -> 运行 `bash scripts/validate_playbook_security.sh playbook.yml` 和 `bash scripts/scan_secrets.sh playbook.yml` -> 若检测到自定义模块则运行文档查找 -> 报告 PASS/FAIL/BLOCKED/SKIPPED 计数和修复步骤。Role：运行 preflight -> `bash scripts/validate_role.sh ./roles/webserver/` -> 若 `molecule/` 存在自动运行 `bash scripts/test_role.sh ./roles/webserver/`，退出码 2 报告 `Molecule Status: BLOCKED` 并继续，退出码 1 报告 `Molecule Status: FAIL` 并给出调试指导 -> 运行 `bash scripts/validate_role_security.sh ./roles/webserver/` 和 `bash scripts/scan_secrets.sh ./roles/webserver/` -> 若检测到自定义模块则运行文档查找 -> 提供最终报告含严重级别、阻塞和 rerun 动作。生产 dry-run：验证 inventory 文件存在 -> `ansible-playbook --check --diff -i production` -> 分析 check mode 输出 -> 高亮会变更的 task -> 审查 handler 通知 -> 标记安全问题 -> 给出应用安全性的建议。自定义 collection：先用 Context7 MCP `mcp__context7__resolve-library-id('ansible community.postgresql')`，若找到则用 `mcp__context7__query-docs` 查 `postgresql_db`，否则用 `web.search_query('ansible community.postgresql version 2.3.0 postgresql_db module documentation')` -> 提取模块参数（必需 vs 可选）-> 提供常见用法示例 -> 注明版本特定注意事项。Molecule 测试：检查 role 中是否配置 molecule -> 运行 preflight 并确认 Docker/Podman runtime -> `bash scripts/test_role.sh <role-path> [scenario]` -> 退出码 2 标记 `BLOCKED` 并继续非 Molecule 检查 -> 退出码 1 检查 converge/verify 输出并报告 role 问题 -> 分析幂等、语法和验证结果 -> 建议改进和精确 rerun 命令。
23. 与其他技能集成：当 Ansible 管理 Kubernetes 资源时与 `k8s-yaml-validator` 组合；当 Ansible 和 Terraform 一起使用时与 `terraform-validator` 组合；当调试 Ansible 管理的基础设施时与 `k8s-debug` 组合。
24. Notes：按顺序运行阶段：preflight -> syntax -> lint/FQCN -> check mode -> Molecule（适用时）-> security -> reference routing -> final report；默认使用 wrapper 脚本，仅当用户要求或 wrapper bootstrapping 被阻塞时切换到 direct 命令；将缺失依赖/runtime 视为 `BLOCKED` 而非静默 skip，并继续剩余阶段；对每个检测到的问题类包含映射 reference 指导（`common_errors`、`best_practices`、`module_alternatives`、`security_checklist`）；始终为失败或阻塞阶段包含显式 rerun 命令。
25. Done Criteria：执行完成条件：报告必需工具的 preflight 状态（`ansible`、`ansible-lint`，以及 role 测试范围包含时的 Molecule runtime 状态）；验证产生确定性阶段结果，使用 `PASS`、`FAIL`、`BLOCKED`、`SKIPPED`；Molecule 绝不使完整验证流程死胡同，阻塞 runtime 条件用 fallback 语言报告；wrapper vs direct 命令选择明确且合理；reference 查找与实际发现的错误类关联，并提供具体修复指导。

适用边界 · 注意事项

• 不适用于生成新 Ansible 代码或从零编写 playbook/role；此技能聚焦验证和调试已有 Ansible 代码。
• 不适用于非 Ansible 文件（如纯 Kubernetes YAML、Terraform），除非与其他验证技能组合使用。
• 如果环境禁止安装工具或运行容器，且无法接受 Molecule/安全扫描阶段被标记为 `BLOCKED`，则不适合期望完整覆盖验证。