跳转到内容
免费试用 Gitea Cloud ☁️ 30 天,加速你的开发与部署!
技术支持

Actions Runner Controller 概览

Actions Runner Controller 在 Kubernetes 集群中运行 Gitea Actions 的 runner,并随任务队列伸缩:有任务排队时增加 runner,空闲后将其回收。您用 Runner 资源描述一组 runner,由 controller 创建、注册和回收 runner Pod。

它可用于任何满足要求的 Kubernetes 集群,托管集群与自建集群均可,不依赖任何云厂商。

术语 含义
Runner 您创建的 Kubernetes 资源,描述一组 runner 及其伸缩方式。
runner Gitea Actions 的 runner,即 Gitea 的 runner 页面中列出的条目。
runner Pod controller 为 Runner 创建的 Pod,每个 Pod 运行一个 runner。controller 的事件、日志和字段说明(kubectl explain)中称其为 worker,例如 worker 3 即 runner Pod <name>-0003。
job Pod 使用 Kubernetes 后端时,runner 为每个任务创建的 Pod。
注册信息 runner 在 Gitea 中的身份。controller 用注册令牌获取它,并保存在 Secret 中。
runner 配置文件 runner 的配置文件(config.yaml),由 controller 根据 Runner 生成。
action 缓存 任务通过 uses: 使用的 action 的代码,由 runner 下载。与工作流缓存无关。
工作流缓存 工作流通过缓存接口保存和恢复的文件,例如 actions/cache,以及开启缓存后的 setup-go、setup-node 等 action 写入的内容。保存在缓存服务器或 S3 存储桶中。
  1. 您在某个命名空间中创建 Runner 资源,指明 Gitea 实例、注册令牌,以及任务通过 runs-on 选择的 label。
  2. controller 每隔几秒向 Gitea 查询有多少任务在等待这些 label,以及它的 runner 是否在线、是否繁忙。这使用 Gitea Enterprise 的 API,因此需要有效的许可证。
  3. controller 据此计算所需的 runner Pod 数量,范围在 minSize 与 maxSize 之间。有任务排队时,一次性增加所需的 runner Pod;runner 空闲时,逐个回收。详见伸缩。
  4. controller 为每个 runner Pod 向 Gitea 注册一个 runner,并生成其 runner 配置文件。注册令牌只由 controller 使用,runner Pod 只获得自己 runner 的凭证。
  5. Pod 中的 runner 与其他 Gitea Actions runner 一样,用同样的协议获取并执行任务。

runner Pod 以 Runner 的名称加编号命名:<name>-0001、<name>-0002,依此类推。runner Pod 被回收后,其注册信息会保留,缓存卷默认保留一周(storage.cacheTTL)。下次需要该编号时,重建的 runner Pod 在 Gitea 中仍是同一个 runner,缓存也仍然保留。

注册令牌决定了 Runner 的 runner 接取哪些任务,以及 controller 统计哪些排队任务:

令牌来源 runner 服务于
管理后台 → Actions → Runners 实例的所有仓库
组织设置 → Actions → Runners 该组织的仓库
仓库设置 → Actions → Runners 该仓库

runner 会出现在令牌所在的同一页面中,名称与其 Pod 相同。

Runner 用以下两种后端之一执行任务,且只能设置其中一种:

  • Docker-in-Docker:每个 runner Pod 运行自己的 Docker daemon,任务以该 daemon 中的容器运行。这与在服务器上安装 runner 的方式相同,但 runner Pod 必须以特权模式运行。
  • Kubernetes:runner 通过 Kubernetes API 为每个任务创建一个 Pod。runner Pod 与 job Pod 都不需要特权模式,但任务中没有 Docker daemon 可以使用。
Docker-in-Docker Kubernetes
配置位置 spec.runtime spec.kubernetesRuntime
runner 镜像 gitea/runner:<version>-dind,5.3.0 及以上,建议 6.0.0 及以上 gitea/runner:<version>,5.3.0 及以上,建议 6.0.0 及以上
任务运行位置 runner Pod 中 Docker daemon 的容器中 单独的 job Pod 中
特权 Pod 需要 不需要。runner Pod 满足 Pod Security 的 restricted 级别,job Pod 满足 baseline
每个 runner Pod 的任务数 1 capacity,默认 4
任务中的 Docker 可用:docker build、Docker 类 action、服务容器的卷 不可用,见限制
任务之间的隔离 共享一个 Docker daemon 的不同容器,每个 Pod 同一时间一个任务 不同的 Pod,可使用 Kata Containers 等沙箱运行时
每个 runner Pod 的持久卷 Docker 数据目录与 action 缓存 action 缓存
拉取的任务镜像缓存在 runner 的 Docker 存储卷上,随 runner 保留 节点上,随节点保留

集群不允许特权 Pod,或希望每个任务运行在单独的 Pod 中时,选择 Kubernetes 后端。工作流需要构建容器镜像或使用 Docker 类 action 时,选择 Docker-in-Docker。两者可以并用:各建一个 Runner,使用不同的 label,见两种后端并用。

在每个 Runner 所在的命名空间中:

资源 Docker-in-Docker Kubernetes
runner Pod 最多 maxSize 个,每个同一时间一个任务 最多 maxSize 个,每个同一时间 capacity 个任务
job Pod 无 每个运行中的任务一个,由 runner 创建,任务结束后删除
每个 runner Pod 的 PVC 两个:<runner pod>-cache 用于 Docker 数据目录,<runner pod>-action-cache 用于 action 缓存 一个:<runner pod>-action-cache
每个 runner 的 Secret <runner pod>-registration,保存 runner 的注册信息 同左
每个 runner Pod 的 ConfigMap <runner pod>-config,生成的 runner 配置文件 同左
ServiceAccount 与 RoleBinding 无 <name>-worker,供 runner 创建 job Pod
缓存服务器 保存工作流缓存,每个 Runner 一个:Pod <name>-cache-server、Service <name>-cache-server-svc、Secret <name>-cache-server-secret、存储卷 <name>-cache-server-data。使用 S3 兼容存储(推荐)、外部缓存服务器或自定义 runner 配置文件时不创建 同左

runner Pod 带有 Kubernetes 标签 app: <name> 与 runner-index: <编号>,缓存服务器 Pod 带有 app: <name> 与 name: <name>-cache-server,可供 NetworkPolicy 等选择器使用。

以上资源均归 Runner 所有,删除 Runner 会将它们一并删除。Gitea 中注册的 runner 不会被删除,它们以离线状态保留,直到您在 Gitea 中删除。

  • 持有有效许可证的 Gitea Enterprise。 没有有效许可证时,controller 无法读取任务队列,因此既不创建也不伸缩 runner Pod,并在 Runner 上报告状态码为 403 的 InspectGiteaFailed 事件。须使用 Gitea Enterprise 27.3.0 及以上版本,建议使用 28.3.1 及以上版本。
  • 注册令牌,其范围即 runner 要服务的范围。
  • Kubernetes 1.30 及以上。
  • 集群能访问您的 Gitea Enterprise 实例。 所有连接都由集群发起,Gitea 无需访问集群,也不需要 Ingress 或负载均衡器。集群还须能拉取 runner 镜像和任务镜像,并能下载任务使用的 action,默认来自 https://github.com。
  • 能动态供应 ReadWriteOnce 存储卷的 StorageClass,见存储与缓存。
  • 所用后端的要求:Docker-in-Docker或 Kubernetes。
  1. 安装 controller。
  2. 创建使用 Docker-in-Docker 后端或 Kubernetes 后端的 Runner。
  3. 用配置和存储与缓存中的选项进行调整。Runner 字段参考列出了所有字段。