qinglong/docs/adr/ADR-0272-bounded-authorized-cluster-automation-inspection.md

ADR-0272：有界且授权原子的 Cluster Automation Inspection

• 状态：Accepted
• 日期：2026-08-04
• 关联：D-85、D-207、D-208、D-239、D-241、D-242、D-253、ADR-0259

上下文

Cluster Automation Management 已能通过独立的 TLS 1.3、mTLS、用途绑定 OIDC 进程发布 TaskDefinition 与 Trigger，但部署者无法通过同一受支持产品面检查当前定义或做有界列表。让用户直接查询 PostgreSQL、把读取能力放进常驻 cluster-control，或返回 Task/Trigger 的完整 spec，都会分别绕过 Policy/audit、扩大 runtime authority，或泄漏脚本正文和调度表达式。

读取也存在撤权竞态：仅在事务外完成 Policy precheck，然后读取 Task/Trigger，会允许 Project、RoleBinding 或 Identity 在两个动作之间变化。另一方面，Edge/Standalone 已有短生命周期本机入口，不能为了 Cluster 能力给路由设备增加 listener、Pool 或依赖闭包。

决策

1. 在既有 ql3-automation-manage 与 ql3-automation-client 中增加 task.inspect、task.list、trigger.inspect、trigger.list；不新增 workspace package、进程、端口、 Pool、migration、表、timer 或 watcher。
2. 所有读取继续要求 TLS 1.3、mTLS、automation-management 用途绑定 OIDC 与 strong User；Task 使用 task.read，Trigger 使用 trigger.read。request 必须携带独立 UUID v4 auditEventId；列表上限复用 Runtime Core 的 256 硬上限和稳定 keyset cursor，禁止 offset 与无界列表。
3. 新的 Runtime Core administration-source contract 只表达授权后的 inspect/list，不赋予 mutation。PostgreSQL adapter 在一个 SERIALIZABLE 快照事务中复验 exact active Project 与 latest active RoleBinding version、拒绝重复 auditEventId、 读取 current head/一页结果、append-only 写 allowed audit，再提交。
4. PostgreSQL 读取必须通过独立只读 PostgresTaskDefinitionSource/PostgresTriggerSource 执行；management service 不取得裸 SQL，runtime/control 不取得 automation-manager 权限。事务失败、围栏变化、重复审计或 存储损坏均失败关闭。
5. 产品响应只返回低敏 summary：稳定 ID、current revision、kind/enabled、content digest、更新时间与 Trigger 的 Task pin；不返回 name、description、labels、spec、mutationId、createdAt、Principal、 authenticationId、Policy reason 或 audit identity。不存在返回显式 absent，列表始终返回固定形状的 tasks|triggers/truncated/next。
6. Edge/Standalone 保持现有短生命周期本机入口和零 Cluster 常驻成本。Cluster HA 继续使用既有两个 management Pod、每 Pod Pool 2、port 8445 与已有数据库角色；本决策不把管理面装入路由 Profile。
7. 读取不是弱一致的“免费查询”：每次 inspect/list 都必须原子持久化 allowed audit。生产 HA 使用 synchronous_commit=remote_apply 时，如果主库已提升但尚无同步备库，读取会在事务超时后失败关闭， 不允许为了查询可用性绕过审计耐久性或降为异步提交。旧主完成 pg_rewind、以只读同步备库重入后， 同一产品入口恢复成功；客户端应以新的 request/audit identity 重试。

被拒绝的方案

• 让 Cluster Control 直接读取 Automation 表：扩大常驻执行面的数据库权限与攻击面。
• 读取不记 audit：无法解释谁在何时枚举了可执行定义。
• Policy precheck 后用独立查询读取：存在 RoleBinding/Project/Identity 撤权竞态。
• 返回完整 Task/Trigger record：会把脚本正文、参数、标签和 cron expression 带出管理边界。
• 新增只读管理 package/service：现有用途隔离进程、身份、限流和 Pool 已是正确部署 owner。
• offset pagination 或客户端指定 revision：前者不稳定且可能无界，后者把当前 head 选择权外移。

验证要求

• Runtime contract 覆盖 exact-shape、UUID v4 audit identity、cursor/page hard bound 与 audit/fence binding；
• PostgreSQL adapter 证明 Project snapshot→RoleBinding fence→read→audit→COMMIT 顺序， fence 变化、重复 audit 与读取失败均无部分提交；
• management service/transport/client 覆盖四个命令、Policy permission、absent、分页与 content-free 输出；
• process composition 证明 disabled 仍不开 Pool/文件，enabled 只复用既有 Pool/HTTPS；
• 完整 package/back、dependency/package-boundary/edge/local-image、十档 artifact 与 PostgreSQL HA 门保持通过。

验证结果

• Runtime Core 435/435、Cluster PostgreSQL 275 pass/1 条件 skip、Cluster Admin 256 pass/2 条件 skip；四个 inspection 命令的 exact-shape、分页、低敏结果、Policy 与事务失败关闭均已覆盖；
• 完整 19-package 门退出 0，后端为 1,095 pass/2 条件 skip/0 fail；十档 Edge/Standalone artifact 均为 compatible，最小 Edge 为 3,514,849 bytes/324 files/10,665,984 bytes RSS，最大 Standalone Application AI 为 5,882,164 bytes/474 files/20,578,304 bytes RSS；
• dependency、package-boundary、edge-import、cluster-deployment 与 local-image 审计均为 compatible， workspace 保持 19 个 package；未增加 dependency、migration、表、进程、listener、port、Pool、timer 或 watcher；
• PostgreSQL 18.4 arm64 physical-streaming HA 门总 passed=true：allowed audit 与读取结果原子提交、 提升前 remote_apply 复制、无同步备库时读取失败关闭、timeline 1→2 promotion，以及旧主 pg_rewind/同步重入后的 Task/Trigger inspect/list 恢复均已由独立 gate 证明；
• 受保护的 ql3-cnpg-evidence-control-plane 未被测试夹具纳入资源集合，启动状态、restart policy 与 restart count 保持不变；本轮随机 ql3-ha-* 容器、网络与卷由 fixture 精确清理。

影响

Cluster 部署者可以通过同一用途隔离管理入口发现发布后的 Task/Trigger 当前状态，不再需要数据库直连。 能力成本只由显式启用 Cluster Automation Management 的部署承担；路由器与 Standalone 不增加常驻开销。