docs: define direct Dev API development loop

2026-09-17 16:38:41 +00:00
parent 0dcd62fed0
commit 8c5e62cad2
4 changed files with 96 additions and 3 deletions
@@ -40,9 +40,9 @@ API-only 描述的是运行拓扑，而不是 API 功能子集。其他组件仍
 API-only 实例测试真实 CRD、admission、watch 和 reconcile 行为，而不必先准备 CNI、
 worker 与完整 GitOps 环境。

-API-only 因此可作为可选的 local development profile，但不构成独立的长期环境，也不
-替代 Dev 集成测试。Flux、in-cluster service discovery、Pod 调度和 executor 集成仍然
-必须在 managed runtime Dev 中验证。
+API-only 可以用于隔离的 API 实验、bootstrap 与恢复开发，但不构成独立的长期环境，也
+不是日常开发的默认路径。日常开发进程可以直接连接 managed runtime Dev 的 API。Flux、
+in-cluster service discovery、Pod 调度和 executor 集成仍然必须在 Dev 中验证。

 ### Managed runtime

@@ -0,0 +1,87 @@
+# ADR-0003：直接连接 Dev API 的开发循环
+
+- 状态：Accepted
+- 日期：2026-09-17
+
+## 背景
+
+如果每次 controller 代码变更都必须构建镜像、推送 registry、等待集群拉取并 rollout，
+开发反馈会被制品发布流程主导。Ayatori 的开发机与 Dev 位于可互通的内部网络，不需要为
+获得快速反馈而复制一套本地集群。
+
+Dev 本身就是可破坏的集成与实验环境，允许随时部署、停止和删除 workload。完整 GitOps
+是 Prod 的运行要求，也是 Dev 的最终集成验证目标，但不是每一个开发中组件在每一个时刻
+都必须采用的交付方式。
+
+## 决策
+
+日常 controller 开发默认直接连接 Dev API：
+
+```text
+Dev k0s API
+    ↑ kubeconfig / internal network
+developer workstation
+    └── locally built controller process
+```
+
+修改代码后只需重新编译或由 file watcher 重启本地进程。只有进入真实部署集成验证时，
+才构建不可变镜像并交给 Dev GitOps 部署。
+
+API-only profile 仍然保留，但主要用于隔离 API 实验、bootstrap 和恢复开发；它不是为了
+每位开发者复制一个长期 local environment。
+
+## 单写入者约束
+
+本地 controller 接管某类资源前，必须暂停对应的 in-cluster controller。若该 Deployment
+由 Flux 管理，应暂停对应 Flux reconciliation 或使用明确的 Dev deployment mode，避免
+Flux 立即恢复副本数。
+
+本地与 in-cluster controller 使用相同的 leader-election lease 和 identity domain，作为
+防止意外双写的最后一道保护；正常流程仍应先停止集群内实例，而不是依赖抢占 leader。
+
+Dev controller 的凭据只允许操作 Dev API 与 Dev 后端资源，不得拥有 Prod 权限。
+
+## GitOps 范围
+
+Dev 可以只用 GitOps 管理稳定底座：
+
+- k0s 之上的基础 namespace、RBAC 与 policy；
+- Flux 自身；
+- 已稳定的 Ayatori controller/operator；
+- 共享的观测和开发依赖。
+
+活跃开发中的 controller 可以暂不纳入 Flux，或以可暂停的独立 Kustomization 管理。进入
+集成验证时必须恢复以下真实部署路径：
+
+```text
+source commit
+→ immutable image
+→ Dev GitOps deployment
+→ RBAC/network/service/admission integration tests
+```
+
+Prod 只接收经过该路径验证的制品，不运行来自开发机的进程。
+
+## Admission 策略
+
+Ayatori 尽量避免 webhook，降低控制面可用性依赖和本地开发复杂度。校验按以下顺序实现：
+
+1. CRD OpenAPI schema、枚举、范围与结构化默认值；
+2. CEL validation 与 `ValidatingAdmissionPolicy`；
+3. controller reconcile 中依赖后端状态的异步校验，并通过 conditions 报告；
+4. 只有无法由上述方式正确表达的同步校验才使用 validating webhook。
+
+不使用 mutating webhook 隐藏重要默认行为。API version conversion webhook 只在真实版本
+演进需要时引入。
+
+确实需要调试 webhook 时，Dev apiserver 可以通过内部网络直接访问开发机上的 HTTPS
+endpoint；这不要求 controller 镜像先部署进集群。最终证书、Service 和 failure policy
+仍必须在 Dev GitOps 集成阶段验证。
+
+## 结果
+
+- 大多数 reconcile 开发不再经历镜像 push/pull 循环。
+- 所有开发者共享真实 Dev API 和后端边界，减少本地环境漂移。
+- Dev 不保证持续保持完整 GitOps 状态，但必须能够恢复到完整集成形态。
+- 需要明确的暂停、接管和恢复流程，避免本地与集群 controller 双写。
+- webhook 被限制为必要机制，而不是默认扩展方式。