记录动态 Runner 设计原则

README.md

@@ -1,20 +1,31 @@
-# Gitea microVM runner
+# Gitea dynamic runner
 
-为 Gitea Actions 按需启动 Cloud Hypervisor microVM。适合 kind、嵌套容器和其他不应
-在常驻 Kubernetes runner 中执行的 CI 工作负载。
+为 Gitea Actions 按需创建一次性执行环境。对 workflow 提供两种稳定的 runner
+接口：
+
+```yaml
+runs-on: [self-hosted, pod]
+```
+
+```yaml
+runs-on: [self-hosted, vm]
+```
+
+`pod` 使用动态 Kubernetes Pod，`vm` 使用动态 Cloud Hypervisor microVM。每个环境
+只执行一个 job，并在 job 结束后连同本地状态一起销毁。完整的设计约束见
+[`docs/design-principles.md`](docs/design-principles.md)。
 
 组件：
 
 - `controller`：接收 Gitea `workflow_job` webhook，将指定 label 的 queued job
   发布到 NATS JetStream。
-- `worker`：在虚拟化宿主机领取任务，限制本机并发，并启动一次性 microVM。
+- `worker`：领取任务、限制并发，并通过 Pod 或 microVM backend 创建一次性环境。
 - `microvm-runner-launch`：为每个任务创建 COW disk、NoCloud seed 和 TAP，运行
   Cloud Hypervisor，退出后完整清理。
 - `guest-runner`：在 guest 中领取一次性 runner registration token，注册 ephemeral
   runner，执行一个 job 后关机。
-- `jwt-broker`：运行在 Kubernetes runner 外层 Pod 中，以可被 SPIRE attestation
-  的 PID 获取固定 `aud=zot` JWT-SVID；DinD job 通过受限 HTTP endpoint 获取短期
-  token。broker 不记录响应、不缓存 token，也不接受调用方指定 audience。
+- `jwt-broker`：早期共享 Kubernetes runner 的过渡实验；目标架构不部署它，每个
+  动态 Pod 或 VM 直接取得自己的 SPIFFE 身份。
 
 消息流使用一个 `WorkQueuePolicy` stream。相同 runner label 的所有 worker 共享同一
 durable consumer；扩容只需要增加 worker 或提高单机 capacity。