actions-runner-controller v0.26.0 升级实战Rootless DinD、多租户、细粒度 Runner 状态与自动扩缩容指标全解析【免费下载链接】actions-runner-controllerKubernetes controller for GitHub Actions self-hosted runners项目地址: https://gitcode.com/GitHub_Trending/ac/actions-runner-controlleractions-runner-controllerARCv0.26.0 是面向生产环境自托管 GitHub Actions Runner 的重要版本围绕安全加固、可观测性与多租户运维三大方向引入多项能力无根rootlessDinD Runner、细粒度实时 Runner 状态上报、更丰富的自动扩缩容 Prometheus 指标、跨企业与组织的多租户凭据支持以及启动版本号打印。本文以官方发布说明为主线结合仓库源码与 Helm chart 配置逐项讲解升级要点、新特性的启用方式、配置参数与底层实现帮助你在升级到 v0.26.0 后平稳落地这些能力。一、版本概览与升级要点v0.26.0 的变更可分为两类破坏性变更breaking changes与增强enhancements。破坏性变更会影响现有部署的兼容性增强则在默认行为之外提供可选的开关式能力多数需要显式配置才能生效。1.1 升级前必读Helm Chart 与 CRD如果你使用 Helm chart 部署 ARC升级到 v0.26.0 时必须同步将 chart 升级到 0.21.0 或更高版本。同时请务必手动升级 CRD——这是 Helm 的已知行为Helm 不会自动升级集群中已安装的 CRD需要单独执行kubectl apply应用新版本的 CRD 清单。仓库中的 CRD 清单位于 config/crd/baseskustomize 形态以及 charts/actions-runner-controller/crdschart 内嵌形态。升级提醒跳过 CRD 升级是 ARC 升级中最常见的未定义字段与校验失败类问题的根源v0.26.0 引入的新字段如多租户的githubAPICredentialsFrom在旧 CRD 下会被 API Server 拒绝。1.2 破坏性变更GitHub Enterprise Server 最低版本提升至 3.6v0.26.0 将最低支持的 GitHub Enterprise ServerGHES版本提升至3.6.0。动机是使用 GHES 3.6 在 list runner groups API 中新增的visible_to_repository选项用于支撑基于 Runner Group 可见性的自动扩缩容——当你拥有大量标签集合互不相同的 Runner Group 时这一能力尤为关键。如果你完全没有使用 Runner GroupARC 的既有功能可能仍然可以工作发布说明原话为ARC may just work, but YMMV但官方明确以 3.6 为最低支持基线低于该版本的 GHES 不在支持范围内。仓库中与 Runner Group 可见性相关的实现可参考 simulator/runnergroup_visibility.go。二、增强Rootless DinD无根 Docker-in-DockerRunner2.1 什么是 Rootless DinD标准 DinDDocker-in-Docker模式下runner 容器内同时运行 Docker daemon 和 runner agent二者都以root用户运行——工作流 job 因此拥有执行特权操作的能力攻击面较大。而rootless DinD是 Docker 的近期增强它允许 Docker daemon 及其容器不依赖root用户运行。在 ARC 的场景中rootless DinD runner仍然需要 privileged 容器才能运行这是 Docker rootless 模式对内核能力的要求但运行 Docker daemon 和actions/runneragent 的 Linux 用户变为非 root。相比在 privileged 容器内直接跑 DinD这显著降低了安全风险随机的恶意工作流 job 不再能够执行特权操作。2.2 源码实现入口脚本与镜像仓库为 rootless DinD 提供了独立的入口脚本 runner/entrypoint-dind-rootless.sh 以及对应各 Ubuntu 版本的 Dockerfile例如 runner/actions-runner-dind-rootless.ubuntu-22.04.dockerfile、runner/actions-runner-dind-rootless.ubuntu-24.04.dockerfile。从 入口脚本 可以看到其关键流程启动前先写入 Docker daemon 配置文件/home/runner/.config/docker/daemon.json注意路径位于非 root 用户的 home 目录下而非/etc/docker/依据环境变量动态写入配置项预处理/home/runner/.local/share目录的属主为runner:runner避免 rootless dockerd 因权限错误启动失败通过dumb-init拉起dockerd-rootless.sh与 runner 启动脚本startup.sh并保持对 SIGTERM 的优雅处理。2.3 可用的 Docker 配置参数入口脚本支持的配置项如下均可通过 runner 的环境变量或spec.template.spec.env注入环境变量写入 daemon.json 的字段说明MTUmtu设置 Docker 网络 MTU同时写入DOCKERD_ROOTLESS_ROOTLESSKIT_MTU到/etc/environment供 rootlesskit 网络栈使用DOCKER_DEFAULT_ADDRESS_POOL_BASEdefault-address-pools[].base默认地址池起始网段需与DOCKER_DEFAULT_ADDRESS_POOL_SIZE同时设置DOCKER_DEFAULT_ADDRESS_POOL_SIZEdefault-address-pools[].size默认地址池子网大小用于规避 docker 网桥与集群 CIDR 冲突DOCKER_REGISTRY_MIRRORregistry-mirrors[0]镜像加速/镜像仓库镜像地址脚本逻辑清晰地体现在 entrypoint-dind-rootless.sh 的第 926 行当MTU等变量非空时用jq修改 daemon.json 后原子替换。2.4 如何选用如果你没有使用 Kubernetes 容器模式即 job 直接在 runner 容器内执行而不是以 Pod 方式动态创建官方强烈建议改用 rootless DinD它在你仍然需要从工作流内调用 Docker 容器与docker build的前提下提供了额外一层安全隔离。选择镜像时将 runner 镜像从actions-runner-dind系列替换为actions-runner-dind-rootless系列即可。三、增强更细粒度、实时的 Runner 状态3.1 旧三阶段状态的局限在 v0.26.0 之前由RunnerDeployment管理的每个Runner资源只能向kubectl get runner暴露三种 Phase且它们只是 Pod phase 的直接拷贝Pendingrunner Pod 等待被调度到某个 Kubernetes 节点RunningPod 已被调度Linux 命名空间、容器与网络已就绪容器主进程正在运行SucceededPod 容器主进程以退出码 0 结束。正如发布说明指出的这套状态几乎无用——它完全无法反映 runner agent 在 Pod 内部的注册进度以及工作流 job 是否正在其上执行。3.2 新状态机Registering / Idle / Running自 PR #1268 起ARC 可选地提供两个新阶段并重构了Running阶段。启用后你将看到Registeringrunner 入口点已启动注册流程注册成功后阶段更新为IdleIdlerunner 已成功注册到 GitHub正在等待 GitHub 分配工作流 jobRunningGitHub 已分配工作流 jobrunner agent 开始执行它。这三个阶段的排障价值远高于旧状态若长时间停留在Registering数分钟仍未结束极可能是GitHub API 凭据配置错误或 runner Pod 被破坏导致无法完成注册若已入队了工作流 job却始终卡在Idle则很可能是runner 标签配置错误或工作流定义中的on触发字段未匹配到该 runner 的标签。3.3 启用方式该能力默认关闭需要同时满足两个条件控制器侧通过控制器新增的命令行 flag 开启在 Helm chart 中对应runner.statusUpdateHook.enabled值RBAC 侧为 runner Pod 授予更新自身状态所需的权限。Helm 默认值为false见 charts/actions-runner-controller/values.yaml 第 6567 行runner: statusUpdateHook: enabled: false当开启后chart 会为 runner 注入额外的 Role/RoleBinding/ServiceAccount 与控制器 flag相关模板逻辑见 charts/actions-runner-controller/templates/deployment.yaml 与 charts/actions-runner-controller/templates/manager_role.yamlchart 参数说明见 charts/actions-runner-controller/README.md。3.4 底层实现update-status 脚本Runner 容器内的状态上报由脚本 runner/update-status 完成。其核心逻辑是当环境变量RUNNER_STATUS_UPDATE_HOOKtrue时读取 Pod 挂载的 service account token通过 Kubernetes API 对当前Runner资源的/status子资源发起merge-patch请求一次性写入status.phase、status.message以及完整的 workflow 信息apiserverhttps://${KUBERNETES_SERVICE_HOST}:${KUBERNETES_SERVICE_PORT_HTTPS} ... curl --cacert ${serviceaccount}/ca.crt \ --header Content-Type: application/merge-patchjson \ --request PATCH \ ${apiserver}/apis/actions.summerwind.dev/v1alpha1/namespaces/${namespace}/runners/${HOSTNAME}/status其中 workflow 字段GITHUB_REPOSITORY、GITHUB_RUN_ID、GITHUB_JOB等对应RunnerStatus.WorkflowStatus结构体其定义见 apis/actions.summerwind.net/v1alpha1/runner_types.go。Runner 控制器在构造 runner Pod 时会注入RUNNER_STATUS_UPDATE_HOOK环境变量见 controllers/actions.summerwind.net/runner_controller.go 第 902904 行。Runner 内置的钩子脚本在 job 生命周期关键点调用该脚本例如 runner/hooks/job-started.d/update-status 在 job 开始时执行exec update-status Running Run $GITHUB_RUN_ID from $GITHUB_REPOSITORY对应地job 完成后由 runner/hooks/job-completed.d/update-status 更新回Idle等状态。启用后kubectl get runner的输出列Status、Message、WF Repo、WF Run等见 runner_types.go 中的 printcolumn 注解即可实时反映注册与 job 执行的完整链路。四、增强更丰富的自动扩缩容指标v0.26.0 为基于拉取pull-based的自动扩缩容新增了多组 Prometheus 指标便于接入 Grafana 等监控告警体系观察扩缩容行为。这些指标以 Prometheus exposition format 暴露定义位于 controllers/actions.summerwind.net/metrics/horizontalrunnerautoscaler.go。4.1PercentageRunnersBusy相关指标5 个指标名含义horizontalrunnerautoscaler_replicas_desired期望副本数desired replicashorizontalrunnerautoscaler_runnersrunner 总数horizontalrunnerautoscaler_runners_registered已注册 runner 数horizontalrunnerautoscaler_runners_busy忙碌 runner 数horizontalrunnerautoscaler_terminating_busy正在终止但仍忙碌的 runner 数4.2TotalNumberOfQueuedAndInProgressWorkflowRuns相关指标5 个指标名含义horizontalrunnerautoscaler_necessary_replicas依据队列计算出的必要副本数horizontalrunnerautoscaler_workflow_runs_completed已完成的工作流运行数horizontalrunnerautoscaler_workflow_runs_in_progress进行中的工作流运行数horizontalrunnerautoscaler_workflow_runs_queued排队中的工作流运行数horizontalrunnerautoscaler_workflow_runs_unknown状态未知的工作流运行数4.3 指标标签从源码定义可见这些指标均为GaugeVec携带以下维度标签便于按企业、组织、仓库或 Runner 种类聚合hra_name、hra_namespaceHorizontalRunnerAutoscaler 的名称与命名空间enterprise、organization、repositoryrunner 所属的 GitHub 层级kind、name被扩缩容资源如 RunnerSet / RunnerDeployment的种类与名称。对应的写入函数SetHorizontalRunnerAutoscalerPercentageRunnersBusy与SetHorizontalRunnerAutoscalerQueuedAndInProgressWorkflowRuns同样位于 horizontalrunnerautoscaler.go。结合指标进行告警时可用horizontalrunnerautoscaler_runners_registered与horizontalrunnerautoscaler_runners_busy的比值判断 runner 池的利用率用horizontalrunnerautoscaler_workflow_runs_queued判断扩容是否及时。五、增强改进的多租户支持5.1 背景从一实例一凭据到一实例多凭据在企业环境中通常有多个 GitHub 组织需要自托管 runner。在 v0.26.0 之前ARC 实例只能处理一组GitHub API 凭据一个 PAT 或一个 GitHub App因此每个企业乃至每个组织都要部署维护一套独立的 ARC运维开销巨大。v0.26.0 引入多租户支持打破了这一限制现在一个 ARC 实例可以管理多个企业与多个组织。核心机制是在 runner spec 中新增githubAPICredentialsFrom字段——创建一个包含 GitHub API 凭据的 Kubernetes Secret并在该字段中指定 Secret 名称ARC 会在调谐reconciliation时按资源分别拾取并使用对应的凭据。仓库中完整的进阶指南见 docs/using-arc-across-organizations.md。5.2 字段的适用位置githubAPICredentialsFrom在以下资源的配置位置不同HorizontalRunnerAutoscalerspec.githubAPICredentialsFrom.secretRef.nameRunnerSetspec.githubAPICredentialsFrom.secretRef.nameRunnerDeploymentspec.template.spec.githubAPICredentialsFrom.secretRef.name说明Runner、RunnerReplicaSet及 runner Pod 同样存在该字段或等价的 Pod 注解但它们是RunnerDeployment与 ARC 管理的实现细节通常无需手动设置。底层类型定义见 apis/actions.summerwind.net/v1alpha1/runner_types.goRunnerConfig内嵌GitHubAPICredentialsFrom指向SecretRef仅含name并通过 CRD 暴露到Runner、RunnerSet、RunnerDeployment等资源的 spec 中。5.3 推荐的组织方式与完整示例通常每个 GitHub 组织准备一组 GitHub App 凭据每个组织的 runner group 对应一个RunnerDeployment加一个HorizontalRunnerAutoscaler。因此每个组织大致包含1 个包含 GitHub App 凭据的 Kubernetes Secret每个 Runner Group 各 1 个RunnerDeployment/RunnerSet与 1 个HorizontalRunnerAutoscaler。RunnerDeployment/RunnerSet与HorizontalRunnerAutoscaler应设置相同的spec.githubAPICredentialsFrom.secretRef.name指向同一个 Secret。完整示例kind: Secret data: github_app_id: ... github_app_installation_id: ... github_app_private_key: ... --- kind: RunnerDeployment metadata: namespace: org1-runners spec: template: spec: githubAPICredentialsFrom: secretRef: name: org1-github-app --- kind: HorizontalRunnerAutoscaler metadata: namespace: org1-runners spec: githubAPICredentialsFrom: secretRef: name: org1-github-app为什么要重复设置两次因为 ARC 中不同组件horizontalrunnerautoscaler-controller、runnerdeployment-controller、runnerreplicaset-controller、runner-controller、runnerpod-controller在不同时机分别发起 GitHub API 调用为同一组 runner 的相关调用指定相同凭据才能保证整个生命周期内的行为一致。多租户场景下凭据的解析与复用逻辑可在 controllers/actions.summerwind.net/multi_githubclient.go 中进一步查看。关于如何创建包含 GitHub App 凭据的 Secretgithub_app_id、github_app_installation_id、github_app_private_key请参考 docs/authenticating-to-the-github-api.md 中使用 GitHub App 认证部署一节。六、增强启动时打印版本号与 HTTP User-Agent6.1 日志中的版本号v0.26.0 起构建脚本会将 ARC 版本号注入可执行文件并在启动时打印到日志中。这样在提交 bug 报告时直接从日志即可确认正在运行的 ARC 版本无需再去核对容器镜像 tag 或 chart 的appVersion。版本注入通过 Go 的ldflags完成构建时将github.com/actions/actions-runner-controller/build.Version与build.CommitSHA写入二进制见 Dockerfile 第 3943 行与 Makefile版本变量的默认回退值定义在 build/version.go。6.2 每次 GitHub API 调用的 User-Agent除了日志ARC 的每一次 GitHub Actions API 调用都会携带包含版本号的 HTTPUser-Agent头。日常使用中你不会直接依赖它但 GitHub 及其 Actions 后端服务可以据此统计各版本 ARC 的使用分布。该能力的实现同样在 controllers/actions.summerwind.net/runner_controller.go 第 906908 行控制器在构造 runner Pod 时注入环境变量GITHUB_ACTIONS_RUNNER_EXTRA_USER_AGENTactions-runner-controller/versionGitHub runner agent 会将该环境变量拼接到其发出的 API 请求 User-Agent 中从而让服务端识别 ARC 版本。七、总结升级 v0.26.0 的行动清单综合上述变更升级到 v0.26.0 并应用新特性的最小行动清单如下升级准备将 Helm chart 升级至 0.21.0并手动应用新版本 CRDcharts/actions-runner-controller/crds评估基线确认 GitHub Enterprise Server 版本不低于 3.6安全增强可选未使用 Kubernetes 容器模式的场景将 DinD runner 镜像切换为 rootless 系列actions-runner-dind-rootless.*并按需配置MTU、地址池与镜像镜像参数可观测性增强可选设置runner.statusUpdateHook.enabled: true开启细粒度 Runner 状态上报配合kubectl get runner与新增的扩缩容指标horizontalrunnerautoscaler_runners_busy、horizontalrunnerautoscaler_workflow_runs_queued等建立监控告警多租户落地可选为每个组织创建含 GitHub App 凭据的 Secret并在RunnerDeployment/RunnerSet与HorizontalRunnerAutoscaler上设置githubAPICredentialsFrom.secretRef.name用一个 ARC 实例统一管理多个组织版本确认查看启动日志中的版本号确认运行版本符合预期。其中状态上报、多租户与指标等能力的完整闭环均可结合 runner/update-status、docs/using-arc-across-organizations.md 与 controllers/actions.summerwind.net/metrics/horizontalrunnerautoscaler.go 等源码与文档进一步深入。【免费下载链接】actions-runner-controllerKubernetes controller for GitHub Actions self-hosted runners项目地址: https://gitcode.com/GitHub_Trending/ac/actions-runner-controller创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考