specsfy-specialist-ansible

Ansible

适用场景

• 当项目包含 playbook、role、inventory、ansible.cfg 或 collections 的 requirements.yml/galaxy.yml 时触发。
• 在针对共享环境运行现有自动化之前，也触发以检查其是否真正 幂等。
• 不要用于编排集群中已容器化的服务；此时应使用 $specsfy-specialist-docker-swarm；这里的 Ansible 用于主机 配置，而非 Swarm 服务编排。
• 当运行 playbook 是部署流水线中的一个步骤时，与 $specsfy-specialist-delivery-engineering 配合使用。

工作流

请先说明计划、汇报进度，并在结束时列出已更改的文件和 已执行的验证。对于公开文本，请遵循使用项目适用的 《共享编辑规范》。

1. 进行完整发布或部署时，应在 $specsfy-specialist-deploy 的协调下工作，并使用编排器已准备好的 SEMVER、镜像和清单。
2. 在进行任何会产生影响的执行之前，确认主机、组、目标环境、连接 方法，以及确切的主机范围。
3. 使用 ./deploy check-hosts 以表格形式列出所有主机，并在首次执行远程 task 前确认 ping 模块。使用 ./deploy sync-keys 仅向 deploy 用户添加公钥，不删除 authorized_keys 中的现有条目。
4. 检查适用的变量优先级（见 references/standards.md 中的表格）以及固定的 collections 和 ansible-core 版本。
5. 使用幂等模块和职责单一的 role 来建模期望状态。
6. 使用 Ansible Vault 或外部提供方（从受管保险库中 lookup）保护 secrets；切勿以明文形式存放在仓库中。
7. 由 Agent 执行时，应在部署编排器下使用 ./deploy run --non-interactive。遵循 已提供的文件、脚本、Vault IDs 和原生配置。若没有外部来源，请指导用户 在人工操作的终端中运行 ./deploy configure-vault。不要通过对话索取或读取密码。 ./deploy run 命令仍需手动执行，输入内容会被隐藏。
8. 验证语法、ansible-lint、check mode 和 diff，且不要在 输出中泄露 secrets。
9. 在可丢弃环境中测试 role，并重复相同的执行，以证明第二次运行不会报告 changed。
10. 在生产环境应用时，使用与变更范围相符的序列化（serial）、限制（--limit） 和停止规则（max_fail_percentage/any_errors_fatal）。

规范

• 创建单独的预检，以在执行会写入的 play 前检查控制器版本、目标系统、Docker 访问权限、manager 角色、registry 登录状态、collections、不可变镜像和 Docker Secrets。
• 当 stack 使用 Cloudflare Tunnel 时，从 vault_cloudflare_tunnel_token 创建 cloudflare_tunnel_token，并设置 no_log: true。stack 只接收 Docker Secret 的名称。
• 将带版本控制的 manifests 复制到主机上的稳定目录，用 docker stack config 验证每个 manifest，并按依赖顺序发布 stacks。
• 每次发布后，查询副本，直到达到收敛状态；如果超过限定的重试次数，则以错误结束。不能仅凭 deploy 模块的返回结果就判定成功。
• 如实处理 check mode：检查类 tasks 可以使用 check_mode: false；会更改状态的 tasks 应跳过或支持模拟。即使不部署 stacks，预检也必须有用。
• 使用 FQCN（ansible.builtin.copy，而不是 copy）和声明式模块；只要存在等效的幂等模块，就应避免使用 shell/command。
• 为 tasks 和 handlers 起可执行的名称（name: 描述产生的效果，而不是模块）；只有 task 确实更改状态时才通知 handler。
• 将 defaults/main.yml（由 role 的使用者配置）、vars/main.yml（内部使用，不应被覆盖）和 secrets（Vault 或外部 lookup）分别放在不同文件中。
• 在 requirements.yml 中固定 collections 的版本，并在更新前验证其与已安装 ansible-core 的兼容性矩阵。
• 仅在需要准确表达命令语义时使用 changed_when/failed_when；绝不能用它们掩盖真实故障，也不能让总是报告变更的 shell/command 假装具有幂等性。
• 限制权限（仅在需要的 task 上使用 become），并对任何处理 secret 的 task 使用 no_log: true，即使该值看起来在日志中无害。
• 当 task 会在主机之间产生副作用时（例如某项服务一次只能重启一台主机），不要依赖偶然的主机顺序或默认并行执行；应在这些情况下显式使用 serial 和 throttle。

反模式

• 使用不带 creates、removes 或显式 changed_when 的 shell/command：即使最终状态完全相同，该 task 每次都会报告 changed；这会妨碍在一次执行中判断“实际发生了哪些变化”，并掩盖非幂等的自动化。

• 无条件通知 handler（不在仅于状态发生变化时触发 notify 的 task 中）：每次执行都会重启服务，包括没有任何变化时，从而造成不必要的服务中断。

• 仅通过通用 group_vars 解析生产/预发布环境变量，而不检查实际优先级：命令行中的 -e 或更具体的 host_vars 可能会悄无声息地覆盖预期值。

• Vault 意外解密后被提交，或将 secret 插入 debug:/日志中但未使用 no_log：即使源文件已正确加密，secret 仍会泄露到 Git 历史记录或执行输出中。 ## 验证

• 在进行任何实际应用之前，运行 ansible-playbook --syntax-check、ansible-lint 和 --check --diff（检查模式），并确认 diff 不会暴露机密。

• 在同一目标上连续运行两次：第二次不应报告任何 task 为 changed；这是验证幂等性的实际依据，而不是目视检查代码。

• 测试 handlers（服务确实会在应该重启时重启）、templates（按环境正确渲染）以及部分失败（某台主机在批次中途失败时，any_errors_fatal、max_fail_percentage 的行为符合预期）。

• 在进行任何远程变更之前，明确确认所用的 inventory 和 --limit；绝不能默默默认“在所有主机上运行”。

• 没有完成上述连续两次运行和检查模式验证，就不要声称某个 role“幂等”或“安全”；阅读 playbook 不能代替在可丢弃环境中实际运行。

## 相关 Skills

• $specsfy-specialist-server-report 通过 Ansible 只读采集日志、服务和磁盘使用情况，并按主机生成报告。

• $specsfy-specialist-deploy 协调完整的服务器自动化；此 skill 负责 roles 和 Ansible playbook。

• $specsfy-specialist-versioning 使 SEMVER 与自动化所传输的镜像和清单保持一致。

• 当由 Ansible 配置的主机加入 Swarm 集群时使用 $specsfy-specialist-docker-swarm；Ansible 准备节点，Swarm 在其中编排服务。

• 当 playbook 执行是包含环境间晋级的流水线步骤时，使用 $specsfy-specialist-delivery-engineering。

• 对于机密管理、凭证轮换和已配置主机加固的审查，使用 $specsfy-specialist-application-security。

• 在应用自动化之前，使用 $specsfy-specialist-debian-server 配置 APT、SSH、sysctl、systemd、防火墙和 Docker Engine。

请阅读 references/standards.md，了解 roles 结构、变量优先级、幂等性、运维安全和测试命令；其中包含 Ansible 官方文档的来源。