Skip to main content

此版本的 GitHub Enterprise Server 已于以下日期停止服务 2024-07-09. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

操作运行器控制器快速入门

5 分钟后试用 Actions Runner Controller。

法律通告

简介

Actions Runner Controller (ARC) 是 Kubernetes 运算符,用于协调和缩放 GitHub Actions 的自托管运行器。 有关详细信息,请参阅 Kubernetes 文档中的运算符模式

使用 ARC,可以创建运行器规模集,以便根据存储库、组织或企业中运行的工作流数量自动缩放。 受控的运行器可以是临时且基于容器的运行器,因此新的运行器实例可以快速顺利地纵向扩展或缩减。 有关自动缩放的详细信息,请参阅“使用自托管运行器自动缩放”。

可以使用 Helm 在 Kubernetes 上设置 ARC,然后创建并运行使用运行器规模集的工作流。 有关运行器规模集的详细信息,请参阅“使用 Actions Runner Controller 部署运行器规模集”。

先决条件

若要使用 ARC,请确保具有以下项。

  • 一个 Kubernetes 群集

    • 对于托管云环境,可以使用 AKS。 有关详细信息,请参阅 Azure 文档中的 Azure Kubernetes 服务

    • 对于本地设置,可以使用 minikube 或 kind。 有关详细信息,请参阅 minikube 文档中的 minikube start 和 kind 文档中的 kind

      注意:当前不支持 OpenShift 群集。

  • Helm 3

    • 有关详细信息,请参阅 Helm 文档中的安装 Helm
  • 虽然不需要部署 ARC,但我们建议在将 ARC 部署到生产工作流中之前,确保已实现从控制器、侦听器和临时运行器中收集和保留日志的方法。

安装操作运行器控制器

  1. 若要在群集中安装运算符和自定义资源定义 (CRD),请执行以下操作。

    1. 在 Helm 图表中,将 NAMESPACE 值更新为希望创建运算符 Pod 的位置。 此命名空间必须允许访问 Kubernetes API 服务器。
    2. 安装 Helm 图表。

    以下示例将安装最新版的图表。 若要安装特定版本,可以将 --version 参数与要安装的图表版本一起传递。 可以在 GitHub 容器注册表中找到发布列表。

    Bash
    NAMESPACE="arc-systems"
    helm install arc \
        --namespace "${NAMESPACE}" \
        --create-namespace \
        oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
    

    有关其他 Helm 配置选项,请参阅 ARC 文档中的 values.yaml

  2. 若要使 ARC 能够对 GitHub 进行身份验证,请生成 personal access token。 有关详细信息,请参阅“向 GitHub API 进行身份验证”。

配置运行器规模集

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

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

    • 仔细更新 INSTALLATION_NAME 值。 在工作流中,将使用安装名称作为 runs-on 的值。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。

    • NAMESPACE 值更新为希望创建运行器 Pod 的位置。

    • GITHUB_CONFIG_URL 设置为存储库、组织或企业的 URL。 这是运行器将属于的实体。

    • 此示例命令安装最新版 Helm 图表。 若要安装特定版本,可以将 --version 参数与要安装的图表版本一起传递。 可以在 GitHub 容器注册表中找到发布列表。

      注意:

      • 作为安全最佳做法,请在与包含运算符 Pod 的命名空间不同的命名空间中创建运行器 Pod。
      • 从安全性角度而言,最佳做法是创建 Kubernetes 机密并传递机密引用。 通过 CLI 以纯文本传递机密可能会产生安全风险。 有关详细信息,请参阅“使用 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
      

      有关其他 Helm 配置选项,请参阅 ARC 文档中的 values.yaml

  2. 从终端运行以下命令,检查安装情况。

    Bash
    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-runners     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0
    
  3. 要检查管理器 Pod,请在终端中运行以下命令。

    Bash
    kubectl get pods -n arc-systems
    

    如果所有内容都已成功安装,Pod 的状态将显示为“正在运行”。

    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 的错误”以获取故障排除信息。

使用运行器规模集

现在,你将创建并运行一个简单的测试工作流,该工作流使用运行器规模集运行器。

  1. 在存储库中,创建类似于以下示例的工作流。 runs-on 值应与安装自动缩放运行器集时使用的 Helm 安装名称匹配。

    有关将工作流添加到存储库的详细信息,请参阅“GitHub Actions 快速入门”。

    YAML
    name: Actions Runner Controller Demo
    on:
      workflow_dispatch:
    
    jobs:
      Explore-GitHub-Actions:
        # You need to use the INSTALLATION_NAME from the previous step
        runs-on: arc-runner-set
        steps:
        - run: echo "🎉 This job uses runner scale set runners!"
    
  2. 将工作流添加到存储库后,请手动触发工作流。 有关详细信息,请参阅“手动运行工作流程”。

  3. 若要查看在工作流运行时创建的运行器 Pod,请从终端运行以下命令。

    Bash
    kubectl get pods -n arc-runners
    

    成功的输出与以下内容类似。

    NAMESPACE     NAME                                                  READY   STATUS    RESTARTS      AGE
    arc-runners   arc-runner-set-rmrgw-runner-p9p5n                     1/1     Running   0             21s
    

后续步骤

Actions Runner Controller 可以帮助你有效地管理 GitHub Actions 运行器。 准备好开始了吗? 以下是一些有用的资源,可帮助你对 ARC 执行后续操作:

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