极狐 GitLab Logo

教程：自动化 runner 创建并注册

这篇教程描述了如何自动化 runner 创建和注册。

要自动化 runner 创建和注册：

  1. 创建一个个人访问令牌。
  2. 创建一个 runner 配置。
  3. 自动化极狐GitLab Runner安装和注册。
  4. 查看具有相同配置的 runners。
本教程中的说明描述了使用 runner 身份验证令牌进行 runner 创建和注册，已替代使用注册令牌的已弃用注册方法。有关更多信息，请参见[新的 runner 注册工作流](../../ci/runners/new_creation_workflow.md#the-new-runner-registration-workflow)。

开始之前#

  • 必须在你的极狐GitLab 实例上安装极狐GitLab Runner。
  • 要创建实例 runners，你必须是管理员。
  • 要创建群组 runners，你必须是管理员或者拥有该群组的所有者角色。
  • 要创建项目 runners，你必须是管理员或者拥有该项目的维护者角色。

创建访问令牌#

创建一个访问令牌以便使用 REST API 创建 runners。

你可以创建：

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

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

创建个人访问令牌#

History
    • 在极狐GitLab 17.6 中进行了更改，最大允许的生命周期的值变为 400 天，使用名为 buffered_token_expiration_limit 的功能标志。默认禁用。
扩展的最大允许生命周期限制的可用性由功能标志控制。有关更多信息，请参见历史记录。
  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. 选择 创建个人访问令牌。

创建项目或群组访问令牌#

History
    • 在极狐GitLab 17.6 中进行了更改，最大允许的生命周期的值变为 400 天，使用名为 buffered_token_expiration_limit 的功能标志。默认禁用。
扩展的最大允许生命周期限制的可用性由功能标志控制。有关更多信息，请参见历史记录。
项目访问令牌被视为[内部用户](../../administration/internal_users.md)。如果内部用户创建项目访问令牌，该令牌能够访问所有可见性级别设置为[内部](../../user/public_access.md)的项目。

要创建项目访问令牌：

  1. 在左侧边栏，选择 搜索或前往 并找到你的项目或群组。
  2. 选择 设置 > 访问令牌。
  3. 选择 添加新令牌。
  4. 输入一个名称。令牌名称对任何有权限查看群组或项目的用户可见。
  5. 输入令牌的过期日期。

    • 令牌在该日期午夜 UTC 过期。具有过期日期为 2024-01-01 的令牌将于 2024-01-01 的 00:00:00 UTC 过期。

    • 如果不输入过期日期，过期日期会自动设置为当前日期的 365 天后。

    • 默认情况下，这个日期可以是当前日期的最多 365 天之后。在极狐GitLab 17.6 或更高版本中，你可以将此限制延长到 400 天。

    • 实例范围的最大生命周期设置可以限制极狐GitLab 私有化部署实例上的最大允许生命周期。

  6. 从 选择角色 下拉列表中：
    • 对于项目访问令牌，选择 维护者。
    • 对于群组访问令牌，选择 所有者。
  7. 在 选择范围 部分，选择 create_runner 复选框。
  8. 选择 创建项目访问令牌。

创建 runner 配置#

runner 配置是你根据需求配置 runners 的地方。

创建 runner 配置后，你会收到一个 runner 身份验证以注册 runner。当这些 runners 使用相同的 runner 身份验证令牌注册时，一个或多个 runners 可以链接到相同的配置。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。
  • 对于群组或项目 runners，群组或项目的 ID 号。ID 号显示在项目或群组概览页面的项目或群组名称下。

在 POST /user/runners REST 端点中使用访问令牌创建一个 runner：

  1. 使用 curl 调用端点以创建一个 runner：

shell
1   curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
2     --data "runner_type=project_type"
3     --data "project_id=<project_id>"
4     --data "description=<your_runner_description>"
5     --data "tag_list=<your_comma_separated_job_tags>"
6     --header "PRIVATE-TOKEN: <project_access_token>"
shell
1   curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
2     --data "runner_type=group_type"
3     --data "group_id=<group_id>"
4     --data "description=<your_runner_description>"
5     --data "tag_list=<your_comma_separated_job_tags>"
6     --header "PRIVATE-TOKEN: <group_access_token>"
shell
   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>"
  1. 在安全位置或密钥管理解决方案中保存返回的 token 值。token 值在 API 响应中只返回一次。

使用 gitlab_user_runner Terraform 资源#

要使用 Terraform 创建 runner 配置，请使用极狐GitLab Terraform 提供商中的 gitlab_user_runner Terraform 资源。

这是一个示例配置块：

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

自动化 runner 安装和注册#

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

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

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

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

  2. 在 GCP Terraform 提供商中，使用 metadata 键将 runner 身份验证令牌添加到 GCP 虚拟机上的 runner 配置文件中。

  3. 要在目标极狐GitLab 实例中注册 runner，请使用从 GCP Terraform 提供商中填充的 cloud-init 脚本。以下是一个示例：

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

查看具有相同配置的 runners#

现在你已经自动化了 runner 创建和自动化，你可以在极狐GitLab UI 中查看使用相同配置的 runners。

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