61 lines
2.5 KiB
Markdown
61 lines
2.5 KiB
Markdown
# Gitea dynamic runner
|
||
|
||
为 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`：领取任务、限制并发，并通过 Pod 或 microVM backend 创建一次性环境。
|
||
- `microvm-runner-launch`：为每个任务创建 COW disk、NoCloud seed 和 TAP，运行
|
||
Cloud Hypervisor，退出后完整清理。
|
||
- `guest-runner`：在 guest 中领取一次性 runner registration token，注册 ephemeral
|
||
runner，执行一个 job 后关机。
|
||
- `pod-worker`：在 Kubernetes 中创建一次性 privileged Pod；Pod 内的 workflow 使用
|
||
host executor，Docker、BuildKit 和 kind 等工具由 pipeline 按需 setup。
|
||
- `jwt-broker`：早期共享 Kubernetes runner 的过渡实验；目标架构不部署它，每个
|
||
动态 Pod 或 VM 直接取得自己的 SPIFFE 身份。
|
||
|
||
消息流使用一个 `WorkQueuePolicy` stream。相同 runner label 的所有 worker 共享同一
|
||
durable consumer；扩容只需要增加 worker 或提高单机 capacity。
|
||
|
||
当前 webhook → NATS 流程是用于尽快验证 Pod/VM 生命周期的 bootstrap 实现，不是
|
||
长期调度接口。长期目标是让 controller 作为兼容 Gitea Runner 协议的调度器直接注册、
|
||
声明 labels、领取 task，并把已领取 task 交给 Pod/VM executor；路线与迁移边界见
|
||
[`docs/runner-protocol-roadmap.md`](docs/runner-protocol-roadmap.md)。
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
. .venv/bin/activate
|
||
pip install -e '.[test]'
|
||
pytest
|
||
```
|
||
|
||
## 安全边界
|
||
|
||
- NATS 密码、webhook secret 和 Gitea registration token 只从文件读取。
|
||
- registration token 不写入 seed image；worker 通过单次 nonce endpoint 交给 guest。
|
||
- guest runner 使用 `--ephemeral`，每台 VM 只执行一个 job。
|
||
- launcher 只接受 UUID instance ID 和 URL-safe nonce，所有临时文件都位于独立目录。
|
||
- base image 不得包含 runner identity、registration token、SSH 密码或 host key。
|
||
|
||
homelab 的 Kubernetes、OpenBao、LXC、bridge 和容量配置保留在
|
||
`panxiao81/homelab-infra`。
|
||
|
||
按需启动 Cloud Hypervisor microVM 的 Gitea Actions runner autoscaler
|