64 lines
3.2 KiB
Markdown
64 lines
3.2 KiB
Markdown
# Gitea Runner 协议调度器路线
|
||
|
||
## 目标
|
||
|
||
长期形态不依赖 `workflow_job` webhook 发现工作。controller 本身作为 Gitea Runner
|
||
协议客户端注册，并声明 `self-hosted`、`pod` 和 `vm` labels；它只在后端存在可用容量
|
||
时领取 task，然后将该 task 交给一个一次性 Pod 或 microVM 执行。
|
||
|
||
```text
|
||
Gitea RunnerService
|
||
│ Register / Declare / FetchTask
|
||
▼
|
||
dynamic-runner scheduler
|
||
│ 已领取的 task + lease
|
||
├── Pod executor
|
||
└── microVM executor
|
||
│ logs / state / result
|
||
└──────────────────────► Gitea
|
||
```
|
||
|
||
这与“收到 webhook 后临时注册另一个 act_runner”不同。`FetchTask` 已经完成任务分配，
|
||
不能再期待 Gitea 把同一个 task 分配给随后启动的 runner。协议调度器必须让 executor
|
||
执行已经领取的 task，并继续完成日志、状态、心跳、取消和最终结果上报。
|
||
|
||
## 设计约束
|
||
|
||
- 对 workflow 的接口保持 `[self-hosted, pod]` 和 `[self-hosted, vm]` 不变。
|
||
- scheduler 在没有对应 backend 容量时不领取 task，避免本地形成不可控积压。
|
||
- 每个 executor 只执行一个 task，完成后销毁。
|
||
- SPIFFE 身份从实际领取的 task 的 repository 和 workflow job key 派生，不需要 queued 与
|
||
in-progress webhook 的二阶段关联。
|
||
- 身份中的 task 段使用 workflow job key，而不是可带空格的展示名称；job key 必须满足
|
||
`[A-Za-z_][A-Za-z0-9_-]*`。slug + hash 只保留为旧名称的显式迁移后备方案。
|
||
- scheduler 只做确定性的身份派生与 executor 绑定，不维护业务授权 policy；Zot、
|
||
OpenBao 等资源服务继续是唯一授权决策点。
|
||
- scheduler 的 runner registration credential 不进入 executor；executor 只得到执行
|
||
当前 task 所需的短期 lease/capability。
|
||
- task ACK、心跳和结果必须能够跨 scheduler 重启恢复；NATS 可以继续作为内部 handoff，
|
||
但不是 Gitea 任务事实来源。
|
||
- Pod 与 VM 共享 task/executor 协议，只有环境创建和销毁实现不同。
|
||
|
||
## 实现顺序
|
||
|
||
1. 固定当前 Gitea 版本所使用的 RunnerService protobuf 与 act_runner 版本，记录兼容
|
||
范围并建立协议契约测试。
|
||
2. 实现只注册、Declare labels 和容量感知 FetchTask 的 scheduler spike，暂不执行
|
||
task。
|
||
3. 从 act_runner 提取或复用 task 执行与日志上报能力，定义 scheduler 到 executor 的
|
||
单任务协议。
|
||
4. 首先接入 Pod executor，验证成功、失败、取消、超时和 scheduler 重启。
|
||
5. 接入 microVM executor，并复用同一 task 协议和身份派生逻辑。
|
||
6. 双轨运行并验证后，移除 webhook receiver、临时 runner 注册和 identity binding
|
||
subject。
|
||
|
||
## Bootstrap 实现的退出条件
|
||
|
||
只有同时满足以下条件才能删除 webhook 路径：
|
||
|
||
- scheduler 能通过 RunnerService 稳定领取并执行 Pod/VM task；
|
||
- Gitea UI 中的实时日志、取消、超时和结论与官方 runner 行为一致；
|
||
- scheduler 重启不会丢失已领取 task，也不会重复执行；
|
||
- SPIFFE 身份只来自实际领取 task；
|
||
- 同一套 workflow 无需修改 `runs-on` 即可从 bootstrap 迁移。
|