{"meta":{"title":"Actions Runner 控制器入门","intro":"在本教程中，你将体验 Actions Runner Controller 的基本用法。","product":"GitHub Actions","breadcrumbs":[{"href":"/zh/actions","title":"GitHub Actions"},{"href":"/zh/actions/tutorials","title":"教程"},{"href":"/zh/actions/tutorials/use-actions-runner-controller","title":"Actions运行器控制器"},{"href":"/zh/actions/tutorials/use-actions-runner-controller/get-started","title":"开始"}],"documentType":"article"},"body":"# Actions Runner 控制器入门\n\n在本教程中，你将体验 Actions Runner Controller 的基本用法。\n\n## 先决条件\n\n请确保您具备以下内容以使用 ARC。\n\n* 一个 Kubernetes 群集\n  * 对于托管云环境，可以使用 AKS。 有关详细信息，请参阅Azure文档中的 [Azure Kubernetes Service](https://azure.microsoft.com/en-us/products/kubernetes-service)。\n  * 对于本地设置，可以使用 minikube 或 kind。 有关详细信息，请参阅 minikube 文档中的 [minikube start](https://minikube.sigs.k8s.io/docs/start/) 和 kind 文档中的 [kind](https://kind.sigs.k8s.io/)。\n\n* Helm 3\n  * 有关详细信息，请参阅 Helm 文档中的[安装 Helm](https://helm.sh/docs/intro/install/)。\n\n* 虽然不需要部署 ARC，但我们建议在将 ARC 部署到生产工作流中之前，确保已实现从控制器、侦听器和临时运行器中收集和保留日志的方法。\n\n## 安装动作运行器控制器\n\n1. 若要在群集中安装运算符和自定义资源定义 (CRD)，请执行以下操作。\n\n   1. 在 Helm 图表中，将 `NAMESPACE` 值更新为希望创建运算符 Pod 的位置。 此命名空间必须允许访问 Kubernetes API 服务器。\n   2. 安装 Helm 图表。\n\n   以下示例将安装最新版的图表。 若要安装特定版本，可以将 `--version` 参数与要安装的图表版本一起传递。 可以在 [GitHub 容器注册表](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set-controller)中找到发布列表。\n\n   ```bash copy\n   NAMESPACE=\"arc-systems\"\n   helm install arc \\\n       --namespace \"${NAMESPACE}\" \\\n       --create-namespace \\\n       oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller\n   ```\n\n   有关其他 Helm 配置选项，请参阅 ARC 文档中的 [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set-controller/values.yaml)。\n\n2. 若要使 ARC 能够对 GitHub 进行身份验证，请生成 personal access token (classic)。 有关详细信息，请参阅“[将 ARC 认证到 GitHub API](/zh/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api#deploying-using-personal-access-token-classic-authentication)”。\n\n## 配置运行器规模集\n\n1. 要配置运行器规模集，请使用 ARC 配置中的值在终端中运行以下命令。\n\n   运行命令时，请记住以下事项。\n\n   * 仔细更新 `INSTALLATION_NAME` 值。 在工作流中，将使用安装名称作为 `runs-on` 的值。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)”。\n\n   * 将 `NAMESPACE` 值更新为要在其中创建运行程序 Pod 的位置。\n\n   * 将 `GITHUB_CONFIG_URL` 设置为存储库、组织或企业的 URL。 这是运行器将属于的实体。\n\n   * 将 `GITHUB_PAT` 设置为 GitHub personal access token，并使用 `repo` 和 `admin:org` 范围应用于存储库和组织的运行器。\n\n   * 此示例命令安装最新版 Helm 图表。 若要安装特定版本，可以将 `--version` 参数与要安装的图表版本一起传递。 可以在 [GitHub 容器注册表](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set)中找到发布列表。\n\n     > \\[!NOTE]\n     >\n     > * 作为安全最佳做法，请在与包含运算符 Pod 的命名空间不同的命名空间中创建运行器 Pod。\n     > * 从安全性角度而言，最佳做法是创建 Kubernetes 机密并传递机密引用。 通过 CLI 以纯文本传递机密可能会产生安全风险。 有关详细信息，请参阅“[使用 Actions Runner Controller 部署运行程序规模集](/zh/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller)”。\n\n     ```bash copy\n     INSTALLATION_NAME=\"arc-runner-set\"\n     NAMESPACE=\"arc-runners\"\n     GITHUB_CONFIG_URL=\"https://github.com/<your_enterprise/org/repo>\"\n     GITHUB_PAT=\"<PAT>\"\n     helm install \"${INSTALLATION_NAME}\" \\\n         --namespace \"${NAMESPACE}\" \\\n         --create-namespace \\\n         --set githubConfigUrl=\"${GITHUB_CONFIG_URL}\" \\\n         --set githubConfigSecret.github_token=\"${GITHUB_PAT}\" \\\n         oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set\n     ```\n\n     有关其他 Helm 配置选项，请参阅 ARC 文档中的 [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml)。\n\n2. 从终端运行以下命令，检查安装情况。\n\n   ```bash copy\n   helm list -A\n   ```\n\n   此时会看到类似下面的输出。\n\n   ```bash\n   NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                                       APP VERSION\n   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\n   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\n   ```\n\n3. 要检查管理器 Pod，请在终端中运行以下命令。\n\n   ```bash copy\n   kubectl get pods -n arc-systems\n   ```\n\n   如果所有内容都已成功安装，Pod 的状态将显示为“正在运行”。\n\n   ```bash\n   NAME                                                   READY   STATUS    RESTARTS   AGE\n   arc-gha-runner-scale-set-controller-594cdc976f-m7cjs   1/1     Running   0          64s\n   arc-runner-set-754b578d-listener                       1/1     Running   0          12s\n   ```\n\n如果安装未成功，请参阅 [排查 Actions Runner Controller 的错误](/zh/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors) 获取故障排除信息。\n\n## 使用运行器规模集\n\n现在，你将创建并运行一个简单的测试工作流，该工作流使用运行器规模集运行器。\n\n1. 在存储库中，创建类似于以下示例的工作流。\n   `runs-on` 值应与安装自动缩放运行器集时使用的 Helm 安装名称匹配。\n\n   有关将工作流添加到仓库的详细信息，请参阅“[GitHub Actions快速入门](/zh/actions/quickstart#creating-your-first-workflow)”。\n\n   ```yaml copy\n   name: Actions Runner Controller Demo\n   on:\n     workflow_dispatch:\n\n   jobs:\n     Explore-GitHub-Actions:\n       # You need to use the INSTALLATION_NAME from the previous step\n       runs-on: arc-runner-set\n       steps:\n       - run: echo \"🎉 This job uses runner scale set runners!\"\n   ```\n\n2. 将工作流添加到存储库后，请手动触发工作流。 有关详细信息，请参阅“[手动运行工作流](/zh/actions/managing-workflow-runs/manually-running-a-workflow)”。\n\n3. 若要查看在工作流运行时创建的运行器 Pod，请从终端运行以下命令。\n\n   ```bash copy\n   kubectl get pods -n arc-runners -w\n   ```\n\n   成功的输出应类似于以下内容。\n\n   ```bash\n   NAMESPACE     NAME                                                  READY   STATUS    RESTARTS      AGE\n   arc-runners   arc-runner-set-rmrgw-runner-p9p5n                     1/1     Running   0             21s\n   ```\n\n## 后续步骤\n\nActions Runner Controller 可以帮助你有效地管理 GitHub Actions 运行器。 准备好开始了吗？ 以下是一些有用的资源，可帮助你对 ARC 执行后续操作：\n\n* 有关详细的身份验证信息，请参阅“[将 ARC 认证到 GitHub API](/zh/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api)”。\n* 有关在工作流中使用 ARC 运行器的帮助，请参阅“[在工作流中使用 Actions Runner Controller 运行器](/zh/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow)”。\n* 有关部署信息，请参阅“[使用 Actions Runner Controller 部署运行程序规模集](/zh/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller)”。\n\n## 法律通告\n\n部分内容改编自 Apache-2.0 许可证下的 <https://github.com/actions/actions-runner-controller/> ：\n\n```text\nCopyright 2019 Moto Ishizawa\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```"}