qinglong/docs/adr/ADR-0433-catalog-bound-kubernetes-target-deployment-ceremony.md

# ADR-0433：Catalog-bound Kubernetes 目标部署 Ceremony

- 状态：Accepted
- 日期：2026-08-16
- 关联 RFC：QL-RFC-0001 D-03、D-14、D-337、D-339、D-341
- 关联 ADR：ADR-0429、ADR-0431、ADR-0432

## 上下文

ADR-0431 已把 verified release catalog 物化为 Kubernetes v2 locked manifest/report，但最后一步仍由运维者直接执行
`kubectl apply -f locked.yaml`。该命令没有再次绑定 report self-digest、目标 cluster、kubeconfig、kubectl executable 或
field manager；检查过的文件、实际输入和实际 API target 之间仍存在复制、context 漂移与 TOCTOU 窗口。成功输出也没有 durable
receipt，响应丢失后只能凭人工判断是否重放。

Cluster 需要解决这个缺口，但不能把 Kubernetes、YAML 或 registry 工具带到 Local/Edge，也不能为一次发布新增常驻 controller、
webhook 或长期 ServiceAccount authority。

## 决策

1. 在现有维护工作站脚本边界增加 `cluster.deployment.preflight`、`cluster.deployment.apply` 与
   `cluster.deployment.receipt.audit` 三种 canonical command；只提供一个
   `pnpm cluster-deployment:ql3 -- --command-file=/absolute/private/command.json` 入口，不新增 workspace package 或生产依赖。
2. command、locked manifest、lock report、kubeconfig、preflight 与 receipt 必须位于 current-UID 的 canonical `0700` 目录，文件为
   canonical、current-UID、单链接 `0600` regular file。所有输入使用 `O_NOFOLLOW|O_CLOEXEC` stable descriptor 有界读取，调用前后
   复验 dev/inode/size/mtime/ctime 与 SHA-256。kubectl 必须是 absolute canonical、current-UID 或 root owner、不可 group/other write
   的单链接 executable，并由 command 固定其 SHA-256。
3. 目标 consumer 独立验证 `qinglong/kubernetes-deployment-lock@v2` exact shape/self-digest、3.x release identity、catalog workflow/
   immutable reference/release-set 闭包、required role 顺序、全部 GHCR digest reference、manifest byte digest、资源/authority 数量、
   五项 release annotation，以及未知或畸形 QingLong image authority 为零。不能只相信 materializer 的 success stdout。
4. kubeconfig 必须由 command 固定 SHA-256 和 explicit context；禁止 `exec` 与 legacy `auth-provider`，避免稳定文件读取后再隐式执行
   ambient credential plugin。每次网络动作前显式读取 `kube-system` Namespace UID，并与人工审核的 `expectedClusterUid` 精确匹配。
5. preflight 只执行固定 manager `qinglong3-catalog-lock` 的 `kubectl apply --server-side --dry-run=server --validate=strict -f=-`，通过
   stdin 发送已验证的内存字节，不让 kubectl 按路径二次读取 manifest。所有承载 QingLong image authority 的资源必须显式携带
   namespace，禁止依赖 context 的 ambient default namespace。成功后才 no-replace 发布 self-digest preflight report；它明确
   `networkAccess=true`、`kubernetesMutation=false`。目标 namespace 必须预先存在，否则包含 namespaced resources 的 dry-run 自然失败关闭。
6. apply 必须消费 exact preflight digest，并重新执行全部离线检查、cluster UID 与 server-side dry-run；不使用
   `--force-conflicts`。实际 apply 后以 `kubectl get -f=- -o=json --show-managed-fields=true` 读取同一资源集合：每个对象必须有
   UID/resourceVersion，全部期望字段递归匹配；承载 QingLong image authority 的资源必须由固定 field manager 以 `Apply` 持有，所有
   image/catalog annotation 再次精确验证。结束时再次检查 cluster UID 和全部稳定文件。
7. 只有所有步骤成功后才以 `0600` no-replace 发布 self-digest receipt。receipt 绑定 mutation、command、preflight、lock/manifest/
   catalog digest、cluster UID、kubeconfig/kubectl digest、各 argv/stdout/stderr digest 与 byte count。已有 exact receipt 的相同 command
   离线返回；apply 成功但 receipt 丢失时，使用同一 command/field manager 重放 server-side apply，再以 live convergence 收敛。
8. Kubernetes 多资源 apply 不是事务，receipt 必须固定 `crossResourceAtomicity=false`。失败时不自动删除或回滚资源；先审计 live state，
   再用上一份 catalog-bound lock 执行新的显式 roll-forward。offline receipt audit 只重建 canonical/self/command binding，明确
   `externalResultsReplayed=false`，不伪称离线重放 API Server 结果。

## 部署与资源影响

- Local/Edge/Standalone 零导入、零制品增量、零常驻 CPU/RSS/网络/写放大；低配路由器继续只消费 Local v2 selection。
- Cluster 不新增 controller、webhook、CRD、RBAC、ServiceAccount、Pod、listener、timer、watcher、数据库、migration、SQL 或 Pool。
  ceremony 使用部署者原有 kubeconfig 权限并在命令结束后退出。每个 kubectl 子进程使用独立 `0700` 临时 HOME/XDG cache/TMPDIR，
  结束即清理，不读取 ambient HOME，也不在仓库或 operator home 留下 discovery cache。
- 实现内聚在 `scripts/lib/ql3-kubernetes-deployment-ceremony.cjs` 与薄 CLI；没有为单一工作站流程拆出浅 workspace package。
- 每次 preflight 为一次 cluster identity read 和一次 server-side dry-run；apply 为 identity read、dry-run、apply、convergence read、末次
  identity read。manifest/report/kubeconfig 各有明确 byte ceiling，process stdout/stderr 各最多 4 MiB。

## 被拒绝的替代方案

### 继续文档化裸 `kubectl apply`

拒绝。它无法证明 apply 的文件、report、context、cluster 和 executable 与人工审核对象相同，也没有 response-loss recovery receipt。

### 使用 `kubectl diff` 证明收敛

拒绝。真实 K3s 门证明 kubectl 会隐式从 `$PATH` 启动外部 `diff`，扩大未固定的 executable authority。受审 convergence read 只调用
同一 pinned kubectl，并直接验证 live object identity、managed field ownership 和完整期望字段。

### 自动 `--force-conflicts` 或失败后删除资源

拒绝。强夺其他 field manager 或跨资源猜测回滚会扩大故障；冲突必须失败关闭，多资源非原子事实必须进入 receipt 与人工恢复流程。

### 在集群内新增持续部署 controller

拒绝。当前缺口是显式 release rollout 的最后一跳，不值得新增常驻 availability、credential、certificate 与升级故障域。

## 验证

- 定向契约 10/10，覆盖 lock/report/manifest/annotation、cluster UID、文件权限、kubeconfig executable auth、server dry-run、apply、live
  convergence、field manager、receipt 重签、response replay、closed CLI 与低敏失败；
- 隔离三节点 K3s `v1.34.3+k3s1`/Linux arm64 真实运行 6 个资源、4 个零副本 Deployment；preflight、server-side apply、live
  convergence 与 offline receipt audit 全部通过，固定 manager 为 `qinglong3-catalog-lock`，临时 Docker container/network 零残留；
- 最终 live cluster UID 为 `7b2a5391-41a3-4905-90cc-3b831bef0058`，preflight digest 为
  `sha256:7c6db6236a704cd7791f94268b3883d6385a75a993a14d1611791f885fb65404`，receipt digest 为
  `sha256:58817a667bccf28c068fff40619cf13d2d0a1be84153de66a137b005feb536ba`。该 synthetic lock 只验证目标 apply 语义，不冒充公开
  GHCR catalog ceremony；
- 完整 backend、18-package、边界审计与制品结果记录在 QL-RFC-0001 D-341。