使用 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="http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'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="http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'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 文档。

选择运行器目标

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

注意：在使用 personal access token (classic) 身份验证时，只能将运行器规模集部署在企业级别。

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

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

githubConfigUrl: "http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>"

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

使用 GitHub App 进行身份验证

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

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

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

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

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

注意：**** 在安装 gha-runner-scale-set 图表的同一命名空间中创建机密。在此示例中，命名空间是 arc-runners，与快速入门文档对应。有关详细信息，请参阅“操作运行器控制器快速入门”。

kubectl create secret generic pre-defined-secret \
  --namespace=arc-runners \
  --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 机密。可通过以下命令使用代理凭据创建机密。

注意：**** 在安装 gha-runner-scale-set 图表的同一命名空间中创建机密。在此示例中，命名空间是 arc-runners，与快速入门文档对应。有关详细信息，请参阅“操作运行器控制器快速入门”。

Bash

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

  kubectl create secret generic proxy-auth \
    --namespace=arc-runners \
    --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 idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
# 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 idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
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 idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
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 idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
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。

使用专用容器注册表

警告：此 Actions Runner Controller 自定义选项可能超出 GitHub 支持可以提供帮助的作用域，并在错误配置时可能导致意外行为出现。****

有关 GitHub 支持可以提供帮助的更多信息，请参阅“关于对 Actions Runner Controller 的支持”。

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

配置控制器映像

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

image:
  repository: "custom-registry.io/gha-runner-scale-set-controller"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: "0.4.0"

imagePullSecrets:
  - name: <registry-secret-name>

侦听器容器继承为控制器定义的 imagePullPolicy。

配置运行器映像

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

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

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

更新运行器 Pod 的 Pod 规范

警告：此 Actions Runner Controller 自定义选项可能超出 GitHub 支持可以提供帮助的作用域，并在错误配置时可能导致意外行为出现。****

有关 GitHub 支持可以提供帮助的更多信息，请参阅“关于对 Actions Runner Controller 的支持”。

你可完全自定义运行器 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。

更新侦听器 Pod 的 Pod 规范

警告：此 Actions Runner Controller 自定义选项可能超出 GitHub 支持可以提供帮助的作用域，并在错误配置时可能导致意外行为出现。****

有关 GitHub 支持可以提供帮助的更多信息，请参阅“关于对 Actions Runner Controller 的支持”。

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

请勿更改侦听器容器的 listenerTemplate.spec.containers.name 值。否则，指定的配置将应用于新的挎斗容器。

listenerTemplate:
  spec:
    containers:
    # If you change the name of the container, the configuration will not be applied to the listener,
    # and it will be treated as a side-car container.
    - name: listener
      securityContext:
        runAsUser: 1000
      resources:
        limits:
          cpu: "1"
          memory: 1Gi
        requests:
          cpu: "1"
          memory: 1Gi

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

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

警告：此 Actions Runner Controller 自定义选项可能超出 GitHub 支持可以提供帮助的作用域，并在错误配置时可能导致意外行为出现。****

有关 GitHub 支持可以提供帮助的更多信息，请参阅“关于对 Actions Runner Controller 的支持”。

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

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

使用 Docker-in-Docker 模式

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

默认情况下，dind 容器使用 docker:dind 映像，此映像会将 Docker 守护程序作为根运行。只要了解已知限制并使用 --privileged 模式运行 Pod，就可以将此映像替换为 docker:dind-rootless。要了解如何自定义 Docker-in-Docker 配置，请参阅“自定义容器模式”。

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", "/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:///var/run/docker.sock
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
      - name: dind
        image: docker:dind
        args:
          - dockerd
          - --host=unix:///var/run/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: /var/run
          - name: dind-externals
            mountPath: /home/runner/externals
    volumes:
      - name: work
        emptyDir: {}
      - name: dind-sock
        emptyDir: {}
      - name: dind-externals
        emptyDir: {}

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

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

使用 Kubernetes 模式

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

先决条件

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

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

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

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

配置 Kubernetes 模式

要启用 Kubernetes 模式，请将 values.yaml 文件中的 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"

自定义容器模式

当在 gha-runner-scale-set Helm 图表的 values.yaml 文件中设置 containerMode 时，可以使用下面的两个值之一：

dind 或
kubernetes

根据为哪个值设置 containerMode，会自动将一个配置注入到 gha-runner-scale-set Helm 图表的文件 values.yaml 的 template 部分中。

请参阅 dind 配置。
请参阅 kubernetes 配置。

要自定义规范，请注释掉或移除 containerMode，并在 template 部分中附加所需的配置。

示例：运行 `dind-rootless`

在决定运行 dind-rootless 之前，请确保了解已知限制。

## githubConfigUrl is the GitHub url for where you want to configure runners
## ex: https://<HOSTNAME>/enterprises/my_enterprise or https://<HOSTNAME>/myorg
githubConfigUrl: "https://<HOSTNAME>/actions/actions-runner-controller"

## githubConfigSecret is the k8s secrets to use when auth with GitHub API.
## You can choose to use GitHub App or a PAT token
githubConfigSecret: my-super-safe-secret

## maxRunners is the max number of runners the autoscaling runner set will scale up to.
maxRunners: 5

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

runnerGroup: "my-custom-runner-group"

## name of the runner scale set to create.  Defaults to the helm release name
runnerScaleSetName: "my-awesome-scale-set"

## template is the PodSpec for each runner Pod
## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
template:
  spec:
    initContainers:
    - name: init-dind-externals
      image: ghcr.io/actions/actions-runner:latest
      command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
      volumeMounts:
        - name: dind-externals
          mountPath: /home/runner/tmpDir
    - name: init-dind-rootless
      image: docker:dind-rootless
      command:
        - sh
        - -c
        - |
          set -x
          cp -a /etc/. /dind-etc/
          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd
          echo 'runner:x:1001:' >> /dind-etc/group
          echo 'runner:100000:65536' >> /dind-etc/subgid
          echo 'runner:100000:65536' >>  /dind-etc/subuid
          chmod 755 /dind-etc;
          chmod u=rwx,g=rx+s,o=rx /dind-home
          chown 1001:1001 /dind-home
      securityContext:
        runAsUser: 0
      volumeMounts:
        - mountPath: /dind-etc
          name: dind-etc
        - mountPath: /dind-home
          name: dind-home
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: DOCKER_HOST
          value: unix:///var/run/docker.sock
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /var/run
    - name: dind
      image: docker:dind-rootless
      args:
        - dockerd
        - --host=unix:///var/run/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /var/run
        - name: dind-externals
          mountPath: /home/runner/externals
        - name: dind-etc
          mountPath: /etc
        - name: dind-home
          mountPath: /home/runner
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-etc
      emptyDir: {}
    - name: dind-home
      emptyDir: {}

了解运行器容器挂钩

当运行器检测到工作流在使用容器作业、服务容器或 Docker 操作运行时，它将调用运行器容器挂钩以创建新的 Pod。运行器依靠运行器容器挂钩来调用 Kubernetes API，并在运行器 Pod 所在的那个命名空间中创建新的 Pod。这个新创建的 Pod 将用来执行容器作业、服务容器或 Docker 操作。有关详细信息，请参阅 runner-container-hooks 存储库。

配置挂钩扩展

自 ARC 版本 0.4.0 起，运行器容器挂钩将支持挂钩扩展。可以使用这些扩展配置运行器容器挂钩创建的 Pod。例如，可以使用一个挂钩扩展在 Pod 上设置安全上下文。可以使用挂钩扩展指定一个 YAML 文件，以便用来更新运行器容器挂钩创建的 Pod 的 PodSpec。

可以使用两种方案配置挂钩扩展。

存储在自定义运行器映像中。可以将 PodSpec 存储在自定义运行器映像中的任意位置的 YAML 文件中。有关详细信息，请参阅“关于 Actions Runner Controller”。
存储在 ConfigMap 中。可以使用 PodSpec 创建一个配置映射，并在运行器容器中装载此配置映射。有关更多信息，请参阅 Kubernetes 文档中的 ConfigMaps。

注意： 使用这两种方案，必须在运行器容器规范中设置 ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE 环境变量，以使其指向在运行器容器中装载的 YAML 文件的路径。

示例：使用配置映射设置 securityContext

在运行器 Pod 所在的那个命名空间中创建一个配置映射。例如：

apiVersion: v1
kind: ConfigMap
metadata:
  name: hook-extension
  namespace: arc-runners
data:
  content: |
    metadata:
      annotations:
        example: "extension"
    spec:
      containers:
        - name: "$job" # Target the job container
          securityContext:
            runAsUser: 1000

除非保留 .metadata.labels 和 metadata.annotations 字段的密钥，否则将按原样追加这两个字段。无法重写 .metadata.name 和 metadata.namespace 字段。
大多数 PodSpec 字段都从指定的模板应用，并覆盖从 Helm 图表 values.yaml 文件传递的值。
如果指定其他卷，它们将追加到运行器指定的默认卷。
将基于分配给 spec.containers 的名称将它们合并。
- 如果此容器的名称是 $job：
  - 将忽略 spec.containers.name 字段和 spec.containers.image 字段。
  - 挂钩创建的默认容器规范中追加了 spec.containers.env、spec.containers.volumeMounts 和 spec.containers.ports 字段。
  - 其余的字段将按提供的原样应用。
- 如果容器的名称不是 $job，字段将按原样添加到 Pod 定义中。

启用指标

注意：**** 从版本 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 所有。

“所有者”	指标	类型	描述
控制器管理器	gha_controller_pending_ephemeral_runners	仪表 (gauge)	处于挂起状态的临时运行器数
控制器管理器	gha_controller_running_ephemeral_runners	仪表 (gauge)	处于正在运行状态的临时运行器数
控制器管理器	gha_controller_failed_ephemeral_runners	仪表 (gauge)	处于失败状态的临时运行器数
控制器管理器	gha_controller_running_listeners	仪表 (gauge)	处于正在运行状态的侦听器数量
listener	gha_assigned_jobs	仪表 (gauge)	分配给运行器规模集的作业数
listener	gha_running_jobs	仪表 (gauge)	正在运行或排队运行的作业数
listener	gha_registered_runners	仪表 (gauge)	运行器规模集注册的运行器数
listener	gha_busy_runners	仪表 (gauge)	当前运行作业的已注册运行器数
listener	gha_min_runners	仪表 (gauge)	为运行器规模集配置的最小运行器数
listener	gha_max_runners	仪表 (gauge)	为运行器规模集配置的最大运行器数
listener	gha_desired_runners	仪表 (gauge)	运行器规模集所需的运行器数（纵向扩展/缩减目标）
listener	gha_idle_runners	仪表 (gauge)	未运行作业的已注册运行器数
listener	gha_started_jobs_total	counter	自侦听器准备就绪后开始的作业总数 [1]
listener	gha_completed_jobs_total	counter	自侦听器准备就绪后完成的作业总数 [1]

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

将 ARC 与 Dependabot 和 code scanning 一起使用

可以使用 Actions Runner Controller 为 GitHub Enterprise Server 实例来创建专用运行器，Dependabot 可以使用这些运行器来帮助保护和维护企业存储库中使用的依赖项。有关详细信息，请参阅“管理企业中 Dependabot 更新的自托管运行器”。

也可以将 ARC 与 CodeQL 一起使用来识别代码中的漏洞和错误。有关详细信息，请参阅“关于使用 CodeQL 进行代码扫描”。如果已在使用 code scanning 并且想要将运行器规模集配置为使用默认设置，请设置 INSTALLATION_NAME=code-scanning。有关 code scanning 默认设置的详细信息，请参阅“配置代码扫描的默认设置”。

Actions Runner Controller 不使用多个标签将作业路由到特定的运行器规模集。相反，若要使用 CodeQL 为 Dependabot 更新或 code scanning 指定运行器规模集，请在 Helm 图表中使用描述性安装名称，例如 dependabot 或 code-scanning。然后，可以将工作流中的 runs-on 值作为单个标签设置为安装名称，并将指定的运行器规模集用于 Dependabot 更新或 code scanning 作业。

如果对 code scanning 使用默认设置，则分析将自动查找安装名称为 code-scanning 的运行器规模集。

Dependabot 操作用于通过 GitHub Actions 运行 Dependabot 更新。此操作需要 Docker 作为依赖项。出于此原因，仅当启用了 Docker-in-Docker (DinD) 模式时，才能将 Actions Runner Controller 与 Dependabot 配合使用。有关详细信息，请参阅“管理企业中 Dependabot 更新的自托管运行器”和“使用 Actions Runner Controller 部署运行器规模集”。

升级 ARC

由于不支持使用 Helm 升级或删除 CRD，因此无法使用 Helm 来升级 ARC。有关更多信息，请参阅 Helm 文档中的自定义资源定义。要将 ARC 升级到更高的版本，必须完成以下步骤。

卸载 gha-runner-scale-set 的所有安装。
等待资源清理。
卸载 CU3。
如果 CRD 从当前已安装的版本更改为升级的版本，则请移除与 actions.github.com API 组关联的所有 CRD。
再次重新安装 ARC。

有关更多信息，请参阅“部署运行器规模集”。

如果希望升级 ARC 但担心停机时间，可以在一个高可用性配置中部署 ARC，以确保运行器始终可用。有关更多信息，请参阅“高可用性和自动故障转移”。

注意:

从社区支持的 ARC 版本过渡到 GitHub 支持的版本是体系结构的一个重大改变。 GitHub 支持的版本要求重新设计 ARC 的很多组件。这不是一次次要软件升级。出于这些原因，我们建议首先在一个过渡环境中测试与生产环境匹配的新版本。这样可以在部署到生产环境之前确保设置的稳定性和可靠性。

部署 Canary 映像

在发布功能之前，可以使用控制器管理器容器映像的 Canary 版本对它们进行测试。 Canary 映像以标记格式 canary-SHORT_SHA 发布。有关更多信息，请参阅 Container registry 上的 gha-runner-scale-set-controller。

注意：

必须在本地文件系统上使用 Helm 图表。
无法使用已发布的 Helm 图表。

将 gha-runner-scale-set-controller values.yaml 文件中的 tag 更新为：canary-SHORT_SHA
将 gha-runner-scale-set 的 Chart.yaml 文件中的字段 appVersion 更新为：canary-SHORT_SHA
使用更新后的 Helm 图表和 values.yaml 文件重新安装 ARC。

高可用性和自动故障转移

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 部署运行器规模集

本文内容