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

法律声明

关于运行器规模集

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

您可以使用运行器组来管理运行器规模集。与自托管运行器类似，您可以将运行器规模集添加到现有运行器组中。但是，运行器规模集一次只能属于一个运行器组，并且只能分配一个标签。有关运行器组的更多信息，请参阅“使用组管理对自托管运行器的访问权限”。

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

部署运行器规模集

要部署运行器规模集，您必须启动并运行 ARC。有关更多信息，请参阅“Actions Runner Controller 快速入门”。

您可以使用 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 提供了一些高级配置选项。

配置运行器规模集名称

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

要配置运行器规模集名称，您可以定义INSTALLATION_NAME或在您的values.yaml文件副本中设置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 应用进行身份验证

如果您没有使用企业级运行器，可以使用 GitHub 应用来对 GitHub API 进行身份验证。有关更多信息，请参阅“对 GitHub API 进行身份验证”。

注意：鉴于将您的私钥以纯文本形式暴露在磁盘上的文件中所带来的安全风险，我们建议创建 Kubernetes 密钥并传递引用。

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

选项 1：创建 Kubernetes 密钥（推荐）

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

注意：在安装 gha-runner-scale-set 图表的同一命名空间中创建密钥。在本例中，命名空间为 arc-runners，与快速入门文档匹配。有关更多信息，请参阅“Actions Runner Controller 快速入门”。

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 密钥。您可以使用以下命令创建包含代理凭据的密钥。

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 将扩展到分配给运行器规模集的作业数量，如果没有任何活动作业，则将缩减到 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 文件并设置 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 值。否则，您指定的配置将应用于新的 side-car 容器。

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 镜像，该镜像以 root 身份运行 Docker 守护程序。您可以将此镜像替换为 docker:dind-rootless，只要您了解已知限制并使用 --privileged 模式运行 Pod。要了解如何自定义 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", "-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:///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 使用 runner 容器钩子在同一命名空间中创建一个新的 Pod 来运行服务、容器作业或操作。

先决条件

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

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

创建可供 runner 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.

要允许没有作业容器的作业运行，请在您的 runner 容器上将ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER设置为false。这将指示 runner 禁用此检查。

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://github.com/myorg/myrepo or https://github.com/myorg
githubConfigUrl: "https://github.com/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.ac.cn/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", "-v", "/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: {}

当 Runner 检测到工作流运行使用容器作业、服务容器或 Docker 操作时，它将调用 runner-container-hooks 来创建一个新的 Pod。Runner 依赖 runner-container-hooks 来调用 Kubernetes API 并与 Runner Pod 在同一个命名空间中创建一个新的 Pod。这个新创建的 Pod 将用于运行容器作业、服务容器或 Docker 操作。有关更多信息，请参阅 runner-container-hooks 存储库。

配置钩子扩展

从 ARC 版本 0.4.0 开始，runner-container-hooks 支持钩子扩展。您可以使用它们来配置由 runner-container-hooks 创建的 Pod。例如，您可以使用钩子扩展为 Pod 设置安全上下文。钩子扩展允许您指定一个 YAML 文件，该文件用于更新由 runner-container-hooks 创建的 Pod 的 PodSpec。

有两种方法可以配置钩子扩展。

存储在您的 **自定义 Runner 镜像** 中。您可以在自定义 Runner 镜像中的任何位置存储 PodSpec 的 YAML 文件。有关更多信息，请参阅“关于 Actions Runner Controller”。
存储在 **ConfigMap** 中。您可以创建一个包含 PodSpec 的 ConfigMap，并将该 ConfigMap 挂载到 Runner 容器中。有关更多信息，请参阅 Kubernetes 文档中的 ConfigMaps。

**注意：** 对于这两种方法，您都必须在 Runner 容器规范中设置 ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE 环境变量，以指向挂载到 Runner 容器中的 YAML 文件的路径。

示例：使用 ConfigMap 设置 securityContext

在与 Runner Pod 相同的命名空间中创建一个 ConfigMap。例如

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 定义中。

启用指标

注意： ARC 的指标从版本 gha-runner-scale-set-0.5.0 开始可用。

ARC 可以发出有关您的运行器、您的作业以及执行工作流所花费时间的指标。指标可用于识别拥塞、监控 ARC 部署的运行状况、可视化使用趋势、优化资源消耗，以及许多其他用例。指标由控制器管理器和监听器 pod 以 Prometheus 格式发出。有关更多信息，请参阅 Prometheus 文档中的公开格式。

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

以下是一个示例配置。

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

注意： 如果未提供 metrics: 对象或已注释掉，则以下标志将应用于控制器管理器和监听器 pod，并带有空值：--metrics-addr、--listener-metrics-addr、--listener-metrics-endpoint。这将禁用 ARC 的指标。

配置完这些属性后，您的控制器管理器和监听器 pod 将通过绑定到您在 values.yaml 文件中指定的端口的监听器端点发出指标。在上面的示例中，端点为 /metrics，端口为 :8080。您可以使用此端点从您的控制器管理器和监听器 pod 中抓取指标。

要关闭指标，请通过删除或注释掉 metrics: 对象及其属性来更新您的 values.yaml 文件。

ARC 的可用指标

下表显示了控制器管理器和监听器 pod 发出的指标。

注意： 控制器管理器发出的指标与控制器运行时相关，不属于 GitHub。

所有者	指标	类型	描述
控制器管理器	gha_controller_pending_ephemeral_runners	指标	处于挂起状态的临时运行器的数量
控制器管理器	gha_controller_running_ephemeral_runners	指标	处于运行状态的临时运行器的数量
控制器管理器	gha_controller_failed_ephemeral_runners	指标	处于失败状态的临时运行器的数量
控制器管理器	gha_controller_running_listeners	指标	处于运行状态的监听器的数量
监听器	gha_assigned_jobs	指标	分配给运行器规模集的作业数量
监听器	gha_running_jobs	指标	正在运行或排队等待运行的作业数量
监听器	gha_registered_runners	指标	由运行器规模集注册的运行器数量
监听器	gha_busy_runners	指标	当前正在运行作业的已注册运行器数量
监听器	gha_min_runners	指标	为运行器规模集配置的最小运行器数量
监听器	gha_max_runners	指标	为运行器规模集配置的最大运行器数量
监听器	gha_desired_runners	指标	运行器规模集所需的运行器数量（向上/向下扩展目标）
监听器	gha_idle_runners	指标	未运行作业的已注册运行器数量
监听器	gha_started_jobs_total	计数器	监听器变为就绪后启动的作业总数 [1]
监听器	gha_completed_jobs_total	计数器	监听器变为就绪后完成的作业总数 [1]
监听器	gha_job_startup_duration_seconds	直方图	等待工作流作业在运行器规模集拥有的运行器上启动所花费的秒数
监听器	gha_job_execution_duration_seconds	直方图	运行器规模集执行工作流作业所花费的秒数

[1]: 具有计数器类型的监听器指标在监听器 pod 重启时重置。

升级 ARC

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

卸载所有 gha-runner-scale-set 安装。
等待资源清理。
卸载 ARC。
如果从您当前安装的版本到升级后的版本，CRD 发生了变化，请删除与 actions.github.com API 组关联的所有 CRD。
重新安装 ARC。

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

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

注意

从社区支持的 ARC 版本过渡到 GitHub 支持的版本是一个重大的架构变更。GitHub 支持的版本涉及重新设计 ARC 的许多组件。这不是一个小的软件升级。出于这些原因，我们建议您首先在与生产环境匹配的暂存环境中测试新版本。这将确保在生产环境中部署之前设置的稳定性和可靠性。

部署金丝雀镜像

您可以通过使用控制器管理器容器镜像的金丝雀版本来测试功能，这些功能尚未发布。金丝雀镜像以标签格式 canary-SHORT_SHA 发布。有关更多信息，请参阅容器注册表上的 gha-runner-scale-set-controller。

注意

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

将 gha-runner-scale-set-controller values.yaml 文件中的 tag 更新为：canary-SHORT_SHA
将 Chart.yaml 文件中 gha-runner-scale-set 的 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 进行身份验证，并为每个运行器规模集定义细粒度的权限。

法律声明

部分内容改编自 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.

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

本文内容

关于运行器规模集

部署运行器规模集

使用高级配置选项

配置运行器规模集名称

选择运行器目标

使用 GitHub 应用进行身份验证

选项 1：创建 Kubernetes 密钥（推荐）

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

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

配置出站代理

设置运行器的最大数量和最小数量

示例：无限数量的运行器

示例：运行器的最小数量

示例：设置运行器的最大和最小数量

示例：作业队列清空

自定义 TLS 证书

使用私有容器注册表

配置控制器镜像

配置运行器镜像

更新运行器 Pod 的 Pod 规范

更新监听器 Pod 的 Pod 规范

在容器中使用 Docker-in-Docker 或 Kubernetes 模式

使用 Docker-in-Docker 模式

使用 Kubernetes 模式

先决条件

配置 Kubernetes 模式

自定义容器模式

示例：运行`dind-rootless`

理解 runner-container-hooks

配置钩子扩展

示例：使用 ConfigMap 设置 securityContext

启用指标

ARC 的可用指标

升级 ARC

部署金丝雀镜像

高可用性和自动故障转移

跨组织使用 ARC

法律声明