---

name: config-as-code-spec description: | AI Workspace Infra Config-as-Code and Ansible standards. Use when changing playbooks, roles, inventories, variables, templates, scripts, migration/ restore logic, or CI/CD delivery of Ansible configuration in playbooks, platform-ops-toolkit, or observability.svc.plus. Covers CMDB-first delivery, Vault/OIDC secrets, idempotency, safe cutovers, and IaC handoff.

Config-as-Code (Playbooks) Specification

本规范适用于 playbooks/ 下的 Ansible 剧本、角色、inventory、变量、模板、脚本及其 CI/CD 调用方式，也适用于调用这些能力的 platform-ops-toolkit 与 observability.svc.plus。目标是让配置交付可追溯、可复用、幂等安全、与 IaC 一致并且密钥零落盘。

“MUST/必须”为强制要求；“SHOULD/应当”为默认要求。偏离 MUST 或 SHOULD 时，必须在 PR 中说明原因、风险和补偿措施。

先阅读 AI Workspace Infra Repository Map，再确认改动属于 playbooks 的执行层、platform-ops-toolkit 的编排层，还是 observability.svc.plus 的独立部署层。不得把主机配置塞进 Terraform、GitOps 或 artifacts 仓库。

1. Repository organization and style

• 新增或修改入口剧本 MUST 遵循其所属仓库和领域的既有命名约定。不得仅为统一风格进行跨目录或仓库级重命名；如确需迁移命名，必须作为独立兼容性变更，提供引用更新、验证与回滚方案。
• 入口剧本只负责编排：选择目标、声明角色、少量输入校验和标签。业务实现放入 roles/。
• 角色按需使用 defaults/、tasks/、handlers/、templates/、files/、vars/、meta/、README.md。默认变量放 defaults/main.yml；不可被调用方覆盖的内部常量才放 vars/main.yml。
• 新增或实质修改的角色 MUST 有 README，说明用途、输入变量、依赖、目标组、执行示例和回滚方式。
• 保留相邻文件的 YAML、Jinja、Shell 和 Markdown 风格；只格式化涉及的文件，不做无关全仓重排。

2. Inventory and IaC boundary

2.1 CMDB is the delivery source of truth

• IaC 驱动的交付 MUST 使用 inventory/terraform_cmdb.py，其数据来自 Terraform 输出的 cmdb.json。
• 新建、替换、扩容、缩容或迁移后的主机，MUST 先更新 Terraform 输出，再执行 Ansible。
• Ansible 剧本、角色、模板和变量文件不得硬编码公有主机 IP、主机名、云实例 ID 或环境节点列表。loopback、监听地址、容器网段和协议默认端口等非目标身份配置可以保留，但必须语义明确。
• 静态 inventory 只用于明确标记的 legacy 或 manual 路径，不得作为 CI/CD 或常规交付默认清单。

2.2 Connect-time preflight

新机或资源变更后的交付 MUST 在连接前执行并记录：

ansible-inventory -i inventory/terraform_cmdb.py --host <hostname>
ansible-inventory -i inventory/terraform_cmdb.py --graph
ansible -i inventory/terraform_cmdb.py <hostname> -m ping

检查 ansible_host 是否来自当前 Terraform 输出、业务组/环境组是否正确、cmdb_instance_id 是否匹配云侧实例、所需 host_vars 是否完整，以及目标选择器是否只包含预期主机。CMDB 缺失、为空、字段不完整或目标不存在时，动态 inventory MUST 失败退出，不得静默返回空 inventory。

2.3 Responsibilities

• Terraform 负责云主机、网络、安全组、负载均衡、DNS 基础资源及状态输出。
• Ansible 负责操作系统配置、软件安装、服务部署、运行时配置和应用级验证。
• 跨 IaC、CI 与 Playbooks 的业务敏感状态，其权威来源和交接媒介 MUST 为 Vault；不得由 GitHub Secret、artifact、临时文件或手工环境变量替代。
• GitOps 中的 resources/<project>/<env>/<provider>/*.yaml 是非敏感的期望状态声明；它描述项目、环境、服务商和资源参数，不承载密码、Token、私钥或运行时配置。IaC 渲染器从该路径读取声明并输出 CMDB，Ansible 只消费 CMDB 与 Vault，不得反向修改或在 playbooks/ 中维护第二份拓扑。
• 任何跨仓库交接都必须保留同一个 <project>/<env>/<provider> 元组、提交 SHA 和状态标识。环境或服务商改变时创建新的声明路径和独立 state，禁止通过默认值把 UAT、生产或不同云账户混到同一清单。

3. Credentials and Vault

• 禁止将密码、Token、私钥、数据库连接串或 Vault password file 提交仓库、写入 GitHub Secret、落入日志或生成到临时文件。
• CI/CD MUST 使用 GitHub OIDC 向 Vault 换取环境专属短期凭证；Vault role 按环境隔离，例如 github-actions-<repo>-sit、-uat、-prod。
• 环境专属 Vault 路径 MUST 由单一运行时变量（如 VAULT_ENV_PATH）派生；不得在 playbook、role 或 workflow 中分散硬编码 sit、uat、prod 路径。
• 运行时环境变量仅可承载 OIDC 登录参数或本次 Job 从 Vault 读取后的短期值。变量优先级为：运行时环境变量 → Vault 查询 → 安全的非敏感默认值（如 127.0.0.1）。凭证、目标主机、环境路径和依赖服务端点等必填值缺失时 MUST 通过 assert 或 fail 明确失败；绝对禁止在 Playbook、Ansible defaults/main.yml、模板或角色中硬编码生产域名、IP 或生产数据库 DSN 作为退回 fallback。模板中的依赖服务 URL 必须根据当前环境/主机的核心网络域名配置动态派生。
• 涉及敏感变量的任务使用 no_log: true，但不得因此隐藏安全的控制流诊断；应暴露状态码、服务状态和失败前置条件，并遮蔽秘密值。
• 发现泄露时 MUST 先吊销并轮换，再用 git filter-repo 清理历史并记录影响范围；只删除文件不算完成处置。

4. Playbook and role implementation

• 优先使用幂等 Ansible 模块；超过三行、包含条件/循环/状态判断或业务逻辑的 Shell/Python MUST 放在角色 files/ 的可执行脚本中，或实现为 Ansible module，不得内嵌在 task/workflow 中。
• 外部脚本 MUST 有明确输入、失败退出码、可重复执行语义和最小权限。
• 可能中断的操作 SHOULD 支持 tags，至少区分 install、configure、validate，必要时增加 rollback。
• 服务配置变更 MUST 使用 handler 重启或 reload，禁止无条件重启；生成配置后先做语法/健康检查，再触发服务重载。
• 对必填变量在 role 开始处使用可读的 assert 校验；变量名以角色或领域前缀命名，避免泛化的 port、host、token。
• 模板通过变量表达环境差异；多主机配置从 groups 与 hostvars 派生，不维护第二份静态节点清单。
• 使用 ansible.builtin.* 全限定模块、显式 changed_when/failed_when，并保持迁移/备份/恢复可重复和可重启。

4.1 Binary artifact download and version pinning

• Immutable Pinning: Playbooks and Ansible roles downloading remote binary dependencies MUST pin to verified, immutable release versions or SHAs (e.g. v0.6.0), or pull from controlled internal artifact repositories (GHCR, Vault, or mirror stores).
• No Unverified Dynamic Daily Tags: Dynamic date-based release tags (such as daily-build-YYYY.MM.DD) MUST NOT be hardcoded as default download URLs in deployment playbooks without artifact existence verification or explicit mirror fallbacks.
• Preflight & Error Handling: Tasks using ansible.builtin.get_url to fetch binaries MUST check HTTP status / artifact availability, provide clear failure messaging when release assets are missing (avoiding ambiguous 404 errors), and support alternative mirror/fallback URLs where appropriate.

删除、清库、覆盖配置、重建集群、DNS 切换和源机清理等破坏性操作 MUST：使用显式布尔确认变量；任务名标明影响；先做范围断言和备份/快照检查；默认不可执行。

5. Resize, migration, and recovery handoff

replacement VPS 的交付顺序 MUST 为：备份或逻辑迁移 → 新主机容量与健康检查 → Terraform state 接管 → 刷新 cmdb.json/inventory → Ansible 部署 → 服务健康检查。DNS 切换和旧机删除是最后的独立确认阶段。

当目标磁盘小于源盘时，整机快照恢复不可行；应使用经过验证的数据库、Vault 和业务文件级备份/恢复，不得反复执行必然失败的快照恢复。迁移剧本应保持 source/target 阶段边界，恢复失败时保留回滚点。

6. CI/CD and environment routing

环境只能由 Git 事件决定：

Git event	Environment
pull_request	sit
push to main or release/*	uat
vMAJOR.MINOR.PATCH tag	prod

• workflow 不得内嵌复杂 Shell/Python；逻辑放在 .github/scripts/ 的可执行脚本中。
• workflow MUST 显式指定 inventory/terraform_cmdb.py，不得依赖 runner 的默认 ansible.cfg 或静态生产 inventory。
• 部署前执行 inventory 校验与 ansible-playbook --syntax-check；部署后执行服务健康检查。
• 执行记录关联提交、目标环境、目标主机、CMDB instance ID 和验证结果。

7. Quality gates and PR minimum

合并前 MUST 通过：YAML 语法与 Ansible --syntax-check；修改角色的 README 和变量说明同步更新；新增目标选择器的 CMDB 验证；明文凭证、静态生产节点地址和 Vault password file 检查；legacy/manual inventory 回归确认。服务变更至少有一次可验证 health check；破坏性/迁移变更提供备份、回滚和演练说明。

PR 描述 MUST 包含交付结果与影响范围、Issue/变更单或基础设施变更链接、目标环境与 CMDB 主机/组选择方式、验证命令和结果、回滚方式，以及任何偏离本规范的原因、风险和补偿措施。

8. Forbidden patterns

• CI/CD 默认使用 inventory.ini 或其他静态生产 inventory。
• 剧本中写死云主机 IP、实例 ID 或外部节点列表。
• Ansible 创建 Terraform 职责内的云网络、负载均衡或安全组。
• 在 task 或 workflow 中内嵌复杂脚本。
• 使用 .vault_pass.txt、长期 Vault Token 或 GitHub Secret 保存业务凭证。
• 未经显式确认执行删除、覆盖、清库或迁移切换。
• 为统一风格进行无业务价值的全仓重命名。