教程：自动化 Runner 的创建和注册

本教程描述如何自动化 Runner 的创建和注册。

要自动化 Runner 的创建和注册：

1. 创建个人访问令牌。
2. 创建 Runner 配置。
3. 自动化 GitLab Runner 的安装和注册。
4. 查看使用相同配置的 Runner。

开始之前

• 必须在您的 GitLab 实例上安装 GitLab Runner。
• 要创建实例 Runner，您必须是管理员。
• 要创建组 Runner，您必须是管理员或拥有该组的 Owner 角色。
• 要创建项目 Runner，您必须是管理员或拥有该项目的 Maintainer 角色。

创建访问令牌

创建一个访问令牌，以便您可以使用 REST API 来创建 Runner。

您可以创建：

• 用于共享、组和项目 Runner 的个人访问令牌。
• 用于组和项目 Runner 的组或项目访问令牌。

访问令牌在 GitLab UI 中只显示一次。离开页面后，您将无法再访问该令牌。您应该使用密钥管理解决方案来存储令牌，例如 HashiCorp Vault 或 Keeper Secrets Manager Terraform 插件。

创建个人访问令牌

1. 在左侧边栏中，选择您的头像。
2. 选择 编辑个人资料。
3. 在左侧边栏中，选择 访问令牌。
4. 选择 添加新令牌。
5. 为令牌输入名称和过期日期。
   • 令牌在 UTC 午夜时过期。过期日期为 2024-01-01 的令牌将在 2024-01-01 00:00:00 UTC 过期。
   • 如果您不输入过期日期，过期日期将自动设置为当前日期后 365 天。
   • 默认情况下，此日期最多可以是当前日期后 365 天。在 GitLab 17.6 或更高版本中，您可以将 此限制延长到 400 天。
6. 在 选择范围 部分，选中 create_runner 复选框。
7. 选择 创建个人访问令牌。

创建项目或组访问令牌

要创建项目访问令牌：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或组。
2. 选择 设置 > 访问令牌。
3. 选择 添加新令牌
4. 输入名称。令牌名称对任何有权查看该组或项目的用户都可见。
5. 为令牌输入过期日期。
   • 令牌在 UTC 午夜时过期。过期日期为 2024-01-01 的令牌将在 2024-01-01 00:00:00 UTC 过期。
   • 如果您不输入过期日期，过期日期将自动设置为当前日期后 365 天。
   • 默认情况下，此日期最多可以是当前日期后 365 天。在 GitLab 17.6 或更高版本中，您可以将 此限制延长到 400 天。
   • 实例范围的 最大生命周期 设置可以限制 GitLab 自托管实例上的最大允许生命周期。
6. 从 选择角色 下拉列表中：
   • 对于项目访问令牌，选择 Maintainer。
   • 对于组访问令牌，选择 Owner。
7. 在 选择范围 部分，选中 create_runner 复选框。
8. 选择 创建项目访问令牌。

创建 Runner 配置

Runner 配置是您根据需求配置 Runner 的地方。

创建 Runner 配置后，您会收到一个 Runner 认证令牌来注册 Runner。当这些 Runner 使用相同的 Runner 认证令牌注册时，一个或多个 Runner 可以链接到相同的配置。Runner 配置存储在 config.toml 文件中。

要创建 Runner 配置，您可以使用：

• GitLab REST API。
• gitlab_user_runner Terraform 资源。

使用 GitLab REST API

开始前，您需要：

• 您的 GitLab 实例的 URL。例如，如果您的项目托管在 gitlab.example.com/yourname/yourproject，您的 GitLab 实例 URL 是 https://gitlab.example.com。
• 对于组或项目 Runner，组或项目的 ID 号。ID 号显示在项目或组概览页面上，项目或组名称下方。

使用 POST /user/runners REST 端点中的访问令牌来创建 Runner：

1. 使用 curl 调用端点来创建 Runner：

   项目

   curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
     --data "runner_type=project_type"
     --data "project_id=<project_id>"
     --data "description=<your_runner_description>"
     --data "tag_list=<your_comma_separated_job_tags>"
     --header "PRIVATE-TOKEN: <project_access_token>"

   组

   curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
     --data "runner_type=group_type"
     --data "group_id=<group_id>"
     --data "description=<your_runner_description>"
     --data "tag_list=<your_comma_separated_job_tags>"
     --header "PRIVATE-TOKEN: <group_access_token>"

   共享

   curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
     --data "runner_type=instance_type"
     --data "description=<your_runner_description>"
     --data "tag_list=<your_comma_separated_job_tags>"
     --header "PRIVATE-TOKEN: <personal_access_token>"

2. 将返回的 token 值保存在安全的位置或您的密钥管理解决方案中。token 值仅在 API 响应中返回一次。

使用 gitlab_user_runner Terraform 资源

要使用 Terraform 创建 Runner 配置，请使用 GitLab Terraform provider 中的 gitlab_user_runner Terraform 资源。

这是一个示例配置块：

resource "gitlab_user_runner" "example_runner" {
  runner_type = "instance_type"
  description = "my-runner"
  tag_list = ["shell", "docker"]
}

自动化 Runner 的安装和注册

如果您在公共云的虚拟机实例上托管 Runner，您可以自动化 Runner 的安装和注册。

创建 Runner 及其配置后，您可以使用相同的 Runner 认证令牌来注册多个具有相同配置的 Runner。例如，您可以部署多个具有相同执行器类型和作业标签的实例 Runner 到目标计算主机。每个使用相同 Runner 认证令牌注册的 Runner 都有一个唯一的 system_id，这是 GitLab Runner 随机生成并存储在您本地文件系统中的。

这是一个您可以用来注册和部署 Runner 到 Google Compute Engine 的自动化工作流程示例：

1. 使用 Terraform 基础设施即代码 将 Runner 应用程序安装到托管在 Google Cloud Platform (GCP) 上的虚拟机。

2. 在 GCP Terraform provider 中， 使用 metadata 键将 Runner 认证令牌添加到 GCP 虚拟机上的 Runner 配置文件。

3. 要将 Runner 注册到目标 GitLab 实例，使用从 GCP Terraform provider 填充的 cloud-init 脚本。这是一个示例：

   #!/bin/bash
   apt update
   curl --location "https://packages.gitlab.com/install/repositories/runner/
   gitlab-runner/script.deb.sh" | bash
   GL_NAME=$(curl 169.254.169.254/computeMetadata/v1/instance/name
   --header "Metadata-Flavor:Google")
   GL_EXECUTOR=$(curl 169.254.169.254/computeMetadata/v1/instance/attributes/
   gl_executor --header "Metadata-Flavor:Google")
   apt update
   apt install -y gitlab-runner
   gitlab-runner register --non-interactive --name="$GL_NAME" --url="https://gitlab.com"
     --token="$RUNNER_TOKEN" --request-concurrency="12" --executor="$GL_EXECUTOR"
     --docker-image="alpine:latest"
   systemctl restart gitlab-runner

查看使用相同配置的 Runner

现在您已经自动化了 Runner 的创建和自动化，您可以在 GitLab UI 中查看使用相同配置的 Runner。

1. 在左侧边栏底部，选择 Admin。
2. 选择 CI/CD > Runners。
3. 在搜索框中，输入 Runner 描述或搜索 Runner 列表。
4. 要查看使用相同配置的 Runner，在 详细信息 选项卡中，在 Runners 旁边，选择 显示详情。