关于 Actions Runner Controller

Actions Runner Controller (ARC) 是 Kubernetes 运算符，用于协调和缩放 GitHub Actions 的自托管运行器。有关详细信息，请参阅 Kubernetes 文档中的运算符模式。

使用 ARC，可以创建运行器规模集，以便根据存储库、组织或企业中运行的工作流数量自动缩放。受控的运行器可以是临时且基于容器的运行器，因此新的运行器实例可以快速顺利地纵向扩展或缩减。有关自动缩放的详细信息，请参阅“使用自托管运行器自动缩放”。

下图演示了 ARC 自动缩放运行器规模集模式的体系结构。

Note

若要以更大的尺寸查看下图，请参阅 Actions Runner Controller 存储库中的自动缩放运行器规模集模式文档。

显示 ARC 自动缩放运行器规模集模式的示意图。

Actions Runner Controller 是使用提供的 Helm 图表安装的，控制器管理器 Pod 部署在指定的命名空间中。通过提供的 Helm 图表或自定义清单文件部署新的 AutoScalingRunnerSet 资源。 AutoScalingRunnerSet 控制器调用 GitHub 的 API 来提取运行器规模集所属的运行器组 ID。
在创建运行器规模集侦听器资源之前，AutoScalingRunnerSet 控制器会再调用 API 一次，以在 GitHub Actions 服务中提取或创建运行器规模集。
运行器规模集侦听器 Pod 由 AutoScalingListener 控制器部署。在此 Pod 中，侦听器应用程序连接到 GitHub Actions 服务，以验证并建立 HTTPS 长轮询连接。侦听器将保持空闲状态，直到收到来自 GitHub Actions 服务的 Job Available 消息。
从存储库触发工作流运行时，GitHub Actions 服务将单个作业运行分派到 runs-on 键与运行器规模集的名称或自托管运行器的标签相匹配的运行器或运行器规模集。
当运行器规模集侦听器收到 Job Available 消息时，它会检查它是否可以纵向扩展到所需的计数。如果可以，运行器规模集侦听器将确认该消息。
运行器规模集侦听器使用一个服务帐户和一个绑定到该帐户的角色，通过 Kubernetes API 进行 HTTPS 调用，使用所需的副本计数修补 Ephemeral RunnerSet 资源。
Ephemeral RunnerSet 尝试创建新的运行器，EphemeralRunner 控制器请求实时 (JIT) 配置令牌来注册这些运行器。该控制器尝试创建运行器 Pod。如果 Pod 的状态为 failed，则该控制器最多重试 5 次。 24 小时后，如果没有运行器接受作业，GitHub Actions 服务会取消分配该作业。
创建运行器 Pod 后，Pod 中的运行器应用程序使用 JIT 配置令牌向 GitHub Actions 服务注册自身。然后，它建立另一个 HTTPS 长轮询连接，以接收它需要执行的作业详细信息。
GitHub Actions 服务确认运行器注册并分派作业运行详细信息。
在整个作业运行执行过程中，运行器持续地将日志和作业运行状态传达回 GitHub Actions 服务。
运行器成功完成其作业后，EphemeralRunner 控制器会使用 GitHub Actions 服务进行检查，查看是否可以删除运行器。如果可以，Ephemeral RunnerSet 将删除运行器。

Actions Runner Controller 组件

ARC 由一组资源组成，其中一些资源专为 ARC 而创建。 ARC 部署将这些资源应用到 Kubernetes 群集。应用后，它会创建一组 Pod，其中包含你的自托管运行器的容器。借助 ARC，GitHub 可以将这些运行器容器视为自托管运行器，并根据需要向其分配作业。

ARC 部署的每个资源都有一个包含以下各项的名称：

安装名称，即安装 Helm 图表时指定的安装名称。
资源标识后缀，即标识资源类型的字符串。此值是不可配置的。

Note

不同版本的 Kubernetes 对资源名称有不同的长度限制。通过添加安装名称长度和资源标识后缀长度来计算资源名称的长度限制。如果资源名称的长度超过预留长度，将收到错误。

`gha-runner-scale-set-controller` 部署的资源

模板	资源种类	名称	预留长度	说明	备注
`deployment.yaml`	部署	INSTALLATION_NAME-gha-rs-controller	18	运行控制器管理器的资源	此资源创建的 Pod 具有 ReplicaSet 后缀和 Pod 后缀。
`serviceaccount.yaml`	ServiceAccount	INSTALLATION_NAME-gha-rs-controller	18	如果 `values.yaml` 中的 `serviceAccount.create` 设置为 true，则会创建此项。	可以在 `values.yaml` 中自定义名称
`manager_cluster_role.yaml`	ClusterRole	INSTALLATION_NAME-gha-rs-controller	18	控制器管理器的 ClusterRole	如果 `flags.watchSingleNamespace` 的值为空，则会创建此项。
`manager_cluster_role_binding.yaml`	ClusterRoleBinding	INSTALLATION_NAME-gha-rs-controller	18	控制器管理器的 ClusterRoleBinding	如果 `flags.watchSingleNamespace` 的值为空，则会创建此项。
`manager_single_namespace_controller_role.yaml`	角色	INSTALLATION_NAME-gha-rs-controller-single-namespace	35	控制器管理器的角色	如果 `flags.watchSingleNamespace` 的值已设置，则会创建此项。
`manager_single_namespace_controller_role_binding.yaml`	RoleBinding	INSTALLATION_NAME-gha-rs-controller-single-namespace	35	控制器管理器的 RoleBinding	如果 `flags.watchSingleNamespace` 的值已设置，则会创建此项。
`manager_single_namespace_watch_role.yaml`	角色	INSTALLATION_NAME-gha-rs-controller-single-namespace-watch	41	所配置命名空间控制器管理器的角色	如果 `flags.watchSingleNamespace` 的值已设置，则会创建此项。
`manager_single_namespace_watch_role_binding.yaml`	RoleBinding	INSTALLATION_NAME-gha-rs-controller-single-namespace-watch	41	所配置命名空间控制器管理器的 RoleBinding	如果 `flags.watchSingleNamespace` 的值已设置，则会创建此项。
`manager_listener_role.yaml`	角色	INSTALLATION_NAME-gha-rs-controller-listener	26	侦听器的角色	此项始终创建。
`manager_listener_role_binding.yaml`	RoleBinding	INSTALLATION_NAME-gha-rs-controller-listener	26	侦听器的 RoleBinding	此项始终创建，并将侦听器角色与服务帐户绑定，后者由 `serviceaccount.yaml` 创建或使用 `values.yaml` 配置。

`gha-runner-scale-set` 部署的资源

模板	资源种类	名称	预留长度	说明	备注
`autoscalingrunnerset.yaml`	AutoscalingRunnerSet	INSTALLATION_NAME	0	使用规模集的顶级资源	名称长度不能超过 45 个字符。
`no_permission_service_account.yaml`	ServiceAccount	INSTALLATION_NAME-gha-rs-no-permission	21	装载到运行器容器的服务帐户	如果容器模式并非 "kubernetes" 且 `template.spec.serviceAccountName` 未指定，则会创建此项。
`githubsecret.yaml`	机密	INSTALLATION_NAME-gha-rs-github-secret	20	包含对 GitHub API 进行身份验证所需值的机密	如果 `githubConfigSecret` 为对象，则会创建此项。如果提供了字符串，则不会创建此机密。
`manager_role.yaml`	角色	INSTALLATION_NAME-gha-rs-manager	15	提供给管理员以便能够协调自动缩放运行器集命名空间中资源的角色	此项始终创建。
`manager_role_binding.yaml`	RoleBinding	INSTALLATION_NAME-gha-rs-manager	15	将 manager_role 绑定到管理员服务帐户。	此项始终创建。
`kube_mode_role.yaml`	角色	INSTALLATION_NAME-gha-rs-kube-mode	17	为挂钩提供必要权限的角色	容器模式设置为 "kubernetes" 且 `template.spec.serviceAccount` 未提供时，将创建此项。
`kube_mode_serviceaccount.yaml`	ServiceAccount	INSTALLATION_NAME-gha-rs-kube-mode	17	绑定到运行器 Pod 的服务帐户。	容器模式设置为 "kubernetes" 且 `template.spec.serviceAccount` 未提供时，将创建此项。

关于自定义资源

ARC 由一些自定义资源定义 (CRD) 组成。有关自定义资源的详细信息，请参阅 Kubernetes 文档中的自定义资源。可以在下面的 API 架构定义中找到用于 ARC 的自定义资源定义列表。

由于自定义资源是 Kubernetes API 的扩展，因此它们在默认的 Kubernetes 安装中不可用。需要安装这些自定义资源才能使用 ARC。有关安装自定义资源的详细信息，请参阅“操作运行器控制器快速入门”。

安装自定义资源后，就可以将 ARC 部署到 Kubernetes 群集了。有关部署 ARC 的信息，请参阅“使用 Actions Runner Controller 部署运行器规模集”。

关于运行器容器映像

GitHub 维护最小运行器容器映像。每个运行器二进制文件版本都会发布一个新映像。最新的映像将有运行器二进制文件版本和 latest 标记。

此映像包含容器运行时和运行器二进制文件所需的最少数量的包。若要安装其他软件，可以创建你自己的运行器映像。可以使用 ARC 的运行器映像作为基础，或使用相应的设置操作。例如，使用面向 Java 的 actions/setup-java 或面向 Node 的 actions/setup-node。

可在此 Dockerfile 中找到 ARC 运行器映像的定义，并在此 Dockerfile 中找到基础映像的定义。

创建自己的运行器映像

你可以创建自己的运行器映像来满足你的要求。运行器映像必须满足以下条件。

使用可运行自托管运行器应用程序的基础映像。有关详细信息，请参阅“关于自托管运行程序”。
必须将运行器二进制文件放置在 /home/runner/ 下并使用 /home/runner/run.sh 启动。
如果使用 Kubernetes 模式，必须将运行器容器挂钩放置在 /home/runner/k8s 下。

可以使用以下示例 Dockerfile 开始创建自己的运行器映像。

Dockerfile

FROM mcr.microsoft.com/dotnet/runtime-deps:6.0 as build

# Replace value with the latest runner release version
# source: https://github.com/actions/runner/releases
# ex: 2.303.0
ARG RUNNER_VERSION=""
ARG RUNNER_ARCH="x64"
# Replace value with the latest runner-container-hooks release version
# source: https://github.com/actions/runner-container-hooks/releases
# ex: 0.3.1
ARG RUNNER_CONTAINER_HOOKS_VERSION=""

ENV DEBIAN_FRONTEND=noninteractive
ENV RUNNER_MANUALLY_TRAP_SIG=1
ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1

RUN apt update -y && apt install curl unzip -y

RUN adduser --disabled-password --gecos "" --uid 1001 runner \
    && groupadd docker --gid 123 \
    && usermod -aG sudo runner \
    && usermod -aG docker runner \
    && echo "%sudo   ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers \
    && echo "Defaults env_keep += \"DEBIAN_FRONTEND\"" >> /etc/sudoers

WORKDIR /home/runner

RUN curl -f -L -o runner.tar.gz https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-${RUNNER_ARCH}-${RUNNER_VERSION}.tar.gz \
    && tar xzf ./runner.tar.gz \
    && rm runner.tar.gz

RUN curl -f -L -o runner-container-hooks.zip https://github.com/actions/runner-container-hooks/releases/download/v${RUNNER_CONTAINER_HOOKS_VERSION}/actions-runner-hooks-k8s-${RUNNER_CONTAINER_HOOKS_VERSION}.zip \
    && unzip ./runner-container-hooks.zip -d ./k8s \
    && rm runner-container-hooks.zip

USER runner

FROM mcr.microsoft.com/dotnet/runtime-deps:6.0 as build

# Replace value with the latest runner release version
# source: https://github.com/actions/runner/releases
# ex: 2.303.0
ARG RUNNER_VERSION=""
ARG RUNNER_ARCH="x64"
# Replace value with the latest runner-container-hooks release version
# source: https://github.com/actions/runner-container-hooks/releases
# ex: 0.3.1
ARG RUNNER_CONTAINER_HOOKS_VERSION=""

ENV DEBIAN_FRONTEND=noninteractive
ENV RUNNER_MANUALLY_TRAP_SIG=1
ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1

RUN apt update -y && apt install curl unzip -y

RUN adduser --disabled-password --gecos "" --uid 1001 runner \
    && groupadd docker --gid 123 \
    && usermod -aG sudo runner \
    && usermod -aG docker runner \
    && echo "%sudo   ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers \
    && echo "Defaults env_keep += \"DEBIAN_FRONTEND\"" >> /etc/sudoers

WORKDIR /home/runner

RUN curl -f -L -o runner.tar.gz https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-${RUNNER_ARCH}-${RUNNER_VERSION}.tar.gz \
    && tar xzf ./runner.tar.gz \
    && rm runner.tar.gz

RUN curl -f -L -o runner-container-hooks.zip https://github.com/actions/runner-container-hooks/releases/download/v${RUNNER_CONTAINER_HOOKS_VERSION}/actions-runner-hooks-k8s-${RUNNER_CONTAINER_HOOKS_VERSION}.zip \
    && unzip ./runner-container-hooks.zip -d ./k8s \
    && rm runner-container-hooks.zip

USER runner

运行器二进制文件
运行器容器挂钩
Docker（Docker-in-Docker 模式下需要）

有关详细信息，请参阅 Actions 存储库中的 ARC 运行器映像 Dockerfile。

资产和发布

ARC 以两个 Helm 图表和一个容器映像的形式发布。 Helm 图表仅作为开放容器计划 (OCI) 包发布。 ARC 不通过 GitHub Pages 提供 tarball 或 Helm 存储库。

可以在 GitHub Packages 上找到最新版本的 ARC Helm 图表和容器映像：

支持的运行器映像作为单独的容器映像发布，可在 GitHub Packages 上 actions-runner 处找到。

法律通告

部分内容改编自 Apache-2.0 许可证下的 https://github.com/actions/actions-runner-controller/ ：

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

关于 Actions Runner Controller

本文内容