qinglong/docs/adr/ADR-0386-cluster-run-management-kubernetes-live-evidence.md

ADR-0386：Cluster Run Management Kubernetes 多节点实证

• 状态：Accepted
• 日期：2026-08-12
• 关联 RFC：QL-RFC-0001 D-298
• 前置决策：ADR-0359、ADR-0364、ADR-0366、ADR-0382、ADR-0383、ADR-0384

上下文

Cluster 已有强认证 run.retry | run.stop、专用 ql3_run_manager、两副本 Kubernetes overlay 和 PostgreSQL HA Docker 证据，但这些证据没有在同一真实 CNI/Pod/CloudNativePG 环境中组合。静态 YAML、进程内测试和单机 PostgreSQL promotion 不能证明跨节点 Pod、mTLS/OIDC rotation、NetworkPolicy、readiness withdrawal 与数据库主切换同时成立。

部署用户跨度很大：Edge 路由设备不能为 Cluster 门增加任何常驻成本；Cluster 节点又需要真实多副本证据。因此本门必须是 workflow_dispatch 的短生命周期发布门，不能进入默认 CI、默认 overlay 或 Local artifact。

决策

1. 新增 opt-in 三节点 K3s live gate：1 control-plane + 2 worker、内置 Flannel、3 实例 CloudNativePG 1.30.0/PostgreSQL 18.4、2 个 Run manager Pod 且位于不同节点。
2. 直接构建当前 Cluster Admin/Control 镜像，应用既有 operations/run-management/cloudnative-pg；不新增 package、生产依赖、migration、表、角色、常驻进程或 sidecar。
3. 产品 client 以 tokenless、无 RBAC、immutable Secret 输入的 caller-driven Job 精确连接每个 Pod。run.retry 必须得到 accepted → existing，随后 run.stop 必须得到 accepted → already_requested；最终数据库只能有 1 个 retry Run、1 个 Attempt、2 个 retry Event、1 个 cancellation Event、2 个 allowed audit，重复 mutation 为 0。
4. 弱认证在业务层前返回 401 且不写项目 audit；强但无 RoleBinding 的 User 返回 403 并写恰好 1 个 denied audit。报告不保存 assertion、证书、密钥、DSN、kubeconfig 或业务内容。
5. OIDC keyset 执行 generation 1→2 overlap→3 revoke，回滚 generation 必须启动失败且始终保留 2 Ready Pod；mTLS CRL 更新必须替换全部 Pod、旧 client 被拒绝、新 client 可用，rollout 不低于 2 Ready。
6. 删除当前 CNPG primary 并确认 promotion 与恢复 3 实例；切断 -rw Service endpoint 时两个 Pod 都返回 503、readiness 为 503、liveness 为 200，恢复 endpoint 后旧 Pod不得原地恢复，必须由新 Pod 服务。
7. CNI 必须观测 labelled client allowed、unlabelled/wrong-port denied、manager→CNPG allowed、manager→Kubernetes API/public internet denied；ServiceAccount 无 Secret read 和 Deployment patch 权限。
8. live 代码分三层：通用 Kubernetes 管理 helper、Run 领域 scenario/SQL facts、严格离线 report audit。通用 executor 的 retry error code 改为显式配置且保留旧默认值，Approval live 回归必须通过。禁止复制身份 assertion、健康探针和平台原语；新增能力不得形成 workspace 微包。

证据合同

离线报告固定为 qinglong/run-management-kubernetes-live-contract@v1，要求：

• K3s v1.32+、锁定 rancher/k3s:v1.34.3-k3s1、3 个独立 PodCIDR；
• migration count 57、control-core capability 56、PostgreSQL version number 180004；
• 两个唯一 Pod/Node digest、PDB minAvailable 1、maxUnavailable 0、每 Pod Pool max 2；
• retry/stop exact replay、认证负向门、identity/certificate rotation、availability、isolation、durability 全为精确字段；
• 0600 regular file、no overwrite、无敏感材料；三条非生产 limitation 不得隐藏。

Package 与低配影响

本切片不新增 workspace package。当前 package boundary 仍要求每个 src/ 根文件都是 manifest 证明的入口；实现位于领域目录，高密度目录受 hard cap。文件少不是拆包理由，部署/authority/稳定多消费者才是 package 边界。该 live gate 只在人工发布作业中创建 Docker/K3s/CNPG 资源，完成后全部删除；Edge/Standalone 的文件、module、RSS、timer、listener 与连接预算不变。

验收状态

• 锁定的 CNPG v1.30.0 manifest SHA-256 为 f8bede43fe4ee0d478c2355b204a36876b2ae4faac60f2a9452280b293da3b88；本机 arm64 真实三节点 K3s/CNPG Run gate 已通过，报告时间 2026-08-12T08:25:36.761Z，报告 SHA-256 为 4be50ad1ebbe0b9fea76ecac33133ea709461d44acbff730c60a37fe3fd2921a，权限 0600，离线审计零 finding。
• 实证为 K3s v1.34.3+k3s1、3 个 CNI Ready 节点、CloudNativePG 1.30.0/PostgreSQL 18.4 三实例、2 个跨节点 Ready manager；migration 57/control-core capability 56。retry 状态为 accepted → existing → existing，stop 为 accepted → already_requested → already_requested，最终 retry Run/Attempt/Event 为 1/1/2、cancel Event 为 1、重复 mutation 为 0。
• identity generation overlap/revoke/rollback、mTLS CRL 全 Pod replacement、CNPG primary promotion、数据库断连 readiness withdrawal/liveness preservation、恢复后强制 Pod replacement、CNI ingress/egress 与 RBAC/数据库角色 least privilege 全部通过；运行后 ql3-run-live-* 容器、网络和临时镜像均无残留。
• 真实门首先暴露并修正三处组合缺口：共享产品 client 未允许精确 Run route；本地镜像替换误伤非镜像 zero-digest annotation；live 重放重新签发 JTI 导致认证/audit fence 漂移。最终重放在签名 key rotation 中固定认证会话 JTI，保留生产端强认证围栏；现场只把测试渲染的 HTTP rate window 收窄为 1 秒，生产清单仍为 peer 30/global 300 次每 60 秒。
• Run/Approval live 静态合同、离线审计与既有 deployment 回归通过；Run report 审计含 topology/schema/deployment/client/rotation/availability/isolation/durability/secret 反向 fixture。
• runner、scenario、platform、identity、PKI 与 audit 均通过 Node syntax check；现有 Run deployment 合同通过。
• 完整 18-package clean build/test 退出 0；backend 1,177 tests、1,175 pass/2 conditional skip/0 fail；14 个 Edge/Standalone Profile artifact 全部 compatible。基础 Edge 为 2,467,343 bytes/295 files/53 loaded modules，RSS delta 10,960,896 bytes，仍低于 4 MiB/512 files/16 MiB 门限。
• package/dependency/local-image boundary 全部 compatible，18 个 workspace package 无 single-source/shallow package；本切片没有改变任一 Local artifact 的生产闭包。
• PostgreSQL 18.4 arm64 HA 通过 123 gates、primary timeline 1→2，报告 SHA-256 6adb8c9de8929ff54b522e9a251e3081d9dd004c1a91f72f83c33288ddce63a9；运行后 ql3-ha-* container、volume、network 均为空。
• 固定 K3s/CloudNativePG live report 已满足，本 ADR 转为 Accepted。

后果

Cluster 有了可重复执行的真实组合门，但 Docker-host K3s 仍不是生产 control-plane HA 或 STONITH 证明，local deterministic IdP 也不替代外部 IdP 集成。工作流只提供 release candidate evidence，不改变默认部署。后续可把同构的 Approval/Automation runner 继续迁移到共享平台层，但不得为去除文本重复而一次性重写已通过的独立 live 流程。