Actions Runner ControllerARC深入解读在 Kubernetes 上运行与自动伸缩 GitHub Actions 自托管 Runner【免费下载链接】actions-runner-controllerKubernetes controller for GitHub Actions self-hosted runners项目地址: https://gitcode.com/GitHub_Trending/ac/actions-runner-controller本文基于仓库内 docs/about-arc.md 编写。该文档描述的是 ARC 的legacy传统模式即actions.summerwind.netAPI 组下的资源体系若要了解较新的 Autoscaling Runner Scale Setsactions.github.comAPI 组请参阅 docs/quickstart.md 与 docs/gha-runner-scale-set-controller/README.md 中对应的新架构说明。阅读本文前建议先通过 README.md 了解项目整体定位。导读Actions Runner ControllerARC是一个 KubernetesK8s控制器用于在 Kubernetes 集群上运行 GitHub Actions 的自托管 Runner并支持基于负载的自动伸缩。本文将从 GitHub Actions 的 Runner 生态讲起系统介绍 ARC 的架构组成自定义资源体系、RunnerDeployment 部署方式、Runner 容器镜像内容、静态与动态两种伸缩策略含 Pull Driven Scaling 的完整配置以及 GitHub Enterprise 支持与自定义 Runner 镜像的实操方法。读完本文你将能够理解 ARC 的核心设计并在自己的集群上完成自托管 Runner 的部署、伸缩与镜像定制。GitHub Actions 与 Runner 生态GitHub ActionsCI/CD 自动化平台GitHub Actions 是一个持续集成与持续交付CI/CD平台用于自动化你的构建、测试和部署流水线。你可以创建工作流Workflow对仓库的每一次 Pull Request 执行构建与测试或将合并后的 PR 自动部署到生产环境。一个工作流包含一个或多个 JobJob 可以串行或并行执行每个 Job 运行在独立的 Runner 上并包含一个或多个 Step——Step 既可以运行你自定义的脚本也可以引用可复用的 Action 扩展。两类 RunnerRunner 负责执行 GitHub Actions 工作流分配给它的 Job分为两类GitHub-hosted runners由 GitHub 在云端托管提供 Linux、Windows、macOS 虚拟机开箱即用、无需运维。Self-hosted runners托管在你自己的数据中心或云基础设施上拥有更高的硬件、操作系统和软件工具控制权。ARC 部署的正是这一类 Runner。自托管 Runner 的三种部署形态自托管 Runner 可以是物理机、虚拟机、容器也可以部署在本地或云端传统部署物理机在物理机器上安装操作系统与应用Runner 常驻运行。缺点是需要 24/7 承担硬件拥有与运维成本即使机器空闲也要持续付费。虚拟化部署VM每个 Runner 运行在一台 VM 上管理更简单但 VM 是完整操作系统每次需要干净环境时启动耗时较长。容器化部署容器与 VM 类似但拉起的是容器而非整台 VM。Kubernetes 为容器化工作负载提供了可扩展、可复现的运行环境——容器轻量、松耦合、高效且可集中管理。Actions Runner ControllerARC正是为了让自托管 Runner 在 Kubernetes 管理的容器上运行变得更简单而诞生的。ARC 是什么ARC 是一个 Kubernetes 控制器用于在你的 Kubernetes 集群上创建自托管 Runner。只需少量命令你就能搭建起一组可按需扩缩容的自托管 Runner。由于这些 Runner 是临时的ephemeral且基于容器新的 Runner 实例可以被快速、干净地拉起。ARC 的架构模式是向集群应用一组自定义资源Custom Resources控制器监控这些资源并创建对应的 PodPod 内运行 GitHub Actions Runner 组件后GitHub 便可以将这些 Pod 视作自托管 Runner并向其分配 Job。部署入口仓库提供 QuickStart 指南详见 docs/quickstart.md更详细的运行与排障文档见 README.md 中的 Legacy documentation 列表。ARC 的组成自定义资源体系五种核心 CRDARC 由若干自定义资源定义CRD构成包括资源作用Runner单个 Runner 的声明对应一个运行 GitHub Actions Runner 的 PodRunnerSet管理一组同质 Runner 的集合RunnerDeployment面向声明式滚动更新的 Runner 集合类比 K8s DeploymentRunnerReplicaSetRunnerDeployment 内部的底层副本集类比 K8s ReplicaSetHorizontalRunnerAutoscaler简称 HRA对 RunnerDeployment / RunnerSet 执行自动伸缩这些 CRD 的类型定义位于 apis/actions.summerwind.net/v1alpha1/例如 runner_types.go、runnerdeployment_types.go 与 horizontalrunnerautoscaler_types.go对应的 CRD YAML 清单在 charts/actions-runner-controller/crds/。安装 CRDHelm 命令QuickStart 指南中的 Helm 命令会将上述自定义资源安装到actions-runner-system命名空间helm install -f custom-values.yaml --wait --namespace actions-runner-system \ --create-namespace actions-runner-controller \ actions-runner-controller/actions-runner-controller其中-f custom-values.yaml用于覆盖 Chart 默认配置完整的可配置项见 charts/actions-runner-controller/values.yaml 与 charts/actions-runner-controller/README.md--wait会等待资源就绪--create-namespace则负责自动创建命名空间。部署 RunnerRunnerDeployment 详解CRD 安装完成后通过一个runnerdeployment.yaml文件即可把 Runner 部署到集群。以下是最小示例apiVersion: actions.summerwind.dev/v1alpha1 kind: RunnerDeployment metadata: name: example-runnerdeploy spec: replicas: 1 template: spec: repository: mumoshu/actions-runner-controller-ci各字段含义kind: RunnerDeployment声明这是一个 RunnerDeployment 自定义资源。replicas: 1部署 1 个副本可配置多个副本实现横向扩展详见后文静态缩放。repository: mumoshu/actions-runner-controller-ciPod 中 Actions Runner 注册时关联的仓库也可以配置为Enterprise企业或Organization组织级别对应 CRD 中的enterprise/organization字段二者与repository互斥参见 runner_types.go 中的validateRepository校验逻辑。执行kubectl apply -f runnerdeployment.yaml后ARC 会创建一个形如example-runnerdeploy-[**]的 Pod其中包含2 个容器runner容器安装并运行 GitHub Runner 组件docker容器内置 Docker 守护进程为工作流中的容器/Docker 操作提供环境。从源码结构看Runner 的 Pod 形态由 runner_pod.go 与 runner_pod_controller.go 等控制器逻辑构建RunnerDeployment 的滚动更新语义则与 K8s Deployment 类似见 runnerdeployment_types.go 中的RunnerDeploymentStatus字段注释。Runner 容器镜像GitHub-hosted runner 预装了大量软件包而 ARC 维护的 Runner 镜像并不包含GitHub Runner 镜像中的全部软件只包含其子集基础 CLI 工具包、git、docker 和 build-essentials。因此文档建议需要额外软件时优先使用对应的 setup action例如actions/setup-java安装 Java、actions/setup-node安装 Node。镜像实际内容源码佐证以仓库中的 runner/actions-runner.ubuntu-24.04.dockerfile 为例镜像基于ubuntu:24.04实际安装的软件包括基础 CLI 包curl、ca-certificates、git、jq、sudo、unzip、zipGit LFS通过 GitHub 的 git-lfs 官方仓库安装Docker下载 Docker 静态二进制并安装Docker Compose作为 Docker CLI 插件安装到/usr/libexec/docker/cli-pluginsdumb-init作为 PID 1 的 init 进程正确转发信号libyaml-dev供ruby/setup-rubyaction 使用同时拷贝了 entrypoint.sh、startup.sh、logger.sh、graceful-stop.sh 等入口脚本与 hooks 目录同目录下还维护了ubuntu-20.04、ubuntu-22.04、ubuntu-24.04的普通版、DinD 版与 DinD Rootless 版共 9 个 Dockerfile例如 actions-runner-dind.ubuntu-24.04.dockerfile、actions-runner-dind-rootless.ubuntu-24.04.dockerfile覆盖不同运行模式。执行工作流完成上述部署后即可在仓库中创建针对 ARC 自托管 Runner 的工作流。关键是让工作流的 Job 定位到自托管池在 workflow 中设置runs-on: self-hostedGitHub 会将该 Job 分发给 ARC 创建的 Runner。若要精确控制 Job 分配到哪一组 Runner可通过Runner labels标签配合runs-on的标签匹配实现详见 docs/using-arc-runners-in-a-workflow.md。静态缩放调整 replicas 数量最简单的手动伸缩方式修改runnerdeployment.yaml中的replicas数量例如改为replicas: 2ARC 会创建对应数量的 Pod每个 Pod 仍是runner docker双容器结构。这种方式适合负载相对稳定、无需自动响应的场景。动态缩放Pull Driven ScalingARC 支持两种动态伸缩机制Webhook driven scalingWebhook 驱动由 GitHub 事件即时触发Pull Driven scaling拉取驱动周期性轮询 GitHub API 获取指标计算目标副本数。本文原文档重点介绍Pull Driven Scaling模型。注意配置自动伸缩后务必移除 RunnerDeployment / RunnerSet 中的replicas字段否则两者会互相冲突详见 docs/automatically-scaling-runners.md 中的说明。启用步骤按以下 3 步即可启用创建HorizontalRunnerAutoscaler编写一个kind: HorizontalRunnerAutoscaler的资源文件设置伸缩参数minReplicas与maxReplicas分别表示伸缩的上下限配置伸缩指标ARC 目前支持PercentageRunnersBusy指标控制器会轮询 GitHub 获取 RunnerDeployment 命名空间中处于busy状态的 Runner 数量再依据你配置的缩放因子决定目标副本数。Pull Driven Scaling 完整 SchemaapiVersion: actions.summerwind.dev/v1alpha1 kind: HorizontalRunnerAutoscaler metadata: name: example-runner-deployment-autoscaler spec: scaleTargetRef: # Your RunnerDeployment Here name: example-runnerdeploy kind: RunnerDeployment minReplicas: 1 maxReplicas: 5 metrics: - type: PercentageRunnersBusy scaleUpThreshold: 0.75 scaleDownThreshold: 0.25 scaleUpFactor: 2 scaleDownFactor: 0.5字段说明结合 horizontalrunnerautoscaler_types.go 中的MetricSpec定义scaleTargetRef伸缩目标kind只能是RunnerDeployment或RunnerSetname为目标资源名minReplicas/maxReplicas伸缩下限/上限metrics[].type指标类型可取PercentageRunnersBusy或TotalNumberOfQueuedAndInProgressWorkflowRunsscaleUpThreshold/scaleDownThreshold触发扩缩容的 busy 百分比阈值字符串形式scaleUpFactor/scaleDownFactor乘数型扩缩容因子也可以改用scaleUpAdjustment/scaleDownAdjustment指定固定增减数量二者互斥详见 autoscaling.goscaleDownDelaySecondsAfterScaleOut防抖参数可覆盖默认的缩容延迟。轮询周期与防抖轮询周期由控制器的--sync-period标志定义若未提供默认同步周期为1m可按秒或分钟配置在 main.go 中通过flag.DurationVar(syncPeriod, sync-period, 1*time.Minute, ...)声明。周期越短GitHub API 速率限额消耗越快需根据环境权衡并监控 rate limit 预算。防抖Anti-Flapping默认情况下Runner 被扩容后 10 分钟内不会被缩容避免缩-扩-缩震荡。可通过--default-scale-down-delay控制器标志修改全局默认值或在 HRA 的spec.scaleDownDelaySecondsAfterScaleOut中按资源覆盖参考 docs/automatically-scaling-runners.md 中的 Anti-Flapping Configuration 一节。指标背后的实现逻辑从 autoscaling.go 源码可见PercentageRunnersBusy的计算方式控制器以当前期望副本数为基数统计 busy 与 terminating-busy 的 Runner 占比fractionBusy当其超过scaleUpThreshold时按scaleUpAdjustment或scaleUpFactor计算新副本数低于scaleDownThreshold时同理缩容。当scaleUpFactor/scaleDownFactor未显式配置时控制器使用默认值1.3与0.7源码中defaultScaleUpFactor 1.3、defaultScaleDownFactor 0.7这一点在 YAML 示例中体现为按比例扩缩容。关于第二种指标TotalNumberOfQueuedAndInProgressWorkflowRuns按指定仓库集合的排队任务数 1:1 扩容以及将两种指标组合使用PercentageRunnersBusy必须排在第一位仅当主指标返回 0 时才会回退到第二指标的详细说明见 docs/automatically-scaling-runners.md。其他高级配置ARC 还支持多种进阶配置备用 RunnerDocker-In-Docker通过dockerdWithinRunnerContainer等字段在 Runner Pod 内启用 DinD 模式相关镜像与文档见 runner/ 目录与 docs/deploying-alternative-runners.mdRunner 组管理用 Runner Groups 管理一组 Runner便于在企业内部管理不同分组见 docs/managing-access-with-runner-groups.mdWebhook 驱动伸缩基于workflow_job事件即时扩缩容可配置scaleUpTriggers与duration详见 docs/automatically-scaling-runners.mdRunner 身份验证PAT 与 GitHub App 两种认证方式见 docs/authenticating-to-the-github-api.md。GitHub Enterprise 支持ARC 同时支持GHECGitHub Enterprise Cloud、GHESGitHub Enterprise Server以及普通 GitHub。认证方面PAT个人访问令牌与 GitHub App均支持仓库级repository level和组织级organization levelRunner 的部署若要部署企业级enterprise levelRunner则只能使用 PAT认证因为 GitHub 目前不支持企业级 Runner 的 GitHub App 认证。若部署到 GHES 环境需要运行GHES 3.6.0版本。同时在控制器部署中额外注入环境变量kubectl set env deploy controller-manager -c manager GITHUB_ENTERPRISE_URLGHEC/S URL --namespace actions-runner-system注意仓库维护者没有企业环境云或服务器企业级特性的支持由社区驱动、按尽力而为原则维护欢迎社区 PR 补充与维护相关功能。Runner 镜像内置软件清单与自定义镜像云工具与内置软件策略云工具链项目支持部署在各类云 Kubernetes 平台如 AWS EKS但不在基础 Runner 镜像中捆绑任何云特定工具这是刻意决策以控制维护成本。内置软件ARC 维护多个基于 Ubuntu 的 Runner 镜像仅包含 GitHub Runner 镜像软件的一个子集类别软件基础 CLIcurl、ca-certificates、git、jq、sudo、unzip、zip 等基础包版本控制Git、Git LFS容器工具Docker、Docker Compose这些均可在 runner/actions-runner.ubuntu-24.04.dockerfile 中逐条核实。GitHub 官方虚拟环境包含更多软件不同版本的 Java、Node.js、Golang、.NET 等Runner 镜像未提供但大多有对应的 setup action如actions/setup-java、actions/setup-node可在工作流中按需安装。构建自定义 Runner 镜像如果需要在镜像中加入没有 setup action 的软件包最简方式是以summerwind/actions-runner镜像为基础在 Dockerfile 中直接安装额外依赖FROM summerwind/actions-runner:latest RUN sudo apt-get update -y \ sudo apt-get install $YOUR_PACKAGES \ sudo rm -rf /var/lib/apt/lists/*然后通过 RunnerDeployment 或 RunnerSet 的image字段指定自定义镜像apiVersion: actions.summerwind.dev/v1alpha1 kind: RunnerDeployment metadata: name: custom-runner spec: repository: actions/actions-runner-controller image: YOUR_CUSTOM_RUNNER_IMAGE除image外spec.template.spec下还支持大量 Pod 级字段如resources、nodeSelector、tolerations、env、volumes、dockerMTU、dockerRegistryMirror、workDir、ephemeral等其完整清单可在 runner_types.go 的RunnerConfig/RunnerPodSpec结构与 docs/automatically-scaling-runners.md 的 Additional Settings 一节中查阅。延伸阅读本文是 ARC 的入门概览围绕在 K8s 上部署与伸缩自托管 Runner的主线展开。更深入的专题文档均在本仓库中快速开始docs/quickstart.md部署 Runnerdocs/deploying-arc-runners.md自动伸缩含 Webhook 驱动、Schedule Overrides、缩容至 0、优雅终止配置docs/automatically-scaling-runners.mdRunner 归属选择仓库/组织/企业docs/choosing-runner-destination.md工作流中使用 Runner 与标签docs/using-arc-runners-in-a-workflow.md自定义存储卷docs/using-custom-volumes.md监控与排障docs/monitoring-and-troubleshooting.md【免费下载链接】actions-runner-controllerKubernetes controller for GitHub Actions self-hosted runners项目地址: https://gitcode.com/GitHub_Trending/ac/actions-runner-controller创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考