关于 Actions Runner Controller

您可以托管自己的运行器，并自定义用于在 GitHub Actions 工作流程中运行作业的环境。

本文内容

法律通告

关于 Actions Runner Controller

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

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

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

Note

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

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

  1. Actions Runner Controller 是使用提供的 Helm 图表安装的，控制器管理器 Pod 部署在指定的命名空间中。 通过提供的 Helm 图表或自定义清单文件部署新的 AutoScalingRunnerSet 资源。 AutoScalingRunnerSet 控制器调用 GitHub 的 API 来提取运行器规模集所属的运行器组 ID。
  2. 在创建运行器规模集侦听器资源之前，AutoScalingRunnerSet 控制器会再调用 API 一次，以在 GitHub Actions 服务中提取或创建运行器规模集。
  3. 运行器规模集侦听器 Pod 由 AutoScalingListener 控制器部署。 在此 Pod 中，侦听器应用程序连接到 GitHub Actions 服务，以验证并建立 HTTPS 长轮询连接。 侦听器将保持空闲状态，直到收到来自 GitHub Actions 服务的 Job Available 消息。
  4. 从存储库触发工作流运行时，GitHub Actions 服务将单个作业运行分派到 runs-on 键与运行器规模集的名称或自托管运行器的标签相匹配的运行器或运行器规模集。
  5. 当运行器规模集侦听器收到 Job Available 消息时，它会检查它是否可以纵向扩展到所需的计数。 如果可以，运行器规模集侦听器将确认该消息。
  6. 运行器规模集侦听器使用一个服务帐户和一个绑定到该帐户的角色，通过 Kubernetes API 进行 HTTPS 调用，使用所需的副本计数修补 Ephemeral RunnerSet 资源。
  7. Ephemeral RunnerSet 尝试创建新的运行器，EphemeralRunner 控制器请求实时 (JIT) 配置令牌来注册这些运行器。 该控制器尝试创建运行器 Pod。 如果 Pod 的状态为 failed，则该控制器最多重试 5 次。 24 小时后，如果没有运行器接受作业，GitHub Actions 服务会取消分配该作业。
  8. 创建运行器 Pod 后，Pod 中的运行器应用程序使用 JIT 配置令牌向 GitHub Actions 服务注册自身。 然后，它建立另一个 HTTPS 长轮询连接，以接收它需要执行的作业详细信息。
  9. GitHub Actions 服务确认运行器注册并分派作业运行详细信息。
  10. 在整个作业运行执行过程中，运行器持续地将日志和作业运行状态传达回 GitHub Actions 服务。
  11. 运行器成功完成其作业后，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-controller18运行控制器管理器的资源此资源创建的 Pod 具有 ReplicaSet 后缀和 Pod 后缀。
serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-controller18如果 values.yaml 中的 serviceAccount.create 设置为 true，则会创建此项。可以在 values.yaml 中自定义名称
manager_cluster_role.yamlClusterRoleINSTALLATION_NAME-gha-rs-controller18控制器管理器的 ClusterRole如果 flags.watchSingleNamespace 的值为空，则会创建此项。
manager_cluster_role_binding.yamlClusterRoleBindingINSTALLATION_NAME-gha-rs-controller18控制器管理器的 ClusterRoleBinding如果 flags.watchSingleNamespace 的值为空，则会创建此项。
manager_single_namespace_controller_role.yaml角色INSTALLATION_NAME-gha-rs-controller-single-namespace35控制器管理器的角色如果 flags.watchSingleNamespace 的值已设置，则会创建此项。
manager_single_namespace_controller_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace35控制器管理器的 RoleBinding如果 flags.watchSingleNamespace 的值已设置，则会创建此项。
manager_single_namespace_watch_role.yaml角色INSTALLATION_NAME-gha-rs-controller-single-namespace-watch41所配置命名空间控制器管理器的角色如果 flags.watchSingleNamespace 的值已设置，则会创建此项。
manager_single_namespace_watch_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41所配置命名空间控制器管理器的 RoleBinding如果 flags.watchSingleNamespace 的值已设置，则会创建此项。
manager_listener_role.yaml角色INSTALLATION_NAME-gha-rs-controller-listener26侦听器的角色此项始终创建。
manager_listener_role_binding.yaml RoleBindingINSTALLATION_NAME-gha-rs-controller-listener26侦听器的 RoleBinding此项始终创建，并将侦听器角色与服务帐户绑定，后者由 serviceaccount.yaml 创建或使用 values.yaml 配置。

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

模板资源种类名称预留长度说明备注
autoscalingrunnerset.yamlAutoscalingRunnerSetINSTALLATION_NAME0使用规模集的顶级资源名称长度不能超过 45 个字符。
no_permission_service_account.yamlServiceAccountINSTALLATION_NAME-gha-rs-no-permission21装载到运行器容器的服务帐户如果容器模式并非 "kubernetes" 且 template.spec.serviceAccountName 未指定，则会创建此项。
githubsecret.yaml机密INSTALLATION_NAME-gha-rs-github-secret20包含对 GitHub API 进行身份验证所需值的机密如果 githubConfigSecret 为对象，则会创建此项。 如果提供了字符串，则不会创建此机密。
manager_role.yaml角色INSTALLATION_NAME-gha-rs-manager15提供给管理员以便能够协调自动缩放运行器集命名空间中资源的角色此项始终创建。
manager_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-manager15将 manager_role 绑定到管理员服务帐户。此项始终创建。
kube_mode_role.yaml角色INSTALLATION_NAME-gha-rs-kube-mode17为挂钩提供必要权限的角色容器模式设置为 "kubernetes" 且 template.spec.serviceAccount 未提供时，将创建此项。
kube_mode_serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-kube-mode17绑定到运行器 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 中找到基础映像的定义。

创建自己的运行器映像

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

可以使用以下示例 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

执行工作流

安装和配置完成后，可以使用 ARC 执行工作流运行。 可在以 ARC 创建的自托管运行器为目标的同一存储库中创建工作流。 有关定位在自托管运行器上运行的工作流的详细信息，请参阅“在工作流中使用自托管运行程序”。

在工作流中使用 ARC 运行器

不能使用其他标签来定位 ARC 创建的运行器。 只能使用在安装期间指定的运行器规模集的安装名称，或者是在 values.yaml 文件中定义 runnerScaleSetName 字段的值。 这些标签用作“单一标签”，用作 runs-on 目标。 有关详细信息，请参阅“在工作流中使用 Actions Runner Controller 运行器”。

缩放运行器

可以根据需求静态或动态缩放运行器。 有关详细信息，请参阅“使用 Actions Runner Controller 部署运行器规模集”。

ARC 运行器映像中安装的软件

ARC 运行器映像与以下软件捆绑在一起：

有关详细信息，请参阅 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.