Reviewed-on: #103
Gitea dynamic runner
为 Gitea Actions 按需创建一次性执行环境。每个 job 的 runs-on 只写一个 label,
它同时决定执行环境和规格:
runs-on: [self-hosted] # homelab Pod,默认规格
runs-on: [self-hosted-large] # homelab Pod,大规格
runs-on: [self-hosted-vm] # OpenSandbox VM
runs-on: [cloud] # GKE Autopilot Pod
每个 runner 也只声明一个 label:Gitea 把 job 派给拥有其全部 label 的 runner,多一个
label 的 runner 就会接走别的池的 job。容量耗尽时不回退到其他池。每个环境只执行一个
job,并在 job 结束后连同本地状态一起销毁。完整的设计约束见
docs/design-principles.md。
模型:Gitea 是队列,worker 是池成员
┌ pod 池 ──────────────────────────────────────────────┐
Gitea ──▶ │ pod-laptop FetchTask ──▶ executor Pod ──▶ facade │
按 label│ pod-sandbox FetchTask ──▶ executor Pod ──▶ facade │
分发 └──────────────────────────────────────────────────────┘
┌ vm 池 ───────────────────────────────────────────────┐
──▶ │ vm FetchTask ──▶ OpenSandbox VM ──▶ facade │
└──────────────────────────────────────────────────────┘
- 每个 worker 是一个 Gitea runner 池的成员,用自己的 registration 声明池的 label,
只在本地容量池有空位时
FetchTask。满载时 task 留在 Gitea 显示为等待,由池内其他 成员领取;加成员就是用相同 label 再注册并部署一个 worker。 - 领取后 worker 同步占槽位,创建 executor、绑定 SPIFFE 身份并等待 executor 里的 官方 runner 认领。Gitea 不能收回已领取的 task:交接失败时删除 executor 并本地 重试,超过期限(或 worker 退出)就把 task 报为失败供 rerun。
- facade 是该 worker 的 SPIFFE mTLS RunnerService:只把预先领取的 task 交给持有对应 身份与 capability 的 executor,并用领取该 task 的 registration 转发上报。executor 只回报给创建它的 worker,所以一个 facade URL 后只能有一个 worker 实例。
组件(同一个 Go 二进制,COMPONENTS 选择,默认两者都启用):
kubernetes-worker:在本集群创建一次性 privileged Pod;Pod 内 workflow 使用 host executor,job hook 等待 SVID 并启动 job-local Docker daemon(cgroup 限制在 Pod 内)。opensandbox-worker:通过 OpenSandbox Lifecycle API 从ci-vmPool 创建 VM。opensandbox-identity(Python,src/):在 sandbox 集群按实际 Pod UID 创建并清理 临时 SPIFFE entry;见docs/opensandbox-runner.md。
开发
go test ./...
go vet ./...
python -m venv .venv && . .venv/bin/activate
pip install -e '.[test]' && pytest # opensandbox-identity
配置
controller 执行 controller 子命令,runner 镜像执行 executor 子命令。长期
credential 只从挂载文件读取:
POD_GITEA_RUNNER_UUID_FILE、POD_GITEA_RUNNER_TOKEN_FILE(kubernetes-worker)与VM_GITEA_RUNNER_*(opensandbox-worker):该 worker 自己的 runner registration, 不下发给 executor。默认 label 是规范的 pod/vm 池,可用POD_RUNNER_LABELS、VM_RUNNER_LABELS覆盖;同一池的成员必须一致。RUNNER_FACADE_CAPABILITY_KEY_FILE:至少 32 字节的 HMAC key,只绑定本 worker 的 executor,每个 worker 可以独立生成。OPENSANDBOX_API_KEY_FILE:仅opensandbox-worker读取。
非 secret 配置:POD_EXECUTOR_IMAGE(digest)、SPIRE_CLUSTER(k8s_psat 集群名,
executor 身份的 parent 由它与 Pod 所在节点 UID 推导,controller 需要读取 Node)、
RUNNER_FACADE_URL、RUNNER_FACADE_SPIFFE_ID、SPIFFE_ENDPOINT_SOCKET、
RUNNER_HEALTH_LISTEN(默认 :8081,明文 GET /healthz 供 kubelet 探针用)、
POD_CAPACITY(默认 4)、VM_CAPACITY(默认 1)。VM_RUNNER_LABELS(默认
self-hosted-vm)是 VM worker 声明的 label,canary 设为 self-hosted-vm-dev。旧组件名 pod-worker、
vm-worker 作为别名保留。
每个 Pod worker 服务一个 label、一个规格:POD_RUNNER_LABELS(默认 self-hosted)是它
声明的 label(迁移期间可用逗号加旧 label 作别名),POD_RESOURCES 是这些 job 的 Kubernetes resources JSON,例如
{"requests":{"cpu":"4","memory":"9Gi"},"limits":{"cpu":"4","memory":"9Gi"}};不设时由
namespace 的 LimitRange 决定。要提供另一个规格,就用另一个 registration 和 label(例如
self-hosted-large)部署一个 worker,只放在资源足够的集群上。未写 limits 的资源会套用
LimitRange 的默认 limit,requests 超过它时 Pod 会创建失败,所以调大资源时 requests 和
limits 要一起写。
云端调度:在 COMPONENTS 中加入 cloud-scheduler,把 runs-on: [cloud] 的 job 调度成
GKE Autopilot 上的一次性 Pod。配置和设计见 docs/cloud-executor.md。
池成员一次注册:scripts/register-runner <名称> <label> 从 OpenBao
kv/k8s/gitea-runner 取 registration token,以官方 runner 6.0.0 注册,并把 uuid、
token 写入 kv/k8s/dynamic-runner-<名称>,不打印凭据;路径已存在时拒绝覆盖。例如
scripts/register-runner pod-sandbox self-hosted。label 只是注册时的初值,worker 启动时会用
Declare 改成自己配置的 label。
Pod task 的 terminal update 被 Gitea 接受后,controller 在 Pod 上持久写入
ci.ddupan.top/terminal=true。生命周期 reconciler 清理带该 label 且已结束的 Pod 及其
ClusterStaticEntry;未上报终态就退出的 executor 也会被标记、清理并释放槽位。
安全边界
- registration、facade key 与 OpenSandbox API key 只从文件读取,不进入 executor; executor 只得到绑定自身 assignment 的 capability 与 SPIFFE 身份。
- 一个成员泄露只暴露它自己的 registration:它只能领取本池 label 的 job,可在 Gitea 单独停用。
- runner 配置属于部署:设置
POD_RUNNER_CONFIGMAP后,Pod executor 挂载该 ConfigMap, 用其中的config.yaml代替镜像内的config/runner.yaml(需保留job_startedhook 与workdir_parent);POD_RUNNER_CACHE_SECRET挂载到/run/gitea-runner-cache,供配置 引用 cache 凭据。host 模式 job 能读到该 secret,因此所有 Pod 仓库共用同一信任域,可以 读写彼此的 Actions cache;只在仓库互相信任时启用。VM executor 不受影响。
homelab 的 Kubernetes、OpenBao、sandbox 集群与容量配置位于 panxiao81/homelab-infra。