panxiao81 68a8c96b98
test / shell (push) Successful in 1m6s
test / python (push) Successful in 2m45s
test / go (push) Successful in 4m47s
Merge pull request 'chore(deps): update ghcr.io/spiffe/spire-agent docker tag to v1.16.0' (#103) from renovate/ghcr.io-spiffe-spire-agent-1.x into main
Reviewed-on: #103
2026-11-18 13:02:21 +00:00
2026-09-16 13:06:05 +00:00

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-vm Pool 创建 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_started hook 与 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。

S
Description
按需创建 Pod 与 Cloud Hypervisor microVM 的 Gitea Actions 动态 Runner
Readme
32 MiB
0 Stars 1 Watchers 0 Forks
Languages
Go 90.5%
Python 5%
Shell 3.5%
Dockerfile 1%