关于 Actions Runner 控制器

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

本文内容

法律声明

关于 Actions Runner 控制器

Actions Runner 控制器 (ARC) 是一个 Kubernetes 运算符，用于编排和扩展 GitHub Actions 的自托管 Runner。更多信息，请参阅 Kubernetes 文档中的 运算符模式。

使用 ARC，您可以创建 Runner 规模集，这些规模集会根据您的存储库、组织或企业中运行的工作流数量自动扩展。由于受控 Runner 可以是短暂的且基于容器的，因此新的 Runner 实例可以快速且干净地进行扩展或缩减。有关自动缩放的更多信息，请参阅“使用自托管 Runner 进行自动缩放”。

下图说明了 ARC 自动缩放 Runner 规模集模式的架构。

注意

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

Diagram showing ARC's autoscaling runner ScaleSet mode.

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

Actions Runner Controller 组件

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

ARC 部署的每个资源都具有一个由以下部分组成的名称：

  • 安装名称，这是您安装 Helm Chart 时指定的安装名称。
  • 资源标识后缀，这是一个标识资源类型的字符串。此值不可配置。

注意

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

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

模板资源类型名称保留长度描述备注
deployment.yamlDeploymentINSTALLATION_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.yamlRoleINSTALLATION_NAME-gha-rs-controller-single-namespace35控制器管理器的 Role如果flags.watchSingleNamespace的值已设置，则创建此资源。
manager_single_namespace_controller_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace35控制器管理器的 RoleBinding如果flags.watchSingleNamespace的值已设置，则创建此资源。
manager_single_namespace_watch_role.yamlRoleINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41控制器管理器针对已配置命名空间的 Role如果flags.watchSingleNamespace的值已设置，则创建此资源。
manager_single_namespace_watch_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41控制器管理器针对已配置命名空间的 RoleBinding如果flags.watchSingleNamespace的值已设置，则创建此资源。
manager_listener_role.yamlRoleINSTALLATION_NAME-gha-rs-controller-listener26监听器的 Role始终创建此资源。
manager_listener_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-listener26监听器的 RoleBinding始终创建此资源，并将监听器角色与服务帐户绑定，该服务帐户由serviceaccount.yaml创建或通过values.yaml配置。

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

模板资源类型名称保留长度描述备注
autoscalingrunnerset.yamlAutoscalingRunnerSetINSTALLATION_NAME0与 Scale Set 协同工作的顶级资源名称长度限制为 45 个字符。
no_permission_service_account.yamlServiceAccountINSTALLATION_NAME-gha-rs-no-permission21挂载到 Runner 容器的服务帐户如果容器模式不是“kubernetes”并且未指定template.spec.serviceAccountName，则创建此资源。
githubsecret.yamlSecretINSTALLATION_NAME-gha-rs-github-secret20包含用于向 GitHub API 进行身份验证所需的值的 Secret如果githubConfigSecret是对象，则创建此 Secret。如果提供字符串，则不会创建此 Secret。
manager_role.yamlRoleINSTALLATION_NAME-gha-rs-manager15提供给管理器的角色，以便能够在自动缩放 Runner 集的命名空间中的资源上进行协调始终创建此资源。
manager_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-manager15将manager_role绑定到管理器服务帐户。始终创建此资源。
kube_mode_role.yamlRoleINSTALLATION_NAME-gha-rs-kube-mode17提供挂钩所需权限的角色当容器模式设置为“kubernetes”并且未提供template.spec.serviceAccount时，创建此资源。
kube_mode_serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-kube-mode17绑定到 Runner Pod 的服务帐户。当容器模式设置为“kubernetes”并且未提供template.spec.serviceAccount时，创建此资源。

关于自定义资源

ARC 包含多个自定义资源定义 (CRD)。有关自定义资源的更多信息，请参阅 Kubernetes 文档中的自定义资源。您可以在以下 API 模式定义中找到用于 ARC 的自定义资源定义列表。

由于自定义资源是 Kubernetes API 的扩展，因此它们在默认的 Kubernetes 安装中不可用。您需要安装这些自定义资源才能使用 ARC。有关安装自定义资源的更多信息，请参阅“Actions Runner Controller 快速入门”。

安装自定义资源后，您可以将 ARC 部署到您的 Kubernetes 集群。有关部署 ARC 的信息，请参阅“使用 Actions Runner Controller 部署 Runner Scale Set”。

关于 Runner 容器镜像

GitHub 维护着一个精简的 Runner 容器镜像。每次发布 Runner 二进制文件时，都会发布一个新镜像。最新的镜像将具有 Runner 二进制文件版本和latest作为标签。

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

您可以在此 Dockerfile中找到 ARC 的 Runner 镜像定义，以及在此 Dockerfile中找到基础镜像的定义。

创建您自己的 Runner 镜像

您可以创建满足您需求的自己的 Runner 镜像。您的 Runner 镜像必须满足以下条件。

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

您可以使用以下示例 Dockerfile 开始创建您自己的 Runner 镜像。

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 创建的自托管 Runner。有关将工作流目标设置为在自托管 Runner 上运行的更多信息，请参阅“在工作流中使用自托管 Runner”。

在工作流中使用 ARC Runner

您不能使用其他标签来定位由 ARC 创建的 Runner。您只能使用在安装过程中指定的 Runner Scale Set 的安装名称，或者通过定义values.yaml文件中的runnerScaleSetName字段的值来使用。这些用作“单个标签”，用作您的runs-on目标。有关更多信息，请参阅“在工作流中使用 Actions Runner Controller Runner”。

缩放 Runner

您可以根据需要静态或动态地缩放 Runner。有关更多信息，请参阅“使用 Actions Runner Controller 部署 Runner Scale Set”。

在 ARC Runner 镜像中安装的软件

ARC Runner 镜像捆绑了以下软件

有关更多信息，请参阅 Actions 存储库中的ARC 的 Runner 镜像 Dockerfile。

资源和版本

ARC 发布为两个 Helm Chart 和一个容器镜像。Helm Chart 仅作为开放容器倡议 (OCI) 包发布。ARC 不通过 GitHub Pages 提供 tarball 或 Helm 存储库。

您可以在 GitHub Packages 上找到 ARC 的 Helm Chart 和容器镜像的最新版本

支持的 Runner 镜像作为单独的容器镜像发布，您可以在 GitHub Packages 上的actions-runner找到它。

部分内容已根据https://github.com/actions/actions-runner-controller/在 Apache-2.0 许可下改编

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.