# Kubernetes 资源操作边界

业务模块持有期望状态，BuildManager 分阶段收敛为 Kubernetes 执行层。

百积木平台的目标边界是把“业务期望状态”和“Kubernetes 执行”分开：业务模块决定
资源为何存在、内容是什么、何时变更和撤销；BuildManager 只执行受控的 Kubernetes
操作。这个边界必须分阶段迁移，不能先删除仍被调用的接口或存量状态。

| 层次           | 目标职责                                                | 不负责内容                         |
| ------------ | --------------------------------------------------- | ----------------------------- |
| 业务模块         | 业务对象、域名与端口规则、目标地址、`desiredGeneration`、持久化、重试和撤销     | kubeconfig、集群凭据、Kubernetes 权限 |
| BuildManager | Pod 工作负载操作、集群选择、受控 Kubernetes 操作与安全校验               | 新增业务规则、证书签发流程、业务状态决策          |
| Controller   | 监听 CR、调和数据面、写 `status.observedGeneration` 和 `Ready` | 产生业务期望状态                      |

## 当前迁移阶段

当前只退役没有活跃调用方的两组 BuildManager 接口：

- `/api/e2b-compatible/**`
- `/api/domain-mapping/**`

以下接口和状态仍有生产调用方，必须保留：

- `/api/port-mapping/**`
- `/api/route-projections/**`
- `domain_mapping`、`route_outbox` 表
- `kubernetes_cluster.port_mapping_*` 配置字段

这是一条发布约束，不是目标架构的例外。Agent Runtime、Browser Session、Hosted
Service、Site Service、Domain Binder 及 lowcode 管理面迁移到各自业务状态前，禁止删除
上述接口、表或配置，也禁止用通用资源接口直接替换后立即删库。

## 最终资源所有权

- Agent Runtime、Browser Session、Hosted Service 分别持有自己 `ContainerRoute` 的业务状态。
- Site Service 持有 `WebsiteRoute` 的业务状态。
- Domain Binder 持有 TLS Secret、`WebsiteChallenge` 的业务状态和证书生命周期。
- BuildManager 不生成域名、端口映射、业务代次或恢复策略，只执行受安全策略约束的操作。

调用方必须在自己的存储中持有源事实。异步调和流程应在同一数据库事务中写入 Outbox；
同步流程必须等待 Controller 返回 `Ready` 后才能确认业务操作成功。修改已有对象时先读取
`resourceVersion`，冲突后重新读取，不得无条件覆盖。

```text
业务事务 -> 期望状态（异步流程同时写 Outbox）
        -> BuildManager 受控执行
        -> API Server
        -> Controller 调和
        -> observedGeneration == desiredGeneration && phase == Ready
```

删除路由应发布 `state=Absent` 的新代次，而不是直接遗忘业务记录。这样延迟到达的旧事件
不能复活已经撤销的路由。

## 迁移与退役门禁

每一类资源必须独立完成以下步骤，不能合并成一次破坏性发布：

1. 明确唯一业务 owner，并在 owner 数据库中建立源事实与 Outbox。
2. 发布新生产者和消费者，完成存量记录、CR 与代次迁移。
3. 验证重试、冲突、删除墓碑、Controller Ready 和回滚链路。
4. 对旧接口做生产流量与代码调用审计，持续确认零调用。
5. 先退役路由并观察，再通过独立数据库迁移删除旧表或字段。

数据库迁移不得与接口切换同时删除生产状态。回滚窗口内继续保留旧表、Outbox、CR 和
TLS Secret，直到新 owner 已能完整恢复。

## 执行层安全约束

BuildManager 的允许列表、固定 namespace、Secret 字段限制和读取脱敏属于平台安全策略。
它们不应包含某个业务的域名、端口、路由生成规则。凭据只授予所需资源和 namespace 的
最小权限，不授予集群管理员权限，也不向调用方暴露 kubeconfig。

时间字段和代次值统一使用 Unix epoch 毫秒整数，公共请求与响应使用
[CModel 数据契约](/development/data-contracts/)。