极狐 GitLab Logo

计划和运维实例或群组 runner fleet

这份指南包含了在共享服务模型中扩展 runner 集群的最佳实践。

当您托管一个实例 runner 集群时，您需要一个精心规划的基础设施，以考虑到您的：

  • 计算能力。
  • 存储容量。
  • 网络带宽和吞吐量。
  • 作业类型（包括编程语言、操作系统平台和依赖库）。

使用本指南来根据您组织的需求制定极狐GitLab Runner 部署策略。

本指南不对您应该使用的基础设施类型提供具体建议。但它提供了从 JihuLab.com 上运行 runner 集群的经验中获得的见解，该集群每月处理数以百万计的 CI/CD 作业。

考虑您的工作负载和环境#

在您部署 runners 之前，请考虑您的工作负载和环境需求。

  • 创建一个计划要在极狐GitLab 上注册的团队列表。
  • 编制您组织中使用的编程语言、Web 框架和库的目录。例如，Go、C++、PHP、Java、Python、JavaScript、React、Node.js。
  • 估算每个团队每天、每小时可能执行的 CI/CD 作业数量。
  • 验证是否有任何团队有无法通过使用容器解决的构建环境要求。
  • 验证是否有任何团队的构建环境要求最好由专用于该团队的 runner 来满足。
  • 估算您可能需要的计算能力以支持预期的需求。

您可能会选择不同的基础设施堆栈来托管不同的 runner 集群。例如，您可能需要在公共云和本地部署一些 runners。

runner 集群上 CI/CD 作业的性能与集群的环境直接相关。如果您正在执行大量资源密集型的 CI/CD 作业，不建议将集群托管在共享计算平台上。

Runners、执行器和自动扩展能力#

gitlab-runner 可执行文件运行您的 CI/CD 作业。每个 runner 是一个隔离的进程，接收作业执行请求并根据预定义的配置处理这些请求。作为一个隔离的进程，每个 runner 可以创建“子进程”（也称为“工作者”）来运行作业。

并发和限制#

  • 并发：设置当您在主机系统上使用所有配置的 runner 时可以并发运行的作业数量。
  • 限制：设置 runner 可以创建的子进程数量，以便同时执行作业。

对于自动扩展 runners（如 Docker Machine 和 Kubernetes），限制与不自动扩展的 runners 是不同的。

  • 对于不自动扩展的 runners，限制 定义了主机系统上 runner 的容量。
  • 对于自动扩展 runners，限制 是您希望运行的 runner 总数。

基本配置：一个 runner 管理器，一个 runner#

对于最基本的配置，您在支持的计算架构和操作系统上安装极狐GitLab Runner 软件。例如，您可能有一个运行 Ubuntu Linux 的 x86-64 虚拟机 (VM)。

安装完成后，您只需执行一次 runner 注册命令，并选择 shell 执行器。然后您编辑 runner config.toml 文件以将并发设置为 1。

toml
1concurrent = 1
2
3[[runners]]
4  name = "instance-level-runner-001"
5  url = ""
6  token = ""
7  executor = "shell"

这个 runner 可以处理的极狐GitLab CI/CD 作业直接在您安装 runner 的主机系统上执行。就像您自己在终端中运行 CI/CD 作业命令一样。在这种情况下，由于您只执行了一次注册命令，config.toml 文件中只包含一个 [[runners]] 部分。假设您将并发值设置为 1，那么只有一个 runner“工作者”可以为该系统上的 runner 进程执行 CI/CD 作业。

中级配置：一个 runner 管理器，多个 runners#

您还可以在同一台机器上注册多个 runner。当您这样做时，runner 的 config.toml 文件中会有多个 [[runners]] 部分。如果所有其他 runner 工作者都使用 shell 执行器，并且您将全局 concurrent 设置值更新为 3，则主机可以一次运行最多三个作业。

toml
1concurrent = 3
2
3[[runners]]
4  name = "instance_level_shell_001"
5  url = ""
6  token = ""
7  executor = "shell"
8
9[[runners]]
10  name = "instance_level_shell_002"
11  url = ""
12  token = ""
13  executor = "shell"
14
15[[runners]]
16  name = "instance_level_shell_003"
17  url = ""
18  token = ""
19  executor = "shell"

您可以在同一台机器上注册多个 runner 工作者，每个工作者都是一个隔离的进程。每个工作者的 CI/CD 作业性能依赖于主机系统的计算能力。

自动扩展配置：一个或多个 runner 管理器，多个工作者#

当极狐GitLab Runner 设置为自动扩展时，您可以配置一个 runner 作为其他 runners 的管理器。您可以使用 docker-machine 或 kubernetes 执行器来实现这种仅管理器配置，在这种配置中，runner 代理本身不执行任何 CI/CD 作业。

Docker Machine 执行器#

使用 Docker Machine 执行器：

  • runner 管理器按需提供带有 Docker 的虚拟机实例。
  • 在这些虚拟机上，极狐GitLab Runner 使用您在 .gitlab-ci.yml 文件中指定的容器镜像来执行 CI/CD 作业。
  • 您应该测试您的 CI/CD 作业在各种机器类型上的性能。
  • 您应该考虑根据速度或成本优化您的计算主机。

Kubernetes 执行器#

使用 Kubernetes 执行器：

  • runner 管理器在目标 Kubernetes 集群上提供 pods。
  • CI/CD 作业在每个 pod 上执行，pod 由多个容器组成。
  • 用于作业执行的 pods 通常需要比托管 runner 管理器的 pod 更多的计算和内存资源。

重用 runner 配置#

与同一 runner 身份验证令牌关联的每个 runner 管理器都会分配一个 system_id 标识符。system_id 识别 runner 使用的机器。使用相同身份验证令牌注册的 runners 按唯一 system_id 分组在一个 runner 条目下。

将相似的 runners 分组在一个配置下简化了 runner 集群操作。

以下是一个可以将相似的 runners 分组在一个配置下的示例场景：

平台管理员需要提供多个具有相同基础虚拟机实例大小（2 vCPU，8 GB RAM）的 runners，并使用标签 docker-builds-2vCPU-8GB。他们希望至少有两个这样的 runners，无论是为了高可用性还是扩展。管理员可以为所有具有相同计算实例大小的 runners 创建一个 runner 配置，而不是在 UI 中创建两个不同的 runner 条目。他们可以重用 runner 配置的身份验证令牌来注册多个 runners。每个注册的 runner 继承 docker-builds-2vCPU-8GB 标签。对于单个 runner 配置的所有子 runners，system_id 充当唯一标识符。

分组的 runners 可以被多个 runner 管理器重用以运行不同的作业。

极狐GitLab Runner 在启动时或保存配置时生成 system_id。system_id 保存在与 config.toml 相同目录下的 .runner_system_id 文件中，并在作业日志和 runner 管理页面中显示。

生成 system_id 标识符#

为了生成 system_id，极狐GitLab Runner 尝试从硬件标识符中派生唯一的系统标识符（例如，在某些 Linux 发行版中是 /etc/machine-id）。如果不成功，极狐GitLab Runner 使用随机标识符生成 system_id。

system_id 具有以下前缀之一：

  • r_: 极狐GitLab Runner 分配的随机标识符。
  • s_: 极狐GitLab Runner 从硬件标识符分配的唯一系统标识符。

在创建容器镜像时需要考虑这一点，以便 system_id 不会被硬编码到镜像中。如果 system_id 被硬编码，您将无法区分执行给定作业的主机。

删除 runners 和 runner 管理器#

要删除使用 runner 注册令牌（已弃用）注册的 runners 和 runner 管理器，请使用 gitlab-runner unregister 命令。

要删除使用 runner 身份验证令牌创建的 runners 和 runner 管理器，请使用 UI 或 API。使用 runner 身份验证令牌创建的 runners 是可重用配置，可以在多台机器上重用。如果您使用 gitlab-runner unregister 命令，则仅删除 runner 管理器，而不是 runner。

配置实例 runners#

在自动扩展配置中使用实例 runners（其中 runner 作为“runner 管理器”）是一种高效且有效的启动方式。

您托管虚拟机或 pods 的基础设施堆栈的计算能力取决于：

  • 您在考虑工作负载和环境时捕获的需求。
  • 您用于托管 runner 集群的技术堆栈。

您可能需要在开始运行 CI/CD 工作负载并随着时间的推移分析性能后调整计算能力。

对于使用自动扩展执行器的实例 runners 配置，您必须从至少两个 runner 管理器开始。

随着时间的推移，您可能需要的 runner 管理器总数取决于：

  • 托管 runner 管理器的堆栈的计算资源。
  • 您选择为每个 runner 管理器配置的并发。
  • 每个管理器每小时、每天和每月执行的 CI/CD 作业产生的负载。

例如，在 JihuLab.com 上，我们运行了七个带有 Docker Machine 执行器的 runner 管理器。每个 CI/CD 作业在 Google Cloud Platform (GCP) n1-standard-1 虚拟机中执行。通过这种配置，我们每月处理数百万个作业。

监控 runners#

在大规模运行 runner 集群的一个关键步骤是设置并使用极狐GitLab 附带的 runner 监控 功能。

下表包含了极狐GitLab Runner 指标的摘要。该列表不包括 Go 特定的进程指标。要在 runner 上查看这些指标，请执行在 可用指标 中注明的命令。

指标名称描述
gitlab_runner_api_request_statuses_total按 runner、端点和状态分区的 API 请求总数。
gitlab_runner_autoscaling_machine_creation_duration_seconds机器创建时间的直方图。
gitlab_runner_autoscaling_machine_states此提供者中每个状态的机器数量。
gitlab_runner_concurrent并发设置的值。
gitlab_runner_errors_total捕获错误的数量。此指标是一个跟踪日志行的计数器。该指标包括标签 level。可能的值是 warning 和 error。如果您计划包含此指标，请在观察时使用 rate() 或 increase()。换句话说，如果您注意到警告或错误的速率增加，这可能表明需要进一步调查的问题。
gitlab_runner_jobs这显示了正在执行的作业数量（标签中具有不同的范围）。
gitlab_runner_job_duration_seconds作业持续时间的直方图。
gitlab_runner_job_queue_duration_seconds作业队列持续时间的直方图。
gitlab_runner_acceptable_job_queuing_duration_exceeded_total统计作业超过配置的排队时间阈值的次数。
gitlab_runner_job_stage_duration_seconds表示每个阶段作业持续时间的直方图。此指标是一个高基数指标。有关更多信息，请参阅高基数指标部分。
gitlab_runner_jobs_total显示执行的总作业数。
gitlab_runner_limit限制设置的当前值。
gitlab_runner_request_concurrency当前对新作业的并发请求数。
gitlab_runner_request_concurrency_exceeded_total超出配置的 request_concurrency 限制的请求计数。
gitlab_runner_version_info一个常数值为 1 的指标，标记了不同的构建状态字段。
process_cpu_seconds_total用户和系统 CPU 时间总计（以秒为单位）。
process_max_fds打开的文件描述符的最大数量。
process_open_fds打开的文件描述符数量。
process_resident_memory_bytes驻留内存大小（以字节为单位）。
process_start_time_seconds进程的开始时间，以 Unix 纪元开始的秒数为单位。
process_virtual_memory_bytes虚拟内存大小（以字节为单位）。
process_virtual_memory_max_bytes可用虚拟内存的最大量（以字节为单位）。

Grafana 仪表板配置提示#

我们为 JihuLab.com 跟踪了许多指标。作为云端 CI/CD 的大型提供商，我们需要许多不同的视图来调试问题。在大多数情况下，私有化部署的 runner 集群不需要跟踪我们在 JihuLab.com 上跟踪的指标数量。

以下是一些您应该用来监控 runner 集群的基本仪表板。

在 runners 上启动的作业：

  • 查看在选定时间间隔内您的 runner 集群上执行的作业总数概览。
  • 查看使用趋势。您至少应该每周分析一次此仪表板。

将此数据与作业持续时间等指标相关联，以确定您是否需要进行配置更改或容量升级以满足您的 CI/CD 作业性能 SLO。

作业持续时间：

  • 分析您的 runner 集群的性能和扩展。

Runner 容量：

  • 查看正在执行的作业数量，按限制或并发的值划分。
  • 确定是否仍然有执行其他作业的容量。

在 Kubernetes 上监控 runners 的注意事项#

对于托管在 Kubernetes 平台（如 OpenShift、EKS 或 GKE）上的 runner 集群，请使用不同的方法来设置 Grafana 仪表板。

在 Kubernetes 上，runner CI/CD 作业执行 pods 可能会频繁创建和删除。在这些情况下，您应该计划监控 runner 管理器 pod 并可能实施以下操作：

  • 量表：显示来自不同来源的相同指标的聚合。
  • 计数器：在应用 rate 或 increase 函数时重置计数器。

高基数指标#

由于高基数，有些指标在摄取和存储时可能会消耗大量资源。高基数发生在指标包含具有许多可能值的标签时，导致大量唯一的时间序列数据点。

为了优化性能，此类指标默认情况下未启用，并可以通过使用 FF_EXPORT_HIGH_CARDINALITY_METRICS 功能标志进行切换。

高基数指标列表#

  • gitlab_runner_job_stage_duration_seconds: 测量各个作业阶段的持续时间（以秒为单位）。此指标包括 stage 标签，该标签可以具有以下预定义值：

    • resolve_secrets
    • prepare_executor
    • prepare_script
    • get_sources
    • clear_worktree
    • restore_cache
    • download_artifacts
    • after_script
    • step_script
    • archive_cache
    • archive_cache_on_failure
    • upload_artifacts_on_success
    • upload_artifacts_on_failure
    • cleanup_file_variables

    此外，此列表可能包括用户自定义步骤，如 step_run。

管理高基数指标#

您可以通过使用 Prometheus 重标记配置 来控制和减少基数，以移除不必要的标签值或整个指标。

移除特定阶段的示例配置#

以下配置移除任何在 stage 标签中具有 prepare_executor 值的指标：

yaml
1scrape_configs:
2  - job_name: 'gitlab_runner_metrics'
3    static_configs:
4      - targets: ['localhost:9252']
5    metric_relabel_configs:
6      - source_labels: [__name__, "stage"]
7        regex: "gitlab_runner_job_stage_duration_seconds;prepare_executor"
8        action: drop

仅保留相关阶段的示例#

以下配置仅保留 step_script 阶段的指标，并完全丢弃其他指标：

yaml
1scrape_configs:
2  - job_name: 'gitlab_runner_metrics'
3    static_configs:
4      - targets: ['localhost:9252']
5    metric_relabel_configs:
6      - source_labels: [__name__, "stage"]
7        regex: "gitlab_runner_job_stage_duration_seconds;step_script"
8        action: keep