关于运行器规模集
运行器规模集是一组可从 GitHub Actions 分配作业的同类运行器。 运行器规模集拥有的活动运行器数可以通过自动缩放运行器解决方案(如 Actions Runner Controller (ARC))进行控制。
可使用运行器组来管理运行器规模集。 与自承载运行器类似,可将运行器规模集添加到现有运行器组。 但是,运行器规模集一次只能属于一个运行器组,并且只能为其分配一个标签。 有关运行器组的详细信息,请参阅“使用组管理对自托管运行程序的访问”。
要将作业分配给运行器规模集,必须将工作流配置为引用运行器规模集的名称。 有关详细信息,请参阅“在工作流中使用 Actions Runner Controller 运行器”。
部署运行器规模集
要部署运行器规模集,必须启动并运行 ARC。 有关详细信息,请参阅“操作运行器控制器快速入门”。
可使用 ARC 的 Helm 图表或部署必要的清单来部署运行器规模集。 使用 ARC 的 Helm 图表是首选方法,尤其是在之前没有 ARC 使用经验的情况下。
Note
- 作为安全最佳做法,请在与包含运算符 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 提供多个高级配置选项。
配置运行器规模集名称
Note
运行器规模集名称在其所属的运行器组中是唯一的。 如果要部署多个同名的运行器规模集,它们必须属于不同的运行器组。
要配置运行器规模集名称,可在 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 文档。
选择运行器目标
运行器规模集可部署在存储库、组织或企业级别。
Note
在使用 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 进行身份验证”。
Note
考虑到在磁盘上的文件中以纯文本形式公开私钥所带来的安全风险,建议改为创建 Kubernetes 机密并传递该引用。
可以创建 Kubernetes 机密,也可以在 values.yaml
文件中指定值。
选项 1:创建 Kubernetes 机密(建议)
创建 GitHub App 后,创建 Kubernetes 机密,并在 values.yaml
文件副本中传递对该机密的引用。
Note
在安装 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 机密。 可通过以下命令使用代理凭据创建机密。
Note
在安装 gha-runner-scale-set
图表的同一命名空间中创建机密。 在此示例中,命名空间是 arc-runners
,与快速入门文档对应。 有关详细信息,请参阅“操作运行器控制器快速入门”。
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 设置的选项。
Note
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
个运行器。
Note
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 证书
Note
如果使用的自定义运行器映像不基于 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
。
使用专用容器注册表
Warning
此 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 规范
Warning
此 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 规范
Warning
此 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 模式
Warning
此 Actions Runner Controller 自定义选项可能超出 GitHub 支持 可以提供帮助的作用域,并在错误配置时可能导致意外行为出现。
有关 GitHub 支持 可以提供帮助的更多信息,请参阅“关于对 Actions Runner Controller 的支持”。
如果使用容器作业和服务或容器操作,则 containerMode
值必须设置为 dind
或 kubernetes
。
- 有关容器作业和服务的详细信息,请参阅“在容器中运行作业”。
- 有关容器操作的详细信息,请参阅“创建 Docker 容器操作”。
使用 Docker-in-Docker 模式
Note
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
。
Note
启用 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。
Note
使用这两种方案,必须在运行器容器规范中设置 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 定义中。
- 如果此容器的名称是
启用指标
Note
从版本 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"
Note
如果未提供或注释掉对象 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 发出的指标。
Note
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 | 计数器 | 自侦听器准备就绪后开始的作业总数 [1] |
listener | gha_completed_jobs_total | 计数器 | 自侦听器准备就绪后完成的作业总数 [1] |
listener | gha_job_startup_duration_seconds | histogram | 工作流作业在运行器规模集拥有的运行器上开始前等待的秒数 |
listener | gha_job_execution_duration_seconds | histogram | 运行器规模集执行工作流作业所用的秒数 |
[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,以确保运行器始终可用。 有关更多信息,请参阅“高可用性和自动故障转移”。
Note
从社区支持的 ARC 版本过渡到 GitHub 支持的版本是体系结构的一个重大改变。 GitHub 支持的版本要求重新设计 ARC 的很多组件。 这不是一次次要软件升级。 出于这些原因,我们建议首先在一个过渡环境中测试与生产环境匹配的新版本。 这样可以在部署到生产环境之前确保设置的稳定性和可靠性。
部署 Canary 映像
在发布功能之前,可以使用控制器管理器容器映像的 Canary 版本对它们进行测试。 Canary 映像以标记格式 canary-SHORT_SHA
发布。 有关更多信息,请参阅 Container registry 上的 gha-runner-scale-set-controller
。
Note
- 必须在本地文件系统上使用 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.