• 配置验证
• 全局部分
  • log_format 示例 (删节)
    • runner
    • text
    • json
  • check_interval 如何工作
• [session_server] 部分
• [[runners]] 部分
  • clone_url 如何工作
• 执行器
• Shell
  • 使用符合POSIX 的 Shell
• [runners.docker] 部分
  • [[runners.docker.services]] 部分
  • [runners.docker] 部分中的卷
    • 示例 1：添加数据卷
    • 示例 2：以数据卷的形式挂载主机目录
  • 使用私有容器镜像库
    • 极狐GitLab 集成镜像库支持
    • Docker 认证解析的优先级别
• [runners.parallels] 部分
• [runners.virtualbox] 部分
• 覆盖基本虚拟机镜像
• [runners.ssh] 部分
• [runners.machine] 部分
  • [[runners.machine.autoscaling]] 部分
  • Periods 语法
• [runners.instance] 部分（Alpha）
• [runners.autoscaler] 部分
• [runners.autoscaler.plugin_config] 部分
• [runners.autoscaler.connector_config] 部分
• [[runners.autoscaler.policy]] 部分
  • Periods 语法
• [runners.custom] 部分
• [runners.cache] 部分
  • [runners.cache.s3] 部分
    • 为 Runner 缓存在 S3 桶中使用 KMS 密钥加密
    • 为 Kubernetes ServiceAccount 资源启用 IAM 角色
  • [runners.cache.gcs] 部分
  • [runners.cache.azure] 部分
• [runners.kubernetes] 部分
• Helper 镜像
  • Kubernetes on Arm 的 Helper 镜像配置
  • 使用老版本 Alpine Linux 的 Runner 镜像
  • Alpine pwsh 镜像
  • Helper 镜像库
  • 覆盖 Helper 镜像
    • 使用 PowerShell Core 时
• [runners.custom_build_dir] 部分
  • 默认构建目录
• [runners.referees] 部分
  • 使用 Metrics Runner Referee
  • 为极狐GitLab Runner 配置 Metrics Runner Referee

高级配置

您可以改变极狐GitLab Runner 和单独注册的 Runner 的行为。

为此，您需要更改一个名为 config.toml 的文件，它使用 TOML 格式。

大多数选项的更改都不需要重启极狐GitLab Runner，包括 [[runners]] 部分的参数和全局部分的大多数参数，除了 listen_address。 如果已经注册了 Runner，您无需再次注册。

极狐GitLab Runner 每 3 秒查看一次配置更改，如有必要会重新加载配置。 极狐GitLab Runner 还会响应 SIGHUP 信号重新加载配置。

您可以在以下位置找到 config.toml 文件：

• 当极狐GitLab Runner 以根用户执行(同样是服务配置的路径)时，*nix 系统上的 /etc/gitlab-runner/。
• 当极狐GitLab Runner 以非根用户执行时，*nix 系统上的 ~/.gitlab-runner/。
• 其他系统上的 ./。

配置验证

引入于极狐GitLab Runner 15.10。

配置验证是一个检查 config.toml 文件结构的过程。配置验证器的输出仅提供 info 级别的消息。

配置验证是尽力而为的，目前仅供参考。它可以帮助用户识别其 Runner 配置的潜在问题。它可能无法捕获所有可能的问题，并且没有任何消息并不能保证 config.toml 文件是完美无缺的。

随着时间的推移，验证过程将得到改进，以提供更准确、全面和有用的反馈。您应该使用最新版本的极狐GitLab Runner 以享受最新的改进和增强功能。

全局部分

以下是全局设置，适用所有 Runner。

配置示例：

concurrent = 4
log_level = "warning"

log_format 示例 (删节)

runner

Runtime platform                                    arch=amd64 os=darwin pid=37300 revision=HEAD version=development version
Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
WARNING: Running in user-mode.
WARNING: Use sudo for system-mode:
WARNING: $ sudo gitlab-runner...

Configuration loaded                                builds=0
listen_address not defined, metrics & debug endpoints disabled  builds=0
[session_server].listen_address not defined, session endpoints disabled  builds=0

text

INFO[0000] Runtime platform                              arch=amd64 os=darwin pid=37773 revision=HEAD version="development version"
INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
WARN[0000] Running in user-mode.
WARN[0000] Use sudo for system-mode:
WARN[0000] $ sudo gitlab-runner...
INFO[0000]
INFO[0000] Configuration loaded                          builds=0
INFO[0000] listen_address not defined, metrics & debug endpoints disabled  builds=0
INFO[0000] [session_server].listen_address not defined, session endpoints disabled  builds=0

json

{"arch":"amd64","level":"info","msg":"Runtime platform","os":"darwin","pid":38229,"revision":"HEAD","time":"2020-06-05T15:57:35+02:00","version":"development version"}
{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Running in user-mode.","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Use sudo for system-mode:","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2020-06-05T15:57:35+02:00"}
{"level":"info","msg":"","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"Configuration loaded","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"listen_address not defined, metrics \u0026 debug endpoints disabled","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"[session_server].listen_address not defined, session endpoints disabled","time":"2020-06-05T15:57:35+02:00"}

check_interval 如何工作

如果 config.toml 中存在多个 [[runners]] 部分， 向极狐GitLab 请求的间隔就会比您预期的更频繁。极狐GitLab Runner 包含一个不断向配置的极狐GitLab 实例调度请求的循环。

极狐GitLab Runner 试图保证以特定间隔向每个 Runner 发送后续请求。 为此，它用 [[runners]] 部分的数量除以 check_interval 的值。循环在所有部分中迭代，为每个部分调度请求，并在计算好的时间休眠。 当 Runner 和另一个极狐GitLab 实例绑定时会更加有趣。 请思考下面的例子。

如果您设置了 check_interval = 10，而且有两个 Runner (runner-1 和 runner-2)， 每 10 秒会发送一个请求。下面是这种情况中循环的一个例子：

1. 获取 check_interval 值 (10s)。
2. 获取 Runner 列表 (runner-1、runner-2)。
3. 计算休眠间隔 (10s / 2 = 5s)。
4. 开启无限循环：
   1. 为 runner-1 请求作业。
   2. 休眠 5s。
   3. 为 runner-2 请求作业。
   4. 休眠 5s。
   5. 重复。

在这个例子中，Runner 进程每 5 秒发送一个请求。 如果 runner-1 和 runner-2 连接到同一个极狐GitLab 实例，这个实例也会每 5 秒收到这个 Runner 发送的新请求。

在 runner-1 的第一个请求和 runner-1 的第二个请求之间，有两个休眠周期，每个 5 秒钟，所以 runner-1 的后续请求之间的间隔大约是 10 秒。 runner-2 也一样。

如果您定义了更多的 Runner，休眠间隔就会更小。然而，所有对其他 Runner 及其休眠周期的请求被调用后，会重复对 Runner 的请求。

[session_server] 部分

[session_server] 部分可以让用户和作业交互，例如在交互式 Web 终端中。

[session_server] 部分应该在根级别进行指定，而不是每个 Runner。 应该在 [[runners]] 部分之外对其进行定义。

[session_server]
  listen_address = "[::]:8093" #  listen on all available interfaces on port 8093
  advertise_address = "runner-host-name.tld:8093"
  session_timeout = 1800

配置 [session_server] 部分时：

• 对于 listen_address 和 advertise_address，使用 host:port 格式，其中 host 是 IP 地址 (127.0.0.1:8093) 或域 (my-runner.example.com:8093)。 Runner 使用此信息为安全连接创建 TLS 证书。
• 确保您的网络浏览器可以连接到 advertise_address。实时会话由 Web 浏览器发起。
• 确保 advertise_address 是公共 IP 地址，除非您启用了应用程序设置，allow_local_requests_from_web_hooks_and_services。

如果想禁用会话服务器和终端支持，请删除 [session_server] 部分。

如果您正在使用极狐GitLab Runner Docker 镜像，您必须添加 -p 8093:8093， 将端口 8093 显示给 docker run 命令。

[[runners]] 部分

每个 [[runners]] 部分定义一个 Runner。

示例：

[[runners]]
  name = "ruby-2.7-docker"
  url = "https://CI/"
  token = "TOKEN"
  limit = 0
  executor = "docker"
  builds_dir = ""
  shell = ""
  environment = ["ENV=value", "LC_ALL=en_US.UTF-8"]
  clone_url = "http://gitlab.example.local"

clone_url 如何工作

当极狐GitLab 实例在 Runner 无法使用的 URL 上可用，您可以配置 clone_url。

例如，防火墙可以阻止 Runner 访问 URL。 如果 Runner 可以访问 192.168.1.23 上的节点，将 clone_url 设置为 http://192.168.1.23。

如果设置了 clone_url，Runner 会以 http://gitlab-ci-token:s3cr3tt0k3n@192.168.1.23/namespace/project.git 的形式创建克隆 URL。

执行器

以下执行器都可用。

Shell

可用的 Shell 可以在不同平台运行。

当 shell 选项被设置为 bash 或 sh 时，Bash 的 ANSI-C quoting 用于 Shell 转义作业脚本。

使用符合POSIX 的 Shell

在极狐GitLab Runner 14.9 及更高版本中，启用功能标志，标志名为 FF_POSIXLY_CORRECT_ESCAPES，以使用符合 POSIX 的 Shell（类似dash）。 启用后，会使用符合 POSIX 的 Shell 转移机制-“双引号”。

[runners.docker] 部分

以下设置定义 Docker 容器参数。

Docker-in-Docker 作为一项服务，或在作业中配置的任何容器运行时，不继承这些参数。

[[runners.docker.services]] 部分

指定作业应该运行的额外服务。访问 Docker 镜像库 查看可用镜像列表。 服务在单独的容器中运行，并与作业相关联。

示例：

[runners.docker]
host = ""
hostname = ""
tls_cert_path = "/Users/ayufan/.boot2docker/certs"
image = "ruby:2.7"
memory = "128m"
memory_swap = "256m"
memory_reservation = "64m"
oom_kill_disable = false
cpuset_cpus = "0,1"
cpus = "2"
dns = ["8.8.8.8"]
dns_search = [""]
privileged = false
userns_mode = "host"
cap_add = ["NET_ADMIN"]
cap_drop = ["DAC_OVERRIDE"]
devices = ["/dev/net/tun"]
disable_cache = false
wait_for_services_timeout = 30
cache_dir = ""
volumes = ["/data", "/home/project/cache"]
extra_hosts = ["other-host:127.0.0.1"]
shm_size = 300000
volumes_from = ["storage_container:ro"]
links = ["mysql_container:mysql"]
allowed_images = ["ruby:*", "python:*", "php:*"]
allowed_services = ["postgres:9", "redis:*", "mysql:*"]
[runners.docker.ulimit]
"rtprio" = "99"
[[runners.docker.services]]
name = "registry.example.com/svc1"
alias = "svc1"
entrypoint = ["entrypoint.sh"]
command = ["executable","param1","param2"]
environment = ["ENV1=value1", "ENV2=value2"]
[[runners.docker.services]]
name = "redis:2.8"
alias = "cache"
[[runners.docker.services]]
name = "postgres:9"
alias = "postgres-db"
[runners.docker.sysctls]
"net.ipv4.ip_forward" = "1"

[runners.docker] 部分中的卷

查看 Docker 卷使用的完全指南。

以下例子展示如何指定 [runners.docker] 部分的卷。

示例 1：添加数据卷

数据卷是一个或多个绕过联合文件系统的容器中特殊指定的目录。数据卷不依赖容器的生命周期，持续存储数据。

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.7"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/volume/in/container"]

这个例子在 /path/to/volume/in/container 的容器中创建了一个新卷。

示例 2：以数据卷的形式挂载主机目录

当您想在容器外存储目录，您可以将目录从您的 Docker Daemon 的主机挂载到容器中：

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.7"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/bind/from/host:/path/to/bind/in/container:rw"]

这个例子使用了 /path/to/bind/in/container 中容器的 CI/CD 主机的 /path/to/bind/from/host。

使用私有容器镜像库

如果您想把私有镜像库作为您作业镜像的来源，您可以在名为 DOCKER_AUTH_CONFIG 的 CI/CD 变量设置授权配置。 您还可以在项目的 CI/CD 中将变量设置为 File 类型或在 config.toml 文件中设置变量。

使用带有 if-not-present 拉取政策的私有镜像库可能会引入安全影响。 如果想充分理解拉取政策如何工作，请阅读拉取政策文档。

详细示例请参见使用 Docker 镜像文档。

Runner 进行的步骤可以归纳为：

1. 从镜像名称中获取镜像库名称。
2. 如果值不为空，执行器为镜像库搜索认证配置。
3. 如果发现了与特定镜像库相匹配的认证，后续拉取会使用它。

现在 Runner 可以认证您的私有镜像库，访问如何配置 .gitlab-ci.yml 文件了解如何使用镜像库。

极狐GitLab 集成镜像库支持

极狐GitLab 发送作业数据时，也会发送它集成的镜像库的证书。 这些证书将自动添加到镜像库的认证参数列表中。

这步过后，对镜像库的认证会与添加 DOCKER_AUTH_CONFIG 参数的配置相似的方式继续。

在您的作业中，您可以使用您极狐GitLab 集成的镜像库中的任何镜像，即使镜像是私有的或受保护的。关于可以访问的镜像作业的信息，请参考 CI/CD 作业令牌文档。

Docker 认证解析的优先级别

如前所述，极狐GitLab Runner 可以使用以不同方式发送的证书，通过比较镜像库来授权 Docker。 如果想要找到合适的镜像库，可以考虑以下优先级别：

1. 使用 DOCKER_AUTH_CONFIG 配置的证书。
2. 使用 ~/.docker/config.json 或 ~/.dockercfg 文件（例如在主机上运行 docker login）在极狐GitLab Runner 主机上本地配置的证书。
3. 与作业负载一起默认发送的证书（例如之前描述的集成镜像库的证书）。

使用第一个发现的镜像库证书。例如，如果您使用 DOCKER_AUTH_CONFIG 变量为集成镜像库添加了证书，默认证书会被覆盖。

[runners.parallels] 部分

以下是 Parallels 的参数：

示例：

[runners.parallels]
  base_name = "my-parallels-image"
  template_name = ""
  disable_snapshots = false

[runners.virtualbox] 部分

以下是 VirtualBox 参数。这个执行器依赖可执行的 vboxmanage 去控制 VirtualBox 机器，所以您必须调整您在 Windows 主机上的 PATH 环境变量:PATH=%PATH%;C:\Program Files\Oracle\VirtualBox。

示例：

[runners.virtualbox]
base_name = "my-virtualbox-image"
base_snapshot = "my-image-snapshot"
disable_snapshots = false
start_type = "headless"

start_type 参数确定启动虚拟镜像时使用的图形前端。主机和访客组合支持的有效值为 headless（默认）、gui 或 separate。

覆盖基本虚拟机镜像

引入于极狐 GitLab Runner 14.2。

对于 Parallels 和 VirtualBox 执行器，您可以覆盖 base_name 指定的基本虚拟机的名称。 为此，您可以使用 .gitlab-ci.yml 文档中的镜像参数。

对于后向兼容，您无法默认覆盖这个值。仅允许 base_name 指定的镜像。

使用 .gitlab-ci.yml 镜像参数允许用户选择虚拟机镜像：

[runners.virtualbox]
  ...
  allowed_images = [".*"]

在这个例子中，可以使用任何现存的虚拟机镜像。

allowed_images 参数是正则表达式的列表。配置可以非常精确。 对于实例，如果您只想允许特定的虚拟机镜像，您可以使用正则表达式：

[runners.virtualbox]
  ...
  allowed_images = ["^allowed_vm[1-2]$"]

在这个例子中，仅允许了 allowed_vm1 和 allowed_vm2。其他尝试都会带来错误。

[runners.ssh] 部分

以下参数定义 SSH 连接：

示例：

[runners.ssh]
  host = "my-production-server"
  port = "22"
  user = "root"
  password = "production-server-password"
  identity_file = ""

[runners.machine] 部分

添加于极狐GitLab Runner v1.1.0。

以下参数定义基于 Docker Machine 的弹性伸缩功能。详情请参见 Runner 弹性伸缩文档。

[[runners.machine.autoscaling]] 部分

示例：

[runners.machine]
  IdleCount = 5
  IdleTime = 600
  MaxBuilds = 100
  MachineName = "auto-scale-%s"
  MachineDriver = "google" # Refer to Docker Machine docs on how to authenticate: https://docs.docker.com/machine/drivers/gce/#credentials
  MachineOptions = [
      # Additional machine options can be added using the Google Compute Engine driver.
      # If you experience problems with an unreachable host (ex. "Waiting for SSH"),
      # you should remove optional parameters to help with debugging.
      # https://docs.docker.com/machine/drivers/gce/
      "google-project=GOOGLE-PROJECT-ID",
      "google-zone=GOOGLE-ZONE", # e.g. 'us-central1-a', full list in https://cloud.google.com/compute/docs/regions-zones/
  ]
  [[runners.machine.autoscaling]]
    Periods = ["* * 9-17 * * mon-fri *"]
    IdleCount = 50
    IdleCountMin = 5
    IdleScaleFactor = 1.5 # Means that current number of Idle machines will be 1.5*in-use machines,
                          # no more than 50 (the value of IdleCount) and no less than 5 (the value of IdleCountMin) 
    IdleTime = 3600
    Timezone = "UTC"
  [[runners.machine.autoscaling]]
    Periods = ["* * * * * sat,sun *"]
    IdleCount = 5
    IdleTime = 60
    Timezone = "UTC"

Periods 语法

Periods 设置包括格式为 cron-style 的时长的字符串模式的阵列。行包括以下字段：

[second] [minute] [hour] [day of month] [month] [day of week] [year]

类似于标准的 cron 配置文件，字段可以包括单个值、范围、列表和星号。详情请参见语法详细描述。

[runners.instance] 部分（Alpha）

以下参数定义实力执行器的配置。

”

[runners.autoscaler] 部分

添加于极狐GitLab Runner v15.10.0。

以下参数配置新的和实验性的弹性伸缩器功能，只能与实例和 Docker Autoscaler 执行器一起使用。

[runners.autoscaler.plugin_config] 部分

这个哈希表被重新编码为 JSON 并直接传递给配置的插件。

fleeting 插件通常会附带有关支持配置的文档。

[runners.autoscaler.connector_config] 部分

fleeting 插件通常会附带有关支持的连接选项的文档。

插件自动更新连接器配置。您可以使用 [runners.autoscaler.connector_config] 以覆盖连接器配置的自动更新，或填写插件无法确定的空值。

[[runners.autoscaler.policy]] 部分

Note - 本上下文中的 idle_count 指的是作业数量，而不是传统弹性伸缩方法中弹性伸缩机器的数量。

设置 scale_factor 后，idle_count成为最小 idle 容量，scaler_factor_limit 成为最大 idle 容量。

Periods 语法

periods 设置包含一组 unix-cron 格式的字符串，用于表示策略启用的时间段。这个 cron 格式包含 5 个字段：

 ┌────────── minute (0 - 59)
 │ ┌──────── hour (0 - 23)
 │ │ ┌────── day of month (1 - 31)
 │ │ │ ┌──── month (1 - 12)
 │ │ │ │ ┌── day of week (1 - 7 or MON-SUN, 0 is an alias for Sunday)
 * * * * *

• 可以在两个数字之间使用 - 来指定范围。
• * 可用于表示该字段的整个有效值范围。
• / 后跟一个数字，或者可以在范围之后使用以跳过该范围内的数字。例如，小时字段的 0-12/2 将在 00:00 和 00:12 之间每 2 小时激活一次周期。
• , 可用于分隔字段的有效数字或范围列表。例如，1,2,6-9。

值得记住的是，这个 cron 作业代表一个时间范围。例如：

[runners.custom] 部分

以下参数定义自定义执行器的配置。

[runners.cache] 部分

引入于极狐GitLab Runner 1.1.0。

以下参数定义了分布式缓存功能。在 Runner 弹性伸缩文档中查看详情。

缓存机制使用预签名 URL 上传和下载缓存。极狐GitLab Runner 在它的实例上进行 URL 签名。 作业脚本（包括缓存上传/下载脚本）无论在本地或外部机器上执行都可以。例如 shell 或 docker 执行器在同一个运行极狐GitLab Runner 程序的机器上运行脚本。同时，virtualbox 或 docker+machine 连接到单独的虚拟机，以执行脚本。这个过程是为了安全考虑：将泄漏缓存适配器证书的可能性降到最低。

如果 S3 缓存适配器被配置为使用 IAM 实例配置文件，适配器会使用附着到极狐GitLab Runner 机器的配置文件。 如果被配置为使用 CredentialsFile ，则类似于 GCS 缓存适配器。文件需要在极狐GitLab Runner 机器上。

下表列出 config.toml、CLI 选项和 register 的 ENV 变量。

[runners.cache.s3] 部分

以下参数定义了缓存的 S3 存储。

在极狐GitLab Runner 11.2 及更低版本中，这些设置在全局 [runners.cache] 部分中。

示例：

[runners.cache]
  Type = "s3"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.s3]
    ServerAddress = "s3.amazonaws.com"
    AccessKey = "AWS_S3_ACCESS_KEY"
    SecretKey = "AWS_S3_SECRET_KEY"
    BucketName = "runners-cache"
    BucketLocation = "eu-west-1"
    Insecure = false
    ServerSideEncryption = "KMS"
    ServerSideEncryptionKeyID = "alias/my-key"

如果未指定 ServerAddress、 AccessKey 或 SecretKey 且未提供 AuthenticationType，S3 客户端会使用 gitlab-runner 实例可用的 IAM 实例配置文件。在弹性伸缩配置中，这不是执行作业的按需机器。 如果指定了 ServerAddress、 AccessKey 和 SecretKey，但未提供 AuthenticationType， access-key 会被用作认证类型。

当您使用 Helm Chart 安装极狐GitLab Runner，且在 values.yaml 文件中将rbac.create 设置为 true， 就会创建 ServiceAccount。ServiceAccount 的注释从 rbac.serviceAccountAnnotations 部分进行检索。

对于 Amazon EKS 上的 Runner，您可以指定分配给服务账户的 IAM 角色。 需要的特定注释是： eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<IAM_ROLE_NAME>。

这个角色的 IAM 政策需要有权限对特定桶做下列动作：

• “s3:PutObject”
• “s3:GetObjectVersion”
• “s3:GetObject”
• “s3:DeleteObject”

如果您使用 KMS 类型的 ServerSideEncryption，则此角色还必须有权对指定的 AWS KMS 密钥执行以下操作：

• “kms:Encrypt”
• “kms:Decrypt”
• “kms:ReEncrypt*”
• “kms:GenerateDataKey*”
• “kms:DescribeKey”

当前不支持 SSE-C 类型的 ServerSideEncryption。 SSE-C 要求除了预签名的 URL 之外，还为下载请求提供包含用户提供的密钥的 header。 这意味着将密钥材料传递给无法保证密钥安全的作业。这确实有可能泄漏解密密钥。

为 Runner 缓存在 S3 桶中使用 KMS 密钥加密

GenerateDataKey API 使用 KMS 对称密钥为客户端加密（(https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)）创建数据密钥。KMS 密钥配置需要：

分配到 rbac.serviceAccountName 中定义的 ServiceAccount 的角色的 IAM 政策需要能够为 KMS 密钥做下列动作：

• kms:GetPublicKey
• kms:Decrypt
• kms:Encrypt
• kms:DescribeKey
• kms:GenerateDataKey

为 Kubernetes ServiceAccount 资源启用 IAM 角色

如果想为服务账户使用 IAM 角色，您的集群中必须存在 IAM OIDC 提供商。IAM OIDC 提供商和您的集群关联后，您可以创建 IAM 角色，和 Runner 的服务账户相关联。

1. 在 Create Role 窗口，在 Select type of trusted entity 下选择 Web Identity。

2. 在角色的 Trusted Relationships tab 中：

   • Trusted entities 部分格式必须如下： arn:aws:iam::<ACCOUNT_ID>:oidc-provider/oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>。 可以在 EKS 集群的 Configuration 选项卡中找到 OIDC ID。

   • 如果 rbac.create 设置为 true，Condition 部分必须拥有 rbac.serviceAccountName 中定义的极狐GitLab Runner 服务账户或创建的默认服务账户：

[runners.cache.gcs] 部分

引入于极狐GitLab Runner 11.3.0。

以下参数定义了谷歌云存储（GCS）的原生支持。值的来源请查看谷歌云存储认证文档。

示例：

证书直接配置在 config.toml 文件中：

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    AccessID = "cache-access-account@test-project-123456.iam.gserviceaccount.com"
    PrivateKey = "-----BEGIN PRIVATE KEY-----\nXXXXXX\n-----END PRIVATE KEY-----\n"
    BucketName = "runners-cache"

从 GCP 下载的 JSON 文件中的证书：

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    CredentialsFile = "/etc/gitlab-runner/service-account.json"
    BucketName = "runners-cache"

GCP 中元数据服务器的应用程序默认证书 (ADC)：

当您通过 Google Cloud ADC 使用极狐GitLab Runner 时，您通常使用默认服务账户。您不需要为实例提供证书：

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    BucketName = "runners-cache"

如果您使用 ADC，请确保您使用的服务账户拥有 iam.serviceAccounts.signBlob 权限。通常，这是通过将服务账户令牌创建者角色授予服务账户来完成的。

[runners.cache.azure] 部分

引入于极狐GitLab Runner 13.4.0。

以下参数定义 Azure Blob Storage 的原生支持。详情请参见 Azure Blob Storage 文档。 S3 和 GCS 为许多对象使用词语 bucket，Azure 使用词语 container 表示许多 blobs。

示例：

[runners.cache]
  Type = "azure"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.azure]
    AccountName = "<AZURE STORAGE ACCOUNT NAME>"
    AccountKey = "<AZURE STORAGE ACCOUNT KEY>"
    ContainerName = "runners-cache"
    StorageDomain = "blob.core.windows.net"

[runners.kubernetes] 部分

引入于极狐GitLab Runner v1.6.0。

以下参数定义 Kubernetes 行为。 更多参数请参见 Kubernetes 执行器文档。

示例：

[runners.kubernetes]
  host = "https://45.67.34.123:4892"
  cert_file = "/etc/ssl/kubernetes/api.crt"
  key_file = "/etc/ssl/kubernetes/api.key"
  ca_file = "/etc/ssl/kubernetes/ca.crt"
  image = "golang:1.8"
  privileged = true
  allow_privilege_escalation = true
  image_pull_secrets = ["docker-registry-credentials", "optional-additional-credentials"]
  allowed_images = ["ruby:*", "python:*", "php:*"]
  allowed_services = ["postgres:9.4", "postgres:latest"]
  [runners.kubernetes.node_selector]
    gitlab = "true"

Helper 镜像

当您使用 docker、 docker+machine 或 kubernetes 执行器，极狐GitLab Runner 使用特定容器处理 Git、产物和缓存操作。这个容器从名为 helper image 的镜像创建。

Helper 镜像对 amd64、 arm、 arm64、 s390x 和 ppc64le 架构可用。它包含 gitlab-runner-helper 二进制，它是极狐GitLab Runner 二进制的特殊编译，仅包括可用命令的子集和 Git、Git LFS 和 SSL 证书存储。

当极狐GitLab Runner 从 DEB/RPM 安装包安装，支持的架构的镜像安装在主机上。 当 Runner 准备执行作业，如果 Docker Engine 上没有特定版本（基于 Runner 的 Git 修订）中的镜像，会自动加载。 docker 和 docker+machine 执行器都以这种方式工作。

对于 alpine 类型，安装包中只包括默认的 alpine 类型镜像。所有其他的类型都从镜像库下载。

kubernetes 执行器和极狐GitLab Runner 手动安装以不同形式工作。

• 对于手动安装，不包括 gitlab-runner-helper 二进制。
• 对于 kubernetes 执行器，Kubernetes API 不允许 gitlab-runner-helper 镜像从本地存档加载。

两种情况下，极狐GitLab Runner 都下载 Helper 镜像。 极狐GitLab Runner 修订和架构定义下载的标签。

Kubernetes on Arm 的 Helper 镜像配置

要在 arm64 Kubernetes 集群上使用 arm64 Helper 镜像，请在配置文件中设置以下值。

[runners.kubernetes]
        helper_image = "gitlab/gitlab-runner-helper:arm64-latest"

使用老版本 Alpine Linux 的 Runner 镜像

引入于极狐GitLab Runner 14.5。

镜像和很多版本的 Alpine Linux进行构建，所以您可以使用新版本的 Alpine，但是同时也使用老版本。 对于 Helper 镜像，更改 helper_image_flavor 或阅读 Helper 镜像部分。

对于极狐GitLab Runner 镜像，遵循同样的逻辑，alpine、alpine3.15、alpine3.16、alpine3.17、alpine3.18 或 alpine-latest 在版本前、镜像中用作前缀：

docker pull gitlab/gitlab-runner:alpine3.18-v16.1.0

Alpine pwsh 镜像

从 16.1 版本开始，所有 alpine helper 镜像都有一个 pwsh 变体。唯一的例外是 alpine-latest，因为极狐GitLab Runner helper 镜像所基于的 pwsh Docker 镜像不支持 alpine:latest。

示例：

docker pull gitlab/gitlab-runner-helper:alpine3.18-x86_64-v16.1.0-pwsh

Helper 镜像库

在 15.0 及更高版本中，Helper 镜像是从极狐GitLab 容器镜像库中拉取的。

在 15.0 及更早版本中，您可以将 Helper 镜像配置为使用来自 Docker Hub 的镜像。要从极狐GitLab 镜像库中检索基本的 gitlab-runner-helper 镜像，请使用 helper-image 值：registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v ${CI_RUNNER_VERSION}。

私有化部署实例还从 JihuLab.com 上的极狐GitLab 容器镜像库中拉取 Helper 镜像。要检查极狐GitLab 容器镜像库的状态，请参阅极狐GitLab 系统状态。

覆盖 Helper 镜像

在某些情况下，您可能需要覆盖 Helper 镜像。这样做有很多原因：

1. 为加速作业执行：在互联网连接缓慢的环境中，多次下载同样的镜像会增加执行作业的时间。从存储 gitlab/gitlab-runner-helper:XYZ 副本的本地镜像库下载 Helper 镜像会进行加速。

2. 安全考量：您可能不会想要下载之前未经过检查的外部依赖。 或许有业务规则指导如何仅使用在本地仓库检查和存储的依赖。

3. 无因特网访问构建环境：在一些情境下，作业会在专用封闭的网络下执行。 kubernetes 执行器并不适用，因为其中的镜像依然需要从 Kubernetes 集群可用的外部镜像库下载。

4. 额外的软件: 您可能想要向 Helper 镜像安装一些额外的软件， 例如 openssh，以支持子模块可以使用 git+ssh 而不是 git+http 进行访问。

在这些情况下，您可以使用 docker、 docker+machine 和 kubernetes 执行器可用的 helper_image 配置字段，配置自定义镜像。

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:tag"

Helper 镜像的版本应该与极狐GitLab Runner 的版本严格耦合。 提供这些镜像的一个主要原因是极狐GitLab Runner 正在使用的是 gitlab-runner-helper 二进制。这个二进制从部分极狐GitLab Runner 源进行编译。其使用预计在两个二进制中相同的内部 API。

极狐GitLab Runner 默认引用 gitlab/gitlab-runner-helper:XYZ 镜像，其中 XYZ 基于极狐GitLab Runner 架构和 Git 修订。

[[runners]]
(...)
executor = "docker"
[runners.docker]
(...)
helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

通过这个配置，极狐GitLab Runner 指示执行器使用基于编译数据的 x86_64-v${CI_RUNNER_VERSION} 版本中的镜像。将极狐GitLab Runner 更新到新版本后，它 试图下载合适的镜像。镜像应该在升级极狐GitLab Runner 之前被上传到镜像库，否则作业会提示 “No such image” 的错误消息并失败。

在极狐GitLab Runner 13.2 及更高版本中，Helper 镜像会被 $CI_RUNNER_VERSION 和 $CI_RUNNER_REVISION 打上标签。两个标签都有效且指向同一个镜像。

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

使用 PowerShell Core 时

包括 PowerShell Core 的 Linux Helper 镜像的额外版本，被打上 gitlab/gitlab-runner-helper:XYZ-pwsh 标签发布。

[runners.custom_build_dir] 部分

这个部分定义了自定义构建目录参数。

如果没有明确配置，这个功能对于 kubernetes、docker 和 docker+machine 执行器默认开启。对于所有其他执行器，默认禁用。

这个功能需要 GIT_CLONE_PATH 在 runners.builds_dir 定义的路径中。如果想使用 builds_dir，请使用 $CI_BUILDS_DIR 变量。

这个功能默认只对于 docker 和 kubernetes 执行器开启， 因为它们提供了一种将资源分开的好方法。 这个功能对于任何执行器都明确开启，但通过共享 builds_dir 且拥有 concurrent > 1 的执行器使用时需要注意。

示例：

[runners.custom_build_dir]
  enabled = true

默认构建目录

极狐GitLab Runner 将仓库克隆到构建目录基本路径下的一个路径中。 这个基本目录的默认位置取决于执行器。对于：

• Kubernetes、Docker 和 Docker Machine 执行器，它是容器内部的 /builds。
• Shell 执行器，它是 $PWD/builds。
• SSH、VirtualBox 和 Parallels 执行器，它是配置为处理目标机器 SSH 连接的用户的主目录中的 ~/builds。
• 自定义 执行器，不提供默认值，并且必须明确配置，否则会导致作业失败。

使用的构建目录可以由用户使用 builds_dir 设置进行明确定义。

极狐GitLab Runner 将构建目录用于它所运行的所有作业，但使用特定模式 {builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_ID/$NAMESPACE/$PROJECT_NAME 进行嵌套。 例如：/builds/2mn-ncv-/0/user/playground。

极狐GitLab Runner 不会阻止您在构建目录中进行存储。 例如，您可以将工具存储在可以在 CI 执行期间使用的 /builds/tools 中。 我们十分不鼓励这样的做法，您不应该在构建目录中存储任何东西。 极狐GitLab Runner 应该对其拥有完全控制权，并在这种情况下不做稳定性保证。 如果您有 CI 所需要的依赖项，我们建议您将其安装在其他地方。

[runners.referees] 部分

• 引入于极狐GitLab Runner 12.7。
• 需要极狐GitLab v12.6 及更高版本。

使用极狐GitLab Runner Referee 将额外作业监控数据传递到极狐GitLab。Referee 是 Runner Manager 中查询和收集作业相关的额外数据的 worker。 结果作为作业产物被上传到极狐GitLab。

使用 Metrics Runner Referee

运行作业的机器或容器展示 Prometheus指标，极狐GitLab Runner 可以在作业的整个持续时间内查询 Prometheus 服务器。收到指标后，它们作为可用于后续分析的作业产物被上传。

只有 docker-machine 执行器 支持 Referee。

为极狐GitLab Runner 配置 Metrics Runner Referee

[[runner]] 部分中，在您的 config.toml 文件中定义 [runner.referees] 和 [runner.referees.metrics] ，并添加以下字段：

以下是 node_exporter 指标的完整配置示例：

[[runners]]
  [runners.referees]
    [runners.referees.metrics]
      prometheus_address = "http://localhost:9090"
      query_interval = 10
      metric_queries = [
        "arp_entries:rate(node_arp_entries{{selector}}[{interval}])",
        "context_switches:rate(node_context_switches_total{{selector}}[{interval}])",
        "cpu_seconds:rate(node_cpu_seconds_total{{selector}}[{interval}])",
        "disk_read_bytes:rate(node_disk_read_bytes_total{{selector}}[{interval}])",
        "disk_written_bytes:rate(node_disk_written_bytes_total{{selector}}[{interval}])",
        "memory_bytes:rate(node_memory_MemTotal_bytes{{selector}}[{interval}])",
        "memory_swap_bytes:rate(node_memory_SwapTotal_bytes{{selector}}[{interval}])",
        "network_tcp_active_opens:rate(node_netstat_Tcp_ActiveOpens{{selector}}[{interval}])",
        "network_tcp_passive_opens:rate(node_netstat_Tcp_PassiveOpens{{selector}}[{interval}])",
        "network_receive_bytes:rate(node_network_receive_bytes_total{{selector}}[{interval}])",
        "network_receive_drops:rate(node_network_receive_drop_total{{selector}}[{interval}])",
        "network_receive_errors:rate(node_network_receive_errs_total{{selector}}[{interval}])",
        "network_receive_packets:rate(node_network_receive_packets_total{{selector}}[{interval}])",
        "network_transmit_bytes:rate(node_network_transmit_bytes_total{{selector}}[{interval}])",
        "network_transmit_drops:rate(node_network_transmit_drop_total{{selector}}[{interval}])",
        "network_transmit_errors:rate(node_network_transmit_errs_total{{selector}}[{interval}])",
        "network_transmit_packets:rate(node_network_transmit_packets_total{{selector}}[{interval}])"
      ]

指标查询的格式为 canonical_name:query_string。查询串支持两种在执行中替换的变量：

例如，使用 docker-machine 执行器的共享极狐GitLab Runner 环境拥有类似于 node=shared-runner-123 的 {selector}。