使用 Actions Runner Controller 部署运行器规模集

法律通告

关于运行器规模集

运行器规模集是一组可从 GitHub Actions 分配作业的同类运行器。运行器规模集拥有的活动运行器数可以通过自动缩放运行器解决方案（如 Actions Runner Controller (ARC)）进行控制。

可使用运行器组来管理运行器规模集。与自承载运行器类似，可将运行器规模集添加到现有运行器组。但运行器规模集一次只能属于一个运行器组，并且不能为其分配标签。有关运行器组的详细信息，请参阅“使用组管理对自托管运行程序的访问”。

要将作业分配给运行器规模集，必须将工作流配置为引用运行器规模集的名称。有关详细信息，请参阅“在工作流中使用 Actions Runner Controller 运行器”。

部署运行器规模集

要部署运行器规模集，必须启动并运行 ARC。有关详细信息，请参阅“操作运行器控制器快速入门”。

可使用 ARC 的 Helm 图表或部署必要的清单来部署运行器规模集。使用 ARC 的 Helm 图表是首选方法，尤其是在之前没有 ARC 使用经验的情况下。

注意：

作为安全最佳做法，请在与包含运算符 Pod 的命名空间不同的命名空间中创建运行器 Pod。
从安全性角度而言，最佳做法是创建 Kubernetes 机密并传递机密引用。通过 CLI 以纯文本传递机密可能会产生安全风险。
建议单独运行生产工作负载。 GitHub Actions 工作流旨在运行任意代码，并且将共享 Kubernetes 群集用于生产工作负载可能会带来安全风险。

要配置运行器规模集，请使用 ARC 配置中的值在终端中运行以下命令。

运行命令时，请记住以下事项。

仔细更新 INSTALLATION_NAME 值。在工作流中，将使用安装名称作为 runs-on 的值。
将 NAMESPACE 值更新为要在其中创建运行器 Pod 的位置。
将 GITHUB_CONFIG_URL 值设置为存储库、组织或企业的 URL。这是运行器将属于的实体。

此示例命令安装最新版 Helm 图表。要安装特定版本，可使用 --version 自变量来传递要安装的图表版本。可在 actions-runner-controller 存储库中找到发行版列表。

Bash

INSTALLATION_NAME="arc-runner-set"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/<your_enterprise/org/repo>"
GITHUB_PAT="<PAT>"
helm install "${INSTALLATION_NAME}" \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

INSTALLATION_NAME="arc-runner-set"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/<your_enterprise/org/repo>"
GITHUB_PAT="<PAT>"
helm install "${INSTALLATION_NAME}" \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

要检查安装，请在终端中运行以下命令。

Bash

helm list -A

helm list -A

此时会看到类似下面的输出。

NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                                       APP VERSION
arc             arc-systems     1               2023-04-12 11:45:59.152090536 +0000 UTC deployed        gha-runner-scale-set-controller-0.4.0       0.4.0
arc-runner-set  arc-systems     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0

要检查管理器 Pod，请在终端中运行以下命令。

Bash

kubectl get pods -n arc-systems

kubectl get pods -n arc-systems

如果安装成功，Pod 将显示 Running 状态。

NAME                                                   READY   STATUS    RESTARTS   AGE
arc-gha-runner-scale-set-controller-594cdc976f-m7cjs   1/1     Running   0          64s
arc-runner-set-754b578d-listener                       1/1     Running   0          12s

如果安装未成功，请参阅“排查 Actions Runner Controller 的错误”以获取故障排除信息。

使用高级配置选项

ARC 提供多个高级配置选项。

配置运行器规模集名称

注意：运行器规模集名称在其所属的运行器组中是唯一的。如果要部署多个同名的运行器规模集，它们必须属于不同的运行器组。

要配置运行器规模集名称，可在 values.yaml 文件副本中定义 INSTALLATION_NAME 或设置 runnerScaleSetName 的值。

## The name of the runner scale set to create, which defaults to the Helm release name
runnerScaleSetName: "my-runners"

请确保在 helm install 命令中传递 values.yaml 文件。有关更多详细信息，请参阅 Helm Install 文档。

选择运行器目标

运行器规模集可部署在存储库、组织或企业级别。

要将运行器规模集部署到特定级别，请在 values.yaml 的副本中将 githubConfigUrl 的值设置为存储库、组织或企业的 URL。

以下示例演示如何配置 ARC 以将运行器添加到 octo-org/octo-repo。

githubConfigUrl: "https://github.com/octo-ent/octo-org/octo-repo"

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

使用 GitHub App 进行身份验证

如果未使用企业级运行器，则可使用 GitHub Apps 通过 GitHub API 进行身份验证。有关详细信息，请参阅“向 GitHub API 进行身份验证”。

注意：考虑到在磁盘上的文件中以纯文本形式公开私钥所带来的安全风险，建议改为创建 Kubernetes 机密并传递该引用。

可以创建 Kubernetes 机密，也可以在 values.yaml 文件中指定值。

选项 1：创建 Kubernetes 机密（建议）

创建 GitHub App 后，创建 Kubernetes 机密，并在 values.yaml 文件副本中传递对该机密的引用。

kubectl create secret generic pre-defined-secret \
  --namespace=my_namespace \
  --from-literal=github_app_id=123456 \
  --from-literal=github_app_installation_id=654321 \
  --from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'

在 values.yaml 副本中，以引用形式传递机密名称。

githubConfigSecret: pre-defined-secret

选项 2：在 `values.yaml` 文件中指定值

或者，可在 values.yaml 文件副本中指定 app_id、installation_id 和 private_key 的值。

## githubConfigSecret is the Kubernetes secret to use when authenticating with GitHub API.
## You can choose to use a GitHub App or a personal access token (classic)
githubConfigSecret:
  ## GitHub Apps Configuration
  ## IDs must be strings, use quotes
  github_app_id: "123456"
  github_app_installation_id: "654321"
  github_app_private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    HkVN9...
    ...
    -----END RSA PRIVATE KEY-----

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

使用运行器组管理访问权限

可使用运行器组来控制哪些组织或存储库有权访问运行器规模集。有关运行器组的详细信息，请参阅“使用组管理对自托管运行程序的访问”。

要将运行器规模集添加到运行器组，前提是已创建运行器组。然后在 values.yaml 文件副本中设置 runnerGroup 属性。以下示例将运行器规模集添加到 Octo-Group 运行器组。

runnerGroup: "Octo-Group"

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

配置出站代理

要强制控制器和运行器的 HTTP 流量通过出站代理，请在 Helm 图表中设置以下属性。

proxy:
  http:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  https:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  noProxy:
    - example.com
    - example.org

ARC 支持使用匿名代理或经过身份验证的代理。如果使用经过身份验证的代理，则需要设置 credentialSecretRef 值以引用 Kubernetes 机密。可通过以下命令使用代理凭据创建机密。

Bash

  kubectl create secret generic proxy-auth \
    --namespace=my_namespace \
    --from-literal=username=proxyUsername \
    --from-literal=password=proxyPassword \

  kubectl create secret generic proxy-auth \
    --namespace=my_namespace \
    --from-literal=username=proxyUsername \
    --from-literal=password=proxyPassword \

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

设置运行器数上限和下限

maxRunners 和 minRunners 属性提供了一系列用于自定义 ARC 设置的选项。

注意：ARC 不支持计划的最大和最小配置。可使用 cronjob 或任何其他计划解决方案按计划更新配置。

示例：无限数量的运行器

如果注释禁止 maxRunners 和 minRunners 属性，ARC 将纵向扩展到分配给运行器规模集的作业数，如果没有任何活动作业，ARC 将纵向缩减到 0。

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of runners the auto scaling runner set will scale down to.
# minRunners: 0

示例：运行器数下限

可将 minRunners 属性设置为任意数字，ARC 将确保至少有此数量的运行器处于活动状态，并且可以随时执行分配给运行器规模集的作业。

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of runners the auto scaling runner set will scale down to.
minRunners: 20

示例：设置运行器数上限和下限

在此配置中，Actions Runner Controller 将纵向扩展到至多 30 个运行器，并在作业完成后纵向缩减到 20 个运行器。

注意：minRunners 的值永远不能超过 maxRunners 的值，除非注释禁止 maxRunners。

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 30

## minRunners is the min number of runners the auto scaling runner set will scale down to.
minRunners: 20

示例：作业队列清空

在某些情况下，可能需要清空作业队列来排查问题或对群集执行维护。如果将这两个属性都设置为 0，则提供和分配新作业时，Actions Runner Controller 将不会新建运行器 Pod。

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 0

## minRunners is the min number of runners the auto scaling runner set will scale down to.
minRunners: 0

自定义 TLS 证书

注意：如果使用的自定义运行器映像不基于 Debian 发行版，则以下说明不适用。

某些环境需要由自定义证书颁发机构 (CA) 签名的 TLS 证书。由于自定义证书颁发机构证书未与控制器或运行器容器捆绑在一起，因此必须将这些证书注入各自的信任存储中。

githubServerTLS:
  certificateFrom:
    configMapKeyRef:
      name: config-map-name
      key: ca.crt
  runnerMountPath: /usr/local/share/ca-certificates/

执行此操作时，请确保使用隐私增强邮件 (PEM) 格式，并且证书的扩展名为 .crt。其他任何格式都会被忽略。

控制器执行以下操作。

创建包含 github-server-tls-cert 中指定的证书的 certificateFrom 卷。
将该卷装载到路径 runnerMountPath/<certificate name> 中。
将 NODE_EXTRA_CA_CERTS 环境变量设置为同一路径。
将 RUNNER_UPDATE_CA_CERTS 环境变量设置为 1（自版本 2.303.0 起，这将指示运行器在主机上重新加载证书）。

ARC 观察运行器 Pod 模板中设置的值，并且不会覆盖它们。

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

对容器使用 Docker-in-Docker 或 Kubernetes 模式

如果使用容器作业和服务或容器操作，则 containerMode 值必须设置为 dind 或 kubernetes。

有关容器作业和服务的详细信息，请参阅“在容器中运行作业”。
有关容器操作的详细信息，请参阅“创建 Docker 容器操作”。

使用 Docker-in-Docker 模式

注意：Docker-in-Docker 容器需要特权模式。有关详细信息，请参阅 Kubernetes 文档中的为 Pod 或容器配置安全性上下文。

Docker-in-Docker 模式是一种支持在 Docker 容器中运行 Docker 的配置。在此配置中，对于创建的每个运行器 Pod，ARC 会创建以下容器。

init 容器
runner 容器
dind 容器

要启用 Docker-in-Docker 模式，请将 containerMode.type 设置为 dind，如下所示。

containerMode:
  type: "dind"

template.spec 将更新为以下默认配置。

template:
  spec:
    initContainers:
    - name: init-dind-externals
      image: ghcr.io/actions/actions-runner:latest
      command: ["cp", "-r", "-v", "/home/runner/externals/.", "/home/runner/tmpDir/"]
      volumeMounts:
        - name: dind-externals
          mountPath: /home/runner/tmpDir
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: DOCKER_HOST
          value: unix:///run/docker/docker.sock
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/docker
          readOnly: true
    - name: dind
      image: docker:dind
      args:
        - dockerd
        - --host=unix:///run/docker/docker.sock
        - --group=$(DOCKER_GROUP_GID)
      env:
        - name: DOCKER_GROUP_GID
          value: "123"
      securityContext:
        privileged: true
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/docker
        - name: dind-externals
          mountPath: /home/runner/externals
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}

不能重写这些自动注入的值。如果要自定义此设置，则必须取消设置 containerMode.type，然后复制此配置并将其直接应用于 values.yaml 文件的副本。

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

使用 Kubernetes 模式

在 Kubernetes 模式下，ARC 使用运行器容器挂钩在同一命名空间中新建 Pod 来运行服务、容器作业或操作。

先决条件

Kubernetes 模式依赖于永久性卷在运行器 Pod 和容器作业 Pod 之间共享作业详细信息。有关详细信息，请参阅永久性卷 Kubernetes 文档。

要使用 Kubernetes 模式，必须执行以下操作。

创建可供运行器 Pod 声明的永久性卷。
使用解决方案按需自动预配永久性卷。

对于测试，可使用 OpenEBS 等解决方案。

配置 Kubernetes 模式

要启用 Kubernetes 模式，请将 containerMode.type 设置为 kubernetes。

containerMode:
  type: "kubernetes"
  kubernetesModeWorkVolumeClaim:
    accessModes: ["ReadWriteOnce"]
    storageClassName: "dynamic-blob-storage"
    resources:
      requests:
        storage: 1Gi

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

启用 Kubernetes 模式后，未配置容器作业的工作流将失败，并显示类似于以下内容的错误：

Jobs without a job container are forbidden on this runner, please add a 'container:' to your job or contact your self-hosted runner administrator.

为了使没有作业容器的作业能够运行，你需要指示运行器禁用此检查。可在运行器容器上将 ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER 设置为 false 来执行此操作：

template:
  spec:
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER
          value: "false"

使用专用容器注册表

要使用专用容器注册表，可将控制器映像和运行器映像复制到专用容器注册表。然后配置指向这些映像的链接，并设置 imagePullPolicy 和 imagePullSecrets 值。

配置运行器映像

可更新 values.yaml 文件的副本并设置 template.spec 属性，如下所示。

template:
  spec:
    containers:
    - name: runner
      image: "custom-registry.io/actions-runner:latest"
      imagePullPolicy: Always
      command: ["/home/runner/run.sh"]

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

更新运行器 Pod 的 Pod 规范

你可完全自定义运行器 Pod 的 PodSpec，控制器将应用你指定的配置。下面是一个 Pod 规范示例。

template:
  spec:
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      resources:
        limits:
          cpu: 500m
          memory: 512Mi
      securityContext:
        readOnlyRootFilesystem: true
        allowPrivilegeEscalation: false
        capabilities:
          add:
          - NET_ADMIN

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

启用指标

注意：**** 从版本 gha-runner-scale-set-0.5.0 开始提供 ARC 的指标。

ARC 可以发出有关运行器、作业和执行工作流所用时间的指标。指标可用于识别拥塞、监视 ARC 部署的运行状况、可视化使用趋势、优化资源消耗以及许多其他用例。指标由 controller-manager 和侦听器 Pod 以 Prometheus 格式发出。有关详细信息，请参阅 Prometheus 文档中的表达式格式。

要启用 ARC 指标，请在 gha-runner-scale-set-controller 图表的 values.yaml 文件中配置 metrics 属性。

下面是一个配置示例：

metrics:
  controllerManagerAddr: ":8080"
  listenerAddr: ":8080"
  listenerEndpoint: "/metrics"

注意：**** 如果未提供或注释禁止对象 metrics:，则以下标志将应用于 controller-manager 和侦听器 Pod，其中包含空值：--metrics-addr、--listener-metrics-addr、--listener-metrics-endpoint。这将禁用 ARC 指标。

配置这些属性后，controller-manager 和侦听器 Pod 会通过绑定到 values.yaml 文件中指定端口的 listenerEndpoint 发出指标。在上面的示例中，端点为 /metrics，端口为 :8080。可以使用此端点从 controller-manager 和侦听器 Pod 中抓取指标。

要关闭指标，请移除或注释禁止 metrics: 对象及其属性来更新 values.yaml 文件。

可用 ARC 指标

下表显示了 controller-manager 和侦听器 Pod 发出的指标。

注意：**** controller-manager 发出的指标与控制器运行时相关，并且不归 GitHub 所有。

所有者	指标	类型	描述
控制器管理器	pending_ephemeral_runners	仪表 (gauge)	处于挂起状态的临时运行器数
控制器管理器	running_ephemeral_runners	仪表 (gauge)	处于正在运行状态的临时运行器数
控制器管理器	failed_ephemeral_runners	仪表 (gauge)	处于失败状态的临时运行器数
listener	assigned_jobs	仪表 (gauge)	分配给运行器规模集的作业数
listener	running_jobs	仪表 (gauge)	正在运行或排队运行的作业数
listener	registered_runners	仪表 (gauge)	运行器规模集注册的运行器数
listener	busy_runners	仪表 (gauge)	当前运行作业的已注册运行器数
listener	min_runners	仪表 (gauge)	为运行器规模集配置的最小运行器数
listener	max_runners	仪表 (gauge)	为运行器规模集配置的最大运行器数
listener	desired_runners	仪表 (gauge)	运行器规模集所需的运行器数（纵向扩展/缩减目标）
listener	idle_runners	仪表 (gauge)	未运行作业的已注册运行器数
listener	started_jobs_total	counter	自侦听器准备就绪后开始的作业总数 [1]
listener	completed_jobs_total	计数器	自侦听器准备就绪后完成的作业总数 [1]
listener	job_queue_duration_seconds	histogram	工作流作业在排队后等待分配给运行器规模集的秒数
listener	job_startup_duration_seconds	histogram	工作流作业在运行器规模集拥有的运行器上开始前等待的秒数
listener	job_execution_duration_seconds	histogram	运行器规模集执行工作流作业所用的秒数

[1]: Listener metrics that have the counter type are reset when the listener pod restarts.

ARC 可以在高可用性（主动-主动）配置中部署。如果在单独的区域中部署两个不同的 Kubernetes 群集，则可以在两个群集中部署 ARC，并将运行器规模集配置为使用相同的 runnerScaleSetName。为此，必须将每个运行器规模集分配给不同的运行器组。例如，可以有两个名为 arc-runner-set 的运行器规模集，前提是一个运行器规模集属于 runner-group-A，另一个运行器规模集属于 runner-group-B。有关将运行器规模集分配给运行器组的信息，请参阅“使用组管理对自托管运行程序的访问”。

如果两个运行器规模集都处于联机状态，则分配给它们的作业将任意分配（分配争用）。无法配置作业分配算法。如果其中一个群集出现故障，另一个群集中的运行器规模集会继续正常获取作业，无需进行任何干预或配置更改。

跨组织使用 ARC

通过单独安装 Actions Runner Controller，可以配置一个或多个运行器规模集。这些运行器规模集可注册到存储库、组织或企业。还可使用运行器组来控制这些运行器规模集的权限边界。

最佳做法是为每个组织创建一个唯一的命名空间。还可为每个运行器组或每个运行器规模集创建一个命名空间。可根据需要在每个命名空间中安装任意数量的运行器规模集。这将提供最高级别的隔离，并提高安全性。可使用 GitHub Apps 进行身份验证，并为每个运行器规模集定义精细权限。

法律通告

部分内容改编自 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 部署运行器规模集

本文内容

关于运行器规模集

部署运行器规模集

使用高级配置选项

配置运行器规模集名称

选择运行器目标

使用 GitHub App 进行身份验证

选项 1：创建 Kubernetes 机密（建议）

选项 2：在 `values.yaml` 文件中指定值

使用运行器组管理访问权限

配置出站代理

设置运行器数上限和下限

示例：无限数量的运行器

示例：运行器数下限

示例：设置运行器数上限和下限

示例：作业队列清空

自定义 TLS 证书

对容器使用 Docker-in-Docker 或 Kubernetes 模式

使用 Docker-in-Docker 模式

使用 Kubernetes 模式

先决条件

配置 Kubernetes 模式

使用专用容器注册表

配置控制器映像

配置运行器映像

更新运行器 Pod 的 Pod 规范

启用指标

可用 ARC 指标

高可用性和自动故障转移

跨组织使用 ARC

法律通告