关于 Actions Runner Controller

Actions Runner Controller (ARC) 是一款 Kubernetes 运营商，可协调和扩展 GitHub Actions 的自托管 runner。有关详细信息，请参阅 Kubernetes 文档中的运营商模式。

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

下图说明了 ARC 的自动扩展 runner 扩展集模式的架构。

注意：要以更大的尺寸查看下图，请参阅 Actions Runner Controller 存储库中的自动扩展 Runner 扩展集模式文档。

Diagram showing ARC's autoscaling runner ScaleSet mode.

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

Actions Runner Controller 组件

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

ARC 部署的每个资源都赋予一个名称，该名称由以下部分组成

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

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

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

模板	资源类型	名称	保留的长度	描述	备注
`deployment.yaml`	部署	INSTALLATION_NAME-gha-rs-controller	18	运行 controller-manager 的资源	此资源创建的 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	controller manager 的 ClusterRole	如果 `flags.watchSingleNamespace` 的值为空，则会创建此项。
`manager_cluster_role_binding.yaml`	ClusterRoleBinding	INSTALLATION_NAME-gha-rs-controller	18	controller manager 的 ClusterRoleBinding	如果 `flags.watchSingleNamespace` 的值为空，则会创建此项。
`manager_single_namespace_controller_role.yaml`	Role	INSTALLATION_NAME-gha-rs-controller-single-namespace	35	controller manager 的 Role	如果设置了 `flags.watchSingleNamespace` 的值，则会创建此项。
`manager_single_namespace_controller_role_binding.yaml`	RoleBinding	INSTALLATION_NAME-gha-rs-controller-single-namespace	35	controller manager 的 RoleBinding	如果设置了 `flags.watchSingleNamespace` 的值，则会创建此项。
`manager_single_namespace_watch_role.yaml`	Role	INSTALLATION_NAME-gha-rs-controller-single-namespace-watch	41	已配置命名空间的 controller manager 的 Role	如果设置了 `flags.watchSingleNamespace` 的值，则会创建此项。
`manager_single_namespace_watch_role_binding.yaml`	RoleBinding	INSTALLATION_NAME-gha-rs-controller-single-namespace-watch	41	已配置命名空间的 controller manager 的 RoleBinding	如果设置了 `flags.watchSingleNamespace` 的值，则会创建此项。
`manager_listener_role.yaml`	Role	INSTALLATION_NAME-gha-rs-controller-listener	26	侦听器的 Role	此项始终会创建。
`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	挂载到 runner 容器的服务帐户	如果容器模式不是“kubernetes”且未指定 `template.spec.serviceAccountName`，则会创建此项。
`githubsecret.yaml`	Secret	INSTALLATION_NAME-gha-rs-github-secret	20	包含用于向 GitHub API 身份验证所需值的 Secret	如果 `githubConfigSecret` 是一个对象，则会创建此项。如果提供了一个字符串，则不会创建此项。
`manager_role.yaml`	Role	INSTALLATION_NAME-gha-rs-manager	15	向管理器提供的角色，使其能够协调自动伸缩运行器集名称空间中的资源	此项始终会创建。
`manager_role_binding.yaml`	RoleBinding	INSTALLATION_NAME-gha-rs-manager	15	将 manager_role 绑定到管理器服务帐户。	此项始终会创建。
`kube_mode_role.yaml`	Role	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。有关安装自定义资源的更多信息，请参阅“Actions Runner Controller 快速入门”。

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

关于运行器容器映像

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

此映像包含容器运行时和运行器二进制文件所需的最少软件包。要安装其他软件，您可以创建自己的运行器映像。您可以将 ARC 的运行器映像用作基础，或使用相应的设置操作。例如，actions/setup-java（用于 Java）或 actions/setup-node（用于 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 模式所需）

有关更多信息，请参阅操作存储库中的 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

本文内容