Advanced configuration
- Tier: 基础版, 专业版, 旗舰版
- Offering: JihuLab.com, 极狐GitLab私有化部署, 极狐GitLab Dedicated
要改变极狐GitLab Runner 和单个注册 runners 的行为,需要修改 config.toml 文件。
你可以在以下位置找到 config.toml 文件:
- 在 *nix 系统上,当极狐GitLab Runner 以 root 身份执行时,位于 /etc/gitlab-runner/。这个目录也是服务配置的路径。
- 在 *nix 系统上,当极狐GitLab Runner 以非 root 身份执行时,位于 ~/.gitlab-runner/。
- 在其他系统上,位于 ./。
极狐GitLab Runner 在更改大多数选项时不需要重启。这包括 [[runners]] 部分和全局部分的大多数参数,除了 listen_address。如果一个 runner 已经注册过,你不需要重新注册它。
极狐GitLab Runner 每 3 秒检查一次配置修改,并在必要时重新加载。极狐GitLab Runner 也会在接收到 SIGHUP 信号后重新加载配置。
配置验证
History
- Introduced in 极狐GitLab Runner 15.10
配置验证是一个检查 config.toml 文件结构的过程。配置验证器的输出仅提供 info 级别的信息。
配置验证过程仅用于信息目的。您可以使用输出来识别 runner 配置中的潜在问题。配置验证可能无法捕捉所有可能的问题,且没有消息并不保证 config.toml 文件是完美无缺的。
全局部分
这些设置是全局的。它们适用于所有 runners。
设置 | 描述 |
---|---|
concurrent | 限制所有注册 runners 可以同时运行的作业数量。每个 [[runners]] 部分可以定义其自己的限制,但此值为所有这些值的组合设置一个最大值。例如,值为 10 意味着不超过 10 个作业可以同时运行。0 是被禁止的。如果使用此值,runner 进程会因严重错误退出。查看此设置如何与 Docker Machine executor、Instance executor、Docker Autoscaler executor 和 runners.custom_build_dir 配置 一起工作。 |
log_level | 定义日志级别。选项有 debug、info、warn、error、fatal 和 panic。此设置的优先级低于命令行参数 --debug、-l 或 --log-level 设置的级别。 |
log_format | 指定日志格式。选项有 runner、text 和 json。此设置的优先级低于命令行参数 --log-format 设置的格式。默认值是 runner,其中包含用于着色的 ANSI 转义码。 |
check_interval | 定义 runner 检查新作业的间隔时间(以秒为单位)。默认值为 3。如果设置为 0 或更低,则使用默认值。 |
sentry_dsn | 启用将所有系统级错误跟踪到 Sentry。 |
connection_max_age | TLS 保持连接与极狐GitLab 服务器的最大持续时间(在重新连接之前)。默认值为 15m(15 分钟)。如果设置为 0 或更低,则连接尽可能长时间保持。 |
listen_address | 定义 Prometheus 指标 HTTP 服务器应监听的地址 (<host>:<port>)。 |
shutdown_timeout | 直到 强制关机操作 超时并退出进程的秒数。默认值为 30。如果设置为 0 或更低,则使用默认值。 |
这是一个配置示例:
toml1 2# 示例 `config.toml` 文件 3 4concurrent = 100 # 一个适用于此 `config.toml` 文件中定义的所有 runner 部分的作业并发性的全局设置 5log_level = "warning" 6log_format = "text" 7check_interval = 3 # 以秒为单位的值 8 9[[runners]] 10 name = "first" 11 url = "Your Gitlab instance URL (for example, `https://jihulab.com`)" 12 executor = "shell" 13 (...) 14 15[[runners]] 16 name = "second" 17 url = "Your Gitlab instance URL (for example, `https://jihulab.com`)" 18 executor = "docker" 19 (...) 20 21 [[runners]] 22 name = "third" 23 url = "Your Gitlab instance URL (for example, `https://jihulab.com`)" 24 executor = "docker-autoscaler" 25 (...) 26
log_format 示例(截断)
runner
shell1Runtime platform arch=amd64 os=darwin pid=37300 revision=HEAD version=development version 2Starting multi-runner from /etc/gitlab-runner/config.toml... builds=0 3WARNING: Running in user-mode. 4WARNING: Use sudo for system-mode: 5WARNING: $ sudo gitlab-runner... 6 7Configuration loaded builds=0 8listen_address not defined, metrics & debug endpoints disabled builds=0 9[session_server].listen_address not defined, session endpoints disabled builds=0
text
shell1INFO[0000] Runtime platform arch=amd64 os=darwin pid=37773 revision=HEAD version="development version" 2INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml... builds=0 3WARN[0000] Running in user-mode. 4WARN[0000] Use sudo for system-mode: 5WARN[0000] $ sudo gitlab-runner... 6INFO[0000] 7INFO[0000] Configuration loaded builds=0 8INFO[0000] listen_address not defined, metrics & debug endpoints disabled builds=0 9INFO[0000] [session_server].listen_address not defined, session endpoints disabled builds=0
json
shell1{"arch":"amd64","level":"info","msg":"Runtime platform","os":"darwin","pid":38229,"revision":"HEAD","time":"2020-06-05T15:57:35+02:00","version":"development version"} 2{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2020-06-05T15:57:35+02:00"} 3{"level":"warning","msg":"Running in user-mode.","time":"2020-06-05T15:57:35+02:00"} 4{"level":"warning","msg":"Use sudo for system-mode:","time":"2020-06-05T15:57:35+02:00"} 5{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2020-06-05T15:57:35+02:00"} 6{"level":"info","msg":"","time":"2020-06-05T15:57:35+02:00"} 7{"builds":0,"level":"info","msg":"Configuration loaded","time":"2020-06-05T15:57:35+02:00"} 8{"builds":0,"level":"info","msg":"listen_address not defined, metrics \u0026 debug endpoints disabled","time":"2020-06-05T15:57:35+02:00"} 9{"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 Runner 包含一个不断调度作业请求到配置了极狐GitLab Runner 的极狐GitLab 实例的循环。
以下示例中,check_interval 为 10 秒,并有两个 [[runners]] 部分(runner-1 和 runner-2)。极狐GitLab Runner 每 10 秒发送一个请求,并休眠五秒:
- 获取 check_interval 值(10s)。
- 获取 runners 列表(runner-1,runner-2)。
- 计算休眠间隔(10s / 2 = 5s)。
- 开始一个无限循环:
- 请求 runner-1 的作业。
- 休眠 5s。
- 请求 runner-2 的作业。
- 休眠 5s。
- 重复。
这是一个 check_interval 配置示例:
toml1# 示例 `config.toml` 文件 2 3concurrent = 100 # 一个适用于此 `config.toml` 文件中定义的所有 runner 部分的作业并发性的全局设置 4log_level = "warning" 5log_format = "json" 6check_interval = 10 # 以秒为单位的值 7 8[[runners]] 9 name = "runner-1" 10 url = "Your Gitlab instance URL (for example, `https://jihulab.com`)" 11 executor = "shell" 12 (...) 13 14[[runners]] 15 name = "runner-2" 16 url = "Your Gitlab instance URL (for example, `https://jihulab.com`)" 17 executor = "docker" 18 (...)
在此示例中,runner 进程每五秒发出一次作业请求。如果 runner-1 和 runner-2 连接到同一个极狐GitLab 实例,则该极狐GitLab 实例也每五秒收到来自此 runner 的新请求。
在 runner-1 的第一次和第二次请求之间发生两个休眠期。每个周期持续五秒,因此大约 10 秒之间的 runner-1 后续请求。对于 runner-2 也是如此。
如果定义更多 runners,则休眠间隔会更小。然而,在所有其他 runners 的请求及其休眠期被调用之后,runner 的请求才会重复。
[session_server] 部分
要与作业交互,请在根级别([[runners]] 部分之外)指定 [session_server] 部分。为所有 runners 配置此部分,而不是为每个单独的 runner 配置。
toml1# 配置了 session server 的示例 `config.toml` 文件 2 3concurrent = 100 # 一个适用于此 `config.toml` 文件中定义的所有 runner 部分的作业并发性的全局设置 4log_level = "warning" 5log_format = "runner" 6check_interval = 3 # 以秒为单位的值 7 8[session_server] 9 listen_address = "[::]:8093" # 监听端口 `8093` 上所有可用接口 10 advertise_address = "runner-host-name.tld:8093" 11 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 证书用于安全连接。
- 确保极狐GitLab 可以连接到 listen_address 或 advertise_address 中定义的 IP 地址和端口。
- 确保 advertise_address 是一个公共 IP 地址,除非您已启用应用程序设置 allow_local_requests_from_web_hooks_and_services。
设置 | 描述 |
---|---|
listen_address | session server 的内部 URL。 |
advertise_address | 访问 session server 的 URL。极狐GitLab Runner 将其暴露给极狐GitLab。如果未定义,则使用 listen_address。 |
session_timeout | 作业完成后 session 可以保持活动状态的秒数。超时阻止作业完成。默认值为 1800(30 分钟)。 |
要禁用 session server 和终端支持,请删除 [session_server] 部分。
当您的 runner 实例已经在运行时,您可能需要执行 gitlab-runner restart 以使 [session_server] 部分中的更改生效。
如果您使用的是极狐GitLab Runner Docker 镜像,您必须通过在 docker run 命令 中添加 -p 8093:8093 来暴露端口 8093。
[[runners]] 部分
每个 [[runners]] 部分定义一个 runner。
设置 | 描述 |
---|---|
name | runner 的描述。仅供参考。 |
url | 极狐GitLab 实例 URL。 |
token | runner 的身份验证令牌,在 runner 注册期间获取。与注册令牌不同。 |
tls-ca-file | 使用 HTTPS 时,包含用于验证对等方的证书的文件。参见 自签名证书或自定义认证机构文档。 |
tls-cert-file | 使用 HTTPS 时,包含用于与对等方进行身份验证的证书的文件。 |
tls-key-file | 使用 HTTPS 时,包含用于与对等方进行身份验证的私钥的文件。 |
limit | 限制此注册 runner 可以同时处理的作业数量。0(默认)表示不限制。查看此设置如何与 Docker Machine、Instance 和 Docker Autoscaler 执行器一起工作。 |
executor | runner 用来运行 CI/CD 作业的主机操作系统上的环境或命令处理器。有关更多信息,请参见 executors。 |
shell | 用于生成脚本的 shell 名称。默认值是 平台相关 的。 |
builds_dir | 在所选执行器的上下文中存储构建的目录的绝对路径。例如,本地、Docker 或 SSH。 |
cache_dir | 在所选执行器的上下文中存储构建缓存的目录的绝对路径。例如,本地、Docker 或 SSH。如果使用 docker 执行器,则此目录需要包含在其 volumes 参数中。 |
environment | 追加或覆盖环境变量。 |
request_concurrency | 限制从极狐GitLab 获取新作业的并发请求数量。默认值为 1。 |
output_limit | 构建日志的最大大小(以千字节为单位)。默认值为 4096(4 MB)。 |
pre_get_sources_script | 在更新 Git 存储库和更新子模块之前,在 runner 上执行的命令。用于首先调整 Git 客户端配置,例如。要插入多个命令,请使用(三引号)多行字符串或 \n 字符。 |
post_get_sources_script | 在更新 Git 存储库和更新子模块之后,在 runner 上执行的命令。要插入多个命令,请使用(三引号)多行字符串或 \n 字符。 |
pre_build_script | 在执行作业之前,在 runner 上执行的命令。要插入多个命令,请使用(三引号)多行字符串或 \n 字符。 |
post_build_script | 在执行完作业后但在执行 after_script 之前,在 runner 上执行的命令。要插入多个命令,请使用(三引号)多行字符串或 \n 字符。 |
clone_url | 覆盖极狐GitLab 实例的 URL。仅在 runner 无法连接到极狐GitLab URL 时使用。 |
debug_trace_disabled | 禁用 debug tracing。如果设置为 true,即使 CI_DEBUG_TRACE 设置为 true,调试日志(跟踪)仍然禁用。 |
clean_git_config | 清理 Git 配置。有关更多信息,请参见 清理 Git 配置。 |
referees | 传递其结果作为作业产物给极狐GitLab 的额外作业监控 worker。 |
unhealthy_requests_limit | 在 runner worker 被禁用之前,对新作业请求的 unhealthy 响应次数。 |
unhealthy_interval | runner worker 在超过 unhealthy 请求限制后被禁用的持续时间。支持诸如 '3600 s'、'1 h 30 min' 等语法。 |
job_status_final_update_retry_limit | 极狐GitLab Runner 在将最终作业状态推送到极狐GitLab 实例时可以重试的最大次数。 |
示例:
toml1[[runners]] 2 name = "ruby-3.3-docker" 3 url = "https://CI/" 4 token = "TOKEN" 5 limit = 0 6 executor = "docker" 7 builds_dir = "" 8 shell = "" 9 environment = ["ENV=value", "LC_ALL=en_US.UTF-8"] 10 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 构造一个 clone_url 形式的克隆 URL,例如 http://gitlab-ci-token:s3cr3tt0k3n@192.168.1.23/namespace/project.git。
clone_url 不影响 Git LFS 端点或产物上传或下载。
修改 Git LFS 端点
要修改 Git LFS 端点,请在以下文件之一中设置 pre_get_sources_script:
-
config.toml:
tomlpre_get_sources_script = "mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template; git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://<alternative-endpoint>"
-
.gitlab-ci.yml:
yamldefault: hooks: pre_get_sources_script: - mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template - git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://localhost
unhealthy_requests_limit 和 unhealthy_interval 的工作原理
当极狐GitLab 实例长时间不可用时(例如,在版本升级期间),其 runners 变为闲置状态。在极狐GitLab 实例再次可用后,runners 在 30-60 分钟内不会恢复作业处理。
要增加或减少 runners 闲置的时间,请更改 unhealthy_interval 设置。
要更改 runner 连接到极狐GitLab 服务器的尝试次数并在接收到 unhealthy 请求后进入闲置状态,请更改 unhealthy_requests_limit 设置。有关更多信息,请参见 check_interval 的工作原理。
执行器
以下是可用的执行器。
执行器 | 所需配置 | 作业运行位置 |
---|---|---|
shell | 本地 shell。默认执行器。 | |
docker | [runners.docker] 和 Docker Engine | 一个 Docker 容器。 |
docker-windows | [runners.docker] 和 Docker Engine | 一个 Windows Docker 容器。 |
ssh | [runners.ssh] | SSH,远程。 |
parallels | [runners.parallels] 和 [runners.ssh] | Parallels VM,但通过 SSH 连接。 |
virtualbox | [runners.virtualbox] 和 [runners.ssh] | VirtualBox VM,但通过 SSH 连接。 |
docker+machine | [runners.docker] 和 [runners.machine] | 类似于 docker,但使用 自动扩展 Docker machines。 |
kubernetes | [runners.kubernetes] | Kubernetes pods。 |
docker-autoscaler | [docker-autoscaler] 和 [runners.autoscaler] | 类似于 docker,但使用自动扩展实例在容器中运行 CI/CD 作业。 |
instance | [docker-autoscaler] 和 [runners.autoscaler] | 类似于 shell,但使用自动扩展实例直接在主机实例上运行 CI/CD 作业。 |
Shells
当配置为使用 shell 执行器时,CI/CD 作业在主机机器上本地运行。支持的操作系统 shells 如下:
Shell | 描述 |
---|---|
bash | 生成 Bash(Bourne-shell)脚本。所有命令在 Bash 上下文中执行。默认适用于所有 Unix 系统。 |
sh | 生成 Sh(Bourne-shell)脚本。所有命令在 Sh 上下文中执行。bash 的回退选项适用于所有 Unix 系统。 |
powershell | 生成 PowerShell 脚本。所有命令在 PowerShell Desktop 上下文中执行。在极狐GitLab Runner 12.0-13.12 中,这是 Windows 的默认选项。 |
pwsh | 生成 PowerShell 脚本。所有命令在 PowerShell Core 上下文中执行。在极狐GitLab Runner 14.0 及更高版本中,这是 Windows 的默认选项。 |
当 shell 选项设置为 bash 或 sh 时,Bash 的 ANSI-C quoting 用于 shell 转义作业脚本。
使用符合 POSIX 的 shell
在极狐GitLab Runner 14.9 及更高版本中,启用功能标志 FF_POSIXLY_CORRECT_ESCAPES 以使用符合 POSIX 的 shell(如 dash)。启用后,将使用 "Double Quotes",这是一种符合 POSIX 的 shell 转义机制。
[runners.docker] 部分
以下设置定义了 Docker 容器参数。这些设置在 runner 配置为使用 Docker 执行器时适用。
Docker-in-Docker 作为服务,或任何在作业中配置的容器运行时,不会继承这些参数。
参数 | 描述 | 示例 |
---|---|---|
allowed_images | 可以在 .gitlab-ci.yml 文件中指定的镜像的通配符列表。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 Docker 或 Kubernetes 执行器一起使用。 | ["ruby:*", "python:*", "php:*"] |
allowed_privileged_images | allowed_images 的通配符子集,当 privileged 启用时以特权模式运行。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 Docker 执行器一起使用。 | |
allowed_pull_policies | 可以在 .gitlab-ci.yml 文件或 config.toml 文件中指定的拉取策略列表。如果未指定,则仅允许在 pull-policy 中指定的拉取策略。与 Docker 执行器一起使用。 | |
allowed_services | 可以在 .gitlab-ci.yml 文件中指定的服务的通配符列表。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 Docker 或 Kubernetes 执行器一起使用。 | ["postgres:9", "redis:*", "mysql:*"] |
allowed_privileged_services | allowed_services 的通配符子集,当 privileged 或 services_privileged 启用时允许以特权模式运行。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 Docker 执行器一起使用。 | |
cache_dir | Docker 缓存应存储的目录。此路径可以是相对于当前工作目录的绝对路径。有关详细信息,请参见 disable_cache。 | |
cap_add | 向容器添加其他 Linux 功能。 | ["NET_ADMIN"] |
cap_drop | 从容器中删除其他 Linux 功能。 | ["DAC_OVERRIDE"] |
cpuset_cpus | 控制组的 CpusetCpus。一个字符串。 | "0,1" |
cpuset_mems | 控制组的 CpusetMems。一个字符串。 | "0,1" |
cpu_shares | 用于设置相对 CPU 使用率的 CPU 份额数。默认值为 1024。 | |
cpus | CPU 数量(适用于 Docker 1.13 或更高版本)。一个字符串。 | "2" |
devices | 与容器共享的其他主机设备。 | ["/dev/net/tun"] |
device_cgroup_rules | 自定义设备 cgroup 规则(适用于 Docker 1.28 或更高版本)。 | |
disable_cache | Docker 执行器有两个缓存级别:一个全局缓存(如任何其他执行器)和一个基于 Docker 卷的本地缓存。此配置标志仅对本地缓存起作用,禁用自动创建的(未映射到主机目录)缓存卷的使用。换句话说,它只会阻止创建一个保存构建临时文件的容器,但不会禁用缓存如果 runner 配置为分布式缓存模式。 | |
disable_entrypoint_overwrite | 禁用镜像入口点覆盖。 | |
dns | 容器使用的 DNS 服务器列表。 | ["8.8.8.8"] |
dns_search | DNS 搜索域的列表。 | |
extra_hosts | 应在容器环境中定义的主机。 | ["other-host:127.0.0.1"] |
gpus | Docker 容器的 GPU 设备。使用与 docker CLI 相同的格式。查看 Docker 文档 了解详细信息。需要 配置以启用 GPU。 | |
group_add | 为容器进程运行添加其他组。 | ["docker"] |
helper_image | (高级)默认的辅助镜像 用于克隆存储库和上传产物。 | |
helper_image_flavor | 设置辅助镜像风格(alpine、alpine3.18、alpine3.19、alpine3.21、alpine-latest、ubi-fips 或 ubuntu)。默认为 alpine。alpine 风格使用与 alpine3.21 相同的版本。 | |
helper_image_autoset_arch_and_os | 使用底层操作系统设置辅助镜像的架构和操作系统。 | |
host | 自定义 Docker 端点。默认是 DOCKER_HOST 环境或 unix:///var/run/docker.sock。 | |
hostname | Docker 容器的自定义主机名。 | |
image | 用于运行作业的镜像。 | "ruby:3.3" |
links | 应与运行作业的容器链接的容器。 | ["mysql_container:mysql"] |
memory | 内存限制。一个字符串。 | "128m" |
memory_swap | 总内存限制。一个字符串。 | "256m" |
memory_reservation | 内存软限制。一个字符串。 | "64m" |
network_mode | 将容器添加到自定义网络中。 | |
mac_address | 容器 MAC 地址 | 92:d0:c6:0a:29:33 |
oom_kill_disable | 如果发生内存不足(OOM)错误,请勿终止容器中的进程。 | |
oom_score_adjust | OOM 分数调整。正数意味着更早终止进程。 | |
privileged | 使容器以特权模式运行。不安全。 | false |
services_privileged | 允许服务以特权模式运行。如果未设置(默认),则使用 privileged 值。与 Docker 执行器一起使用。不安全。 | |
pull_policy | 镜像拉取策略:never、if-not-present 或 always(默认)。查看 拉取策略文档 了解详细信息。您还可以添加多个拉取策略、重试失败的拉取 或限制拉取策略。 | |
runtime | Docker 容器的运行时。 | |
isolation | 容器隔离技术(default、hyperv 和 process)。仅适用于 Windows。 | |
security_opt | 安全选项(docker run 中的 --security-opt)。采用 : 分隔的键/值列表。 | |
shm_size | 镜像的共享内存大小(以字节为单位)。 | 300000 |
sysctls | sysctl 选项。 | |
tls_cert_path | 用于存储和使用 ca.pem、cert.pem 或 key.pem 以与 Docker 建立安全 TLS 连接的目录。与 boot2docker 一起使用此设置。 | 在 macOS 上 /Users/<username>/.boot2docker/certs。 |
tls_verify | 启用或禁用对 Docker 守护进程连接的 TLS 验证。默认禁用。默认情况下,极狐GitLab Runner 通过 SSH 连接到 Docker Unix 套接字。Unix 套接字不支持 RTLS,并通过 SSH 通信以提供加密和身份验证。通常不需要启用 tls_verify,并且需要额外的配置。要启用 tls_verify,守护进程必须监听端口(而不是默认的 Unix 套接字),并且极狐GitLab Runner Docker 主机必须使用守护进程监听的地址。 | |
user | 在容器中以指定用户身份运行所有命令。 | |
userns_mode | 启用用户命名空间重新映射选项时,容器和 Docker 服务的用户命名空间模式。适用于 Docker 1.10 或更高版本。有关详细信息,请参阅 Docker 文档。 | |
ulimit | 传递给容器的 Ulimit 值。使用与 Docker --ulimit 标志相同的语法。 | |
volumes | 应挂载的其他卷。与 Docker -v 标志相同的语法。 | ["/data", "/home/project/cache"] |
volumes_from | 以 <container name>[:<access_level>] 形式继承自其他容器的卷列表。访问级别默认为读写,但可以手动设置为 ro(只读)或 rw(读写)。 | ["storage_container:ro"] |
volume_driver | 用于容器的卷驱动程序。 | |
wait_for_services_timeout | 等待 Docker 服务的时间。设置为 -1 以禁用。默认值为 30。 | 30 |
container_labels | 要添加到 runner 创建的每个容器的标签集。标签值可以包含用于扩展的环境变量。 | |
services_limit | 设置每个作业允许的最大服务数。-1(默认)表示没有限制。 | |
service_cpuset_cpus | 包含要用于服务的 cgroups CpusetCpus 的字符串值。 | |
service_cpu_shares | 用于设置服务相对 CPU 使用率的 CPU 份额数(默认: 1024)。 | |
service_cpus | 服务的 CPU 数量的字符串值。适用于 Docker 1.13 或更高版本。 | |
service_gpus | Docker 容器的 GPU 设备。使用与 docker CLI 相同的格式。查看 Docker 文档 了解详细信息。需要 配置以启用 GPU。 | |
service_memory | 服务的内存限制的字符串值。 | |
service_memory_swap | 服务的总内存限制的字符串值。 | |
service_memory_reservation | 服务的内存软限制的字符串值。 |
[[runners.docker.services]] 部分
指定要与作业一起运行的其他服务。有关可用镜像的列表,请参阅 Docker Registry。 每个服务都在一个单独的容器中运行,并与作业链接。
参数 | 描述 | 示例 |
---|---|---|
name | 要作为服务运行的镜像名称。 | "registry.example.com/svc1" |
alias | 可以用于访问服务的附加别名名称。 | "svc1" |
entrypoint | 应作为容器入口点执行的命令或脚本。语法类似于 Dockerfile ENTRYPOINT 指令,其中每个 shell 标记是数组中的一个单独字符串。引入于 极狐GitLab Runner 13.6。 | ["entrypoint.sh"] |
command | 应用作容器命令的命令或脚本。语法类似于 Dockerfile CMD 指令,其中每个 shell 标记是数组中的一个单独字符串。引入于 极狐GitLab Runner 13.6。 | ["executable","param1","param2"] |
environment | 为服务容器追加或覆盖环境变量。 | ["ENV1=value1", "ENV2=value2"] |
示例:
toml1[runners.docker] 2 host = "" 3 hostname = "" 4 tls_cert_path = "/Users/ayufan/.boot2docker/certs" 5 image = "ruby:3.3" 6 memory = "128m" 7 memory_swap = "256m" 8 memory_reservation = "64m" 9 oom_kill_disable = false 10 cpuset_cpus = "0,1" 11 cpuset_mems = "0,1" 12 cpus = "2" 13 dns = ["8.8.8.8"] 14 dns_search = [""] 15 service_memory = "128m" 16 service_memory_swap = "256m" 17 service_memory_reservation = "64m" 18 service_cpuset_cpus = "0,1" 19 service_cpus = "2" 20 services_limit = 5 21 privileged = false 22 group_add = ["docker"] 23 cap_add = ["NET_ADMIN"] 24 cap_drop = ["DAC_OVERRIDE"] 25 devices = ["/dev/net/tun"] 26 disable_cache = false 27 wait_for_services_timeout = 30 28 cache_dir = "" 29 volumes = ["/data", "/home/project/cache"] 30 extra_hosts = ["other-host:127.0.0.1"] 31 shm_size = 300000 32 volumes_from = ["storage_container:ro"] 33 links = ["mysql_container:mysql"] 34 allowed_images = ["ruby:*", "python:*", "php:*"] 35 allowed_services = ["postgres:9", "redis:*", "mysql:*"] 36 [runners.docker.ulimit] 37 "rtprio" = "99" 38 [[runners.docker.services]] 39 name = "registry.example.com/svc1" 40 alias = "svc1" 41 entrypoint = ["entrypoint.sh"] 42 command = ["executable","param1","param2"] 43 environment = ["ENV1=value1", "ENV2=value2"] 44 [[runners.docker.services]] 45 name = "redis:2.8" 46 alias = "cache" 47 [[runners.docker.services]] 48 name = "postgres:9" 49 alias = "postgres-db" 50 [runners.docker.sysctls] 51 "net.ipv4.ip_forward" = "1"
[runners.docker] 部分中的卷
有关卷的更多信息,请参阅 Docker 文档。
以下示例展示了如何在 [runners.docker] 部分中指定卷。
示例 1:添加数据卷
数据卷是一个或多个容器中绕过联合文件系统的专门指定目录。数据卷旨在独立于容器的生命周期持久化数据。
toml1[runners.docker] 2 host = "" 3 hostname = "" 4 tls_cert_path = "/Users/ayufan/.boot2docker/certs" 5 image = "ruby:3.3" 6 privileged = false 7 disable_cache = true 8 volumes = ["/path/to/volume/in/container"]
此示例在容器中 /path/to/volume/in/container 处创建一个新卷。
示例 2:将主机目录挂载为数据卷
当您希望将目录存储在容器之外时,可以将 Docker 守护进程的主机中的目录挂载到容器中:
toml1[runners.docker] 2 host = "" 3 hostname = "" 4 tls_cert_path = "/Users/ayufan/.boot2docker/certs" 5 image = "ruby:3.3" 6 privileged = false 7 disable_cache = true 8 volumes = ["/path/to/bind/from/host:/path/to/bind/in/container:rw"]
此示例在容器中的 /path/to/bind/in/container 使用 CI/CD 主机的 /path/to/bind/from/host。
极狐GitLab Runner 11.11 及更高版本 挂载主机目录 用于定义的服务 以及。
使用私有容器注册表
要将私有注册表用作作业的镜像源,请使用 CI/CD 变量 DOCKER_AUTH_CONFIG 配置授权。您可以在以下之一中设置变量:
- 项目的 CI/CD 设置作为 file 类型
- config.toml 文件
使用 if-not-present 拉取策略的私有注册表可能会引入 安全隐患。 有关拉取策略如何工作的更多信息,请参阅 配置 runner 拉取镜像的方式。
有关使用私有容器注册表的更多信息,请参阅:
runner 执行的步骤可以总结为:
- 从镜像名称中找到注册表名称。
- 如果值不为空,执行器会搜索此注册表的身份验证配置。
- 最后,如果找到了与指定注册表相对应的身份验证,则后续拉取将使用它。
极狐GitLab 集成注册表的支持
极狐GitLab 发送凭据用于其集成注册表与作业的数据一起。这些凭据会自动添加到注册表的授权参数列表中。
在此步骤之后,对注册表的授权过程类似于通过 DOCKER_AUTH_CONFIG 变量添加的配置。
在你的作业中,你可以使用任何来自极狐GitLab 集成注册表的镜像,即使镜像是私有的或受保护的。有关作业可以访问的镜像的信息,请阅读CI/CD 作业令牌文档文档。
Docker 授权解析的优先级
如前所述,极狐GitLab Runner 可以通过使用不同方式发送的凭据来授权 Docker 访问注册表。为了找到合适的注册表,考虑以下优先级:
- 使用 DOCKER_AUTH_CONFIG 配置的凭据。
- 在极狐GitLab Runner 主机上本地配置的凭据,使用 ~/.docker/config.json 或 ~/.dockercfg 文件(例如,在主机上运行 docker login)。
- 默认随作业负载发送的凭据(例如,前面描述的集成注册表的凭据)。
找到的第一个注册表凭据将被使用。例如,如果你通过 DOCKER_AUTH_CONFIG 变量为集成注册表添加了凭据,那么默认凭据将被覆盖。
runners.parallels 部分
以下参数适用于 Parallels。
参数 | 描述 |
---|---|
base_name | 被克隆的 Parallels 虚拟机的名称。 |
template_name | Parallels 虚拟机链接模板的自定义名称。可选。 |
disable_snapshots | 如果禁用,当作业完成时,虚拟机将被销毁。 |
allowed_images | 允许的 image/base_name 值的列表,表示为正则表达式。有关更多详细信息,请参阅覆盖基础虚拟机镜像部分。 |
示例:
toml[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。
参数 | 说明 |
---|---|
base_name | 被克隆的 VirtualBox 虚拟机的名称。 |
base_snapshot | 要从中创建链接克隆的虚拟机的特定快照的名称或 UUID。如果此值为空或省略,则使用当前快照。如果不存在当前快照,则会创建一个快照,除非 disable_snapshots 为 true,在这种情况下,将进行基础虚拟机的完整克隆。 |
base_folder | 保存新虚拟机的文件夹。如果此值为空或省略,则使用默认虚拟机文件夹。 |
disable_snapshots | 如果禁用,当作业完成时,虚拟机将被销毁。 |
allowed_images | 允许的 image/base_name 值的列表,表示为正则表达式。有关更多详细信息,请参阅覆盖基础虚拟机镜像部分。 |
start_type | 启动虚拟机时的图形前端类型。 |
示例:
toml[runners.virtualbox] base_name = "my-virtualbox-image" base_snapshot = "my-image-snapshot" disable_snapshots = false start_type = "headless"
start_type 参数决定了启动虚拟镜像时使用的图形前端。有效值为 headless(默认)、gui 或 separate,具体取决于主机和客户机组合的支持。
覆盖基础虚拟机镜像
History
- 在极狐GitLab Runner 14.2 中引入。
对于 Parallels 和 VirtualBox 执行器,你可以覆盖由 base_name 指定的基础虚拟机名称。为此,请在 .gitlab-ci.yml 文件中使用 image 参数。
为了向后兼容,默认情况下你不能覆盖此值。仅允许 base_name 指定的镜像。
为了允许用户通过 .gitlab-ci.yml 使用 image 参数选择虚拟机镜像:
toml[runners.virtualbox] ... allowed_images = [".*"]
在此示例中,可以使用任何现有的虚拟机镜像。
allowed_images 参数是正则表达式的列表。配置可以根据需要精确。例如,如果你只想允许某些虚拟机镜像,可以使用如下正则表达式:
toml[runners.virtualbox] ... allowed_images = ["^allowed_vm[1-2]$"]
在此示例中,只允许 allowed_vm1 和 allowed_vm2。任何其他尝试都会导致错误。
runners.ssh 部分
以下参数定义 SSH 连接。
参数 | 描述 |
---|---|
host | 连接到的主机。 |
port | 端口。默认是 22。 |
user | 用户名。 |
password | 密码。 |
identity_file | SSH 私钥的文件路径(id_rsa、id_dsa 或 id_edcsa)。文件必须以未加密的形式存储。 |
disable_strict_host_key_checking | 此值确定 runner 是否应该使用严格的主机密钥检查。默认是 true。在极狐GitLab 15.0 中,默认值或未指定的值为 false。 |
示例:
toml1[runners.ssh] 2 host = "my-production-server" 3 port = "22" 4 user = "root" 5 password = "production-server-password" 6 identity_file = ""
runners.machine 部分
以下参数定义基于 Docker Machine 的自动缩放功能。有关更多信息,请参阅 Docker Machine 执行器自动缩放配置。
参数 | 描述 |
---|---|
MaxGrowthRate | 可以并行添加到 runner 的最大机器数量。默认是 0(无限制)。 |
IdleCount | 需要创建并处于 Idle 状态的机器数量。 |
IdleScaleFactor | 处于 Idle 状态的机器数量作为使用中机器数量的一个因子。必须是浮点数格式。有关更多详细信息,请参阅自动缩放文档。默认是 0.0。 |
IdleCountMin | 当使用 IdleScaleFactor 时,需创建并处于 Idle 状态的机器的最小数量。默认是 1。 |
IdleTime | 机器处于 Idle 状态的时间(以秒为单位)然后被移除。 |
[[runners.machine.autoscaling]] | 多个部分,每个部分包含自动缩放配置的覆盖。选择与当前时间匹配的表达式的最后一个部分。 |
OffPeakPeriods | 已弃用:调度程序处于 OffPeak 模式的时间段。cron 风格模式的数组(在下方描述)。 |
OffPeakTimezone | 已弃用:OffPeakPeriods 中给出的时间的时区。类似 Europe/Berlin 的时区字符串。如果省略或为空,默认使用主机的区域系统设置。极狐GitLab Runner 尝试在 ZONEINFO 环境变量指向的目录或未压缩的 zip 文件中查找时区数据库,然后在 Unix 系统的已知安装位置查找,最后在 $GOROOT/lib/time/zoneinfo.zip 中查找。 |
OffPeakIdleCount | 已弃用:类似于 IdleCount,但用于 Off Peak 时间段。 |
OffPeakIdleTime | 已弃用:类似于 IdleTime,但用于 Off Peak 时间段。 |
MaxBuilds | 在机器被移除之前的最大作业(构建)数量。 |
MachineName | 机器的名称。必须包含 %s,它将被唯一的机器标识符替换。 |
MachineDriver | Docker Machine 的 driver。详情请参阅 Docker Machine 配置中的云提供商部分。 |
MachineOptions | Docker Machine 的 MachineDriver 选项。有关更多信息,请参阅支持的云提供商。有关 AWS 的所有选项的更多信息,请参阅 Docker Machine 存储库中的 AWS 和 GCP 项目。 |
[[runners.machine.autoscaling]] 部分
以下参数定义在使用 Instance 或 Docker Autoscaler 执行器时可用的配置。
参数 | 描述 |
---|---|
Periods | 此计划活动期间的时间段。cron 风格模式的数组(在下方描述)。 |
IdleCount | 需要创建并处于 Idle 状态的机器数量。 |
IdleScaleFactor | (实验)处于 Idle 状态的机器数量作为使用中机器数量的一个因子。必须是浮点数格式。有关更多详细信息,请参阅自动缩放文档。默认是 0.0。 |
IdleCountMin | 当使用 IdleScaleFactor 时,需创建并处于 Idle 状态的机器的最小数量。默认是 1。 |
IdleTime | 机器处于 Idle 状态的时间(以秒为单位)然后被移除。 |
Timezone | Periods 中给出的时间的时区。类似 Europe/Berlin 的时区字符串。如果省略或为空,默认使用主机的区域系统设置。极狐GitLab Runner 尝试在 ZONEINFO 环境变量指向的目录或未压缩的 zip 文件中查找时区数据库,然后在 Unix 系统的已知安装位置查找,最后在 $GOROOT/lib/time/zoneinfo.zip 中查找。 |
示例:
toml1[runners.machine] 2 IdleCount = 5 3 IdleTime = 600 4 MaxBuilds = 100 5 MachineName = "auto-scale-%s" 6 MachineDriver = "google" # 参考 Docker Machine 文档了解如何认证:https://docs.docker.com/machine/drivers/gce/#credentials 7 MachineOptions = [ 8 # 使用 Google Compute Engine 驱动程序可以添加额外的机器选项。 9 # 如果遇到主机不可达的问题(例如“等待 SSH”), 10 # 应该删除可选参数以帮助调试。 11 # https://docs.docker.com/machine/drivers/gce/ 12 "google-project=GOOGLE-PROJECT-ID", 13 "google-zone=GOOGLE-ZONE", # 例如 'us-central1-a',完整列表见 https://cloud.google.com/compute/docs/regions-zones/ 14 ] 15 [[runners.machine.autoscaling]] 16 Periods = ["* * 9-17 * * mon-fri *"] 17 IdleCount = 50 18 IdleCountMin = 5 19 IdleScaleFactor = 1.5 # 表示当前空闲机器的数量将是 1.5*使用中的机器, 20 # 不超过 50(IdleCount 的值),不少于 5(IdleCountMin 的值) 21 IdleTime = 3600 22 Timezone = "UTC" 23 [[runners.machine.autoscaling]] 24 Periods = ["* * * * * sat,sun *"] 25 IdleCount = 5 26 IdleTime = 60 27 Timezone = "UTC"
时间段语法
Periods 设置包含以 cron 风格格式表示的时间段字符串的数组。该行包含以下字段:
plaintext[second] [minute] [hour] [day of month] [month] [day of week] [year]
如同标准的 cron 配置文件,字段可以包含单个值、范围、列表和星号。查看语法的详细描述。
runners.instance 部分
参数 | 类型 | 描述 |
---|---|---|
allowed_images | 字符串 | 启用虚拟机隔离时,allowed_images 控制作业允许指定哪些镜像。 |
runners.autoscaler 部分
History
- 在极狐GitLab Runner v15.10.0 中引入。
以下参数配置自动缩放功能。你只能在 Instance 和 Docker Autoscaler 执行器中使用这些参数。
参数 | 描述 |
---|---|
capacity_per_instance | 单个实例可以同时执行的作业数量。 |
max_use_count | 实例在被安排移除之前可以使用的最大次数。 |
max_instances | 允许的最大实例数量,这与实例状态(待定、运行、删除)无关。默认值:0(无限制)。 |
plugin | 要使用的 fleeting 插件。有关如何安装和引用插件的详细信息,请参阅 安装 fleeting 插件。 |
delete_instances_on_shutdown | 指定极狐GitLab Runner 关闭时是否删除所有预留的实例。默认:false。在 极狐GitLab Runner 15.11 中引入 |
instance_ready_command | 在自动缩放器预留的每个实例上执行此命令以确保它已准备好使用。失败会导致实例被移除。在 极狐GitLab Runner 16.11 中引入。 |
update_interval | 检查 fleeting 插件进行实例更新的间隔。默认值:1m(1 分钟)。在 极狐GitLab Runner 16.11 中引入。 |
update_interval_when_expecting | 在期待状态变化时检查 fleeting 插件进行实例更新的间隔。例如,当实例已预留且 runner 等待从 pending 过渡到 running 时)。默认值:2s(2 秒)。在 极狐GitLab Runner 16.11 中引入。 |
如果 instance_ready_command 在空闲缩放规则下频繁失败,实例可能会被移除并创建得比 runner 接受作业的速度还快。为了支持缩放节流,极狐GitLab 17.0 中添加了指数退避。
自动缩放器配置选项不会随着配置更改而重新加载。但是,在极狐GitLab 17.5.0 或更高版本中,配置更改时重新加载 [[runners.autoscaler.policy]] 条目。
runners.autoscaler.plugin_config 部分
此哈希表被重新编码为 JSON 并直接传递给配置的插件。
fleeting 插件通常会附带支持的配置的文档。
runners.autoscaler.scale_throttle 部分
History
- 在极狐GitLab Runner v17.0.0 中引入。
参数 | 描述 |
---|---|
limit | 每秒可以预留的新实例的速率限制。-1 表示无限。默认值(0),将限制设置为 100。 |
burst | 新实例的突发限制。默认值是 max_instances 或 limit,当未设置 max_instances 时。如果 limit 是无限的,则忽略 burst。 |
limit 和 burst 之间的关系
缩放节流使用令牌配额系统来创建实例。此系统由两个值定义:
- burst:配额的最大大小。
- limit:每秒配额刷新率。
你可以一次创建的实例数量取决于剩余的配额。 如果你有足够的配额,你可以创建多达该数量的实例。 如果配额耗尽,你可以每秒创建 limit 个实例。 当实例创建停止时,配额每秒增加 limit,直到达到 burst 值。
例如,如果 limit 是 1 且 burst 是 60:
- 你可以立即创建 60 个实例,但会受到节流。
- 如果你等待 60 秒,可以立即创建另外 60 个实例。
- 如果不等待,你可以每秒创建 1 个实例。
runners.autoscaler.connector_config 部分
fleeting 插件通常会附带支持的连接选项的文档。
插件会自动更新连接器配置。你可以使用 [runners.autoscaler.connector_config] 覆盖连接器配置的自动更新,或者填写插件无法确定的空值。
参数 | 描述 |
---|---|
os | 实例的操作系统。 |
arch | 实例的架构。 |
protocol | ssh、winrm 或 winrm+https。如果检测到 Windows,则默认使用 winrm。 |
protocol_port | 基于指定协议建立连接的端口。默认值为 ssh:220,winrm+http:5985,winrm+https:5986。 |
username | 用于连接的用户名。 |
password | 用于连接的密码。 |
key_path | 用于连接或动态预留凭据的 TLS 密钥。 |
use_static_credentials | 禁用自动凭据预留。默认值:false。 |
keepalive | 连接保持活动的持续时间。 |
timeout | 连接超时时间。 |
use_external_addr | 是否使用插件提供的外部地址。如果插件仅返回内部地址,则无论此设置如何,它都会被使用。默认值:false。 |
runners.autoscaler.state_storage 部分
- 状态:Beta
History
- 在极狐GitLab Runner 17.5.0 中引入。
如果极狐GitLab Runner 在禁用状态存储(默认)时启动,为了安全起见,现有的 fleeting 实例会立即被移除。例如,当 max_use_count 设置为 1 时, 如果我们不知道其实例的使用状态,我们可能会不小心将作业分配给一个已使用的实例。
启用状态存储功能可以使实例的状态在本地磁盘上持久化。 在这种情况下,如果在极狐GitLab Runner 启动时存在实例,则不会被删除。其缓存的连接详细信息、使用计数和其他配置将被恢复。
启用状态存储功能时,请考虑以下信息:
-
实例的身份验证详细信息(用户名、密码、密钥) 将保留在磁盘上。
-
如果在极狐GitLab Runner 启动时实例正在积极运行作业,极狐GitLab Runner 默认会将其删除。此行为确保安全,因为极狐GitLab Runner 无法恢复作业。要保留实例,请将 keep_instance_with_acquisitions 设置为 true。
将 keep_instance_with_acquisitions 设置为 true 有助于当你不关心实例上正在进行的作业时。你还可以使用 instance_ready_command 配置选项来清理环境以保留实例。这可能涉及停止所有正在执行的命令或强制删除 Docker 容器。
参数 | 描述 |
---|---|
enabled | 是否启用状态存储。默认:false。 |
dir | 状态存储目录。此处每个 runner 配置条目都有一个子目录。默认:极狐GitLab Runner 配置文件目录中的 .taskscaler。 |
keep_instance_with_acquisitions | 是否删除具有活动作业的实例。默认:false。 |
runners.autoscaler.policy 部分
注意 - 在此上下文中,idle_count 指的是作业数量,而不是旧的自动缩放方法中的自动缩放机器数量。
参数 | 描述 |
---|---|
periods | 一个 UNIX-cron 格式化字符串的数组,用于表示此策略启用的时间段。默认:* * * * * |
timezone | 评估 UNIX-cron 时间段时使用的时区。默认:系统的本地时区。 |
idle_count | 我们希望立即为作业提供的目标空闲容量。 |
idle_time | 实例可以处于空闲状态的时间。 |
scale_factor | 我们希望立即为作业提供的目标空闲容量,作为 idle_count 之外的当前使用容量的一个因子。默认值为 0.0。 |
scale_factor_limit | scale_factor 计算可以产生的最大容量。 |
为了决定是否移除空闲实例,taskscaler 将 idle_time 与实例的空闲持续时间进行比较。 每个实例的空闲周期是从实例:
- 上次完成作业(如果实例以前使用过)。
- 被预留时(如果从未使用过)。
此检查在缩放事件期间发生。超过配置的 idle_time 的实例将被移除,除非需要保持所需的 idle_count 作业容量。
当设置 scale_factor 时,idle_count 成为最小 idle 容量,而 scaler_factor_limit 是最大 idle 容量。
你可以定义多个策略。使用最后一个匹配的策略。
在以下示例中,空闲计数 1 在周一至周五的 08:00 到 15:59 之间使用。否则,空闲计数为 0。
toml1[[runners.autoscaler.policy]] 2 idle_count = 0 3 idle_time = "0s" 4 periods = ["* * * * *"] 5 6[[runners.autoscaler.policy]] 7 idle_count = 1 8 idle_time = "30m0s" 9 periods = ["* 8-15 * * mon-fri"]
时间段语法
periods 设置包含一个 UNIX-cron 格式化字符串的数组,用于表示策略启用的时间段。cron 格式由 5 个字段组成:
plaintext1 ┌────────── 分钟 (0 - 59) 2 │ ┌──────── 小时 (0 - 23) 3 │ │ ┌────── 月中的日 (1 - 31) 4 │ │ │ ┌──── 月 (1 - 12) 5 │ │ │ │ ┌── 周中的日 (1 - 7 或 MON-SUN,0 是星期日的别名) 6 * * * * *
- - 可以用于两个数字之间以指定范围。
- * 可以用于表示该字段的有效值的整个范围。
- / 后跟一个数字或可以在范围后使用,以跳过该数字的范围。例如,小时字段的 0-12/2 将在 00:00 到 00:12 之间的每 2 小时激活一次。
- , 可以用于分隔字段的有效数字或范围的列表。例如,1,2,6-9。
值得注意的是,这个 cron 作业表示一个时间范围。例如:
时间段 | 影响 |
---|---|
1 * * * * * | 每小时启用 1 分钟的规则(不太可能非常有效) |
* 0-12 * * * | 每天开始时启用 12 小时的规则 |
0-30 13,16 * * SUN | 每个星期日下午 1 点和 4 点启用 30 分钟的规则。 |
runners.autoscaler.vm_isolation 部分
虚拟机隔离使用 nesting,仅在 macOS 上支持。
参数 | 描述 |
---|---|
enabled | 指定是否启用虚拟机隔离。默认:false。 |
nesting_host | nesting 守护进程主机。 |
nesting_config | nesting 配置,它被序列化为 JSON 并发送到 nesting 守护进程。 |
image | 如果没有指定作业镜像,则由 nesting 守护进程使用的默认镜像。 |
runners.autoscaler.vm_isolation.connector_config 部分
[runners.autoscaler.vm_isolation.connector_config] 部分的参数与 [runners.autoscaler.connector_config] 部分相同, 但用于连接到 nesting 预留的虚拟机,而不是自动缩放的实例。
runners.custom 部分
以下参数定义了 自定义执行器 的配置。
参数 | 类型 | 描述 |
---|---|---|
config_exec | 字符串 | 可执行文件的路径,以便用户可以在作业开始之前覆盖一些配置设置。这些值将覆盖在 [[runners]] 部分中设置的值。自定义执行器文档 中有完整列表。 |
config_args | 字符串数组 | 传递给 config_exec 可执行文件的第一组参数。 |
config_exec_timeout | 整数 | config_exec 完成执行的超时时间(以秒为单位)。默认是 3600 秒(1 小时)。 |
prepare_exec | 字符串 | 准备环境的可执行文件的路径。 |
prepare_args | 字符串数组 | 传递给 prepare_exec 可执行文件的第一组参数。 |
prepare_exec_timeout | 整数 | prepare_exec 完成执行的超时时间(以秒为单位)。默认是 3600 秒(1 小时)。 |
run_exec | 字符串 | 必需。 在环境中运行脚本的可执行文件的路径。例如,克隆和构建脚本。 |
run_args | 字符串数组 | 传递给 run_exec 可执行文件的第一组参数。 |
cleanup_exec | 字符串 | 清理环境的可执行文件的路径。 |
cleanup_args | 字符串数组 | 传递给 cleanup_exec 可执行文件的第一组参数。 |
cleanup_exec_timeout | 整数 | cleanup_exec 完成执行的超时时间(以秒为单位)。默认是 3600 秒(1 小时)。 |
graceful_kill_timeout | 整数 | 在被终止时(例如在作业取消期间)等待 prepare_exec 和 cleanup_exec 的时间(以秒为单位)。在此超时时间后,进程将被杀死。默认是 600 秒(10 分钟)。 |
force_kill_timeout | 整数 | 在向脚本发送杀死信号之后等待的时间(以秒为单位)。默认是 600 秒(10 分钟)。 |
runners.cache 部分
以下参数定义了分布式缓存功能。详细信息请参阅 runner 自动缩放文档。
参数 | 类型 | 描述 |
---|---|---|
Type | 字符串 | 之一:s3、gcs、azure。 |
Path | 字符串 | 要添加到缓存 URL 的路径名称。 |
Shared | 布尔型 | 启用 runner 之间的缓存共享。默认是 false。 |
MaxUploadedArchiveSize | int64 | 上传到云存储的缓存归档的限制,以字节为单位。恶意行为者可以绕过此限制,因此 GCS 适配器通过签名 URL 中的 X-Goog-Content-Length-Range 标头强制执行。你还应该在云存储提供商处设置限制。 |
缓存机制使用预签名的 URL 上传和下载缓存。URL 由极狐GitLab Runner 在其自身实例上签署。 无论作业脚本(包括缓存上传/下载脚本)是在本地还是外部 机器上执行,这都无关紧要。例如,shell 或 docker 执行器在极狐GitLab Runner 进程运行的同一 机器上运行其脚本。同时,virtualbox 或 docker+machine 连接到单独的虚拟机以执行脚本。此过程是出于安全原因: 最大限度地减少泄露缓存适配器凭据的可能性。
如果 S3 缓存适配器 配置为使用 IAM 实例配置文件,则适配器使用附加到极狐GitLab Runner 机器的配置文件。 同样对于 GCS 缓存适配器,如果配置为 使用 CredentialsFile。该文件需要存在于极狐GitLab Runner 机器上。
下表列出了 config.toml、CLI 选项和 register 的环境变量。
设置 | TOML 字段 | register 的 CLI 选项 | register 的环境变量 |
---|---|---|---|
Type | [runners.cache] -> Type | --cache-type | $CACHE_TYPE |
Path | [runners.cache] -> Path | --cache-path 在 12.0 之前,--cache-s3-cache-path | $CACHE_PATH 在 12.0 之前,$S3_CACHE_PATH |
Shared | [runners.cache] -> Shared | --cache-shared 在 12.0 之前,--cache-cache-shared | $CACHE_SHARED |
S3.ServerAddress | [runners.cache.s3] -> ServerAddress 在 12.0 之前,[runners.cache] -> ServerAddress | --cache-s3-server-address | $CACHE_S3_SERVER_ADDRESS 在 12.0 之前,$S3_SERVER_ADDRESS |
S3.AccessKey | [runners.cache.s3] -> AccessKey 在 12.0 之前,[runners.cache] -> AccessKey | --cache-s3-access-key | $CACHE_S3_ACCESS_KEY 在 12.0 之前,$S3_ACCESS_KEY |
S3.SecretKey | [runners.cache.s3] -> SecretKey 在 12.0 之前,[runners.cache] -> SecretKey | --cache-s3-secret-key | $CACHE_S3_SECRET_KEY 在 12.0 之前,$S3_SECRET_KEY |
S3.SessionToken | [runners.cache.s3] -> SessionToken | --cache-s3-session-token | $CACHE_S3_SESSION_TOKEN |
S3.BucketName | [runners.cache.s3] -> BucketName 在 12.0 之前,[runners.cache] -> BucketName | --cache-s3-bucket-name | $CACHE_S3_BUCKET_NAME 在 12.0 之前,$S3_BUCKET_NAME |
S3.BucketLocation | [runners.cache.s3] -> BucketLocation 在 12.0 之前,[runners.cache] -> BucketLocation | --cache-s3-bucket-location | $CACHE_S3_BUCKET_LOCATION 在 12.0 之前,$S3_BUCKET_LOCATION |
S3.Insecure | [runners.cache.s3] -> Insecure 在 12.0 之前,[runners.cache] -> Insecure | --cache-s3-insecure | $CACHE_S3_INSECURE 在 12.0 之前,$S3_INSECURE |
S3.AuthenticationType | [runners.cache.s3] -> AuthenticationType | --cache-s3-authentication_type | $CACHE_S3_AUTHENTICATION_TYPE |
S3.ServerSideEncryption | [runners.cache.s3] -> ServerSideEncryption | --cache-s3-server-side-encryption | $CACHE_S3_SERVER_SIDE_ENCRYPTION |
S3.ServerSideEncryptionKeyID | [runners.cache.s3] -> ServerSideEncryptionKeyID | --cache-s3-server-side-encryption-key-id | $CACHE_S3_SERVER_SIDE_ENCRYPTION_KEY_ID |
S3.DualStack | [runners.cache.s3] -> DualStack | --cache-s3-dual-stack | $CACHE_S3_DUAL_STACK |
S3.Accelerate | [runners.cache.s3] -> Accelerate | --cache-s3-accelerate | $CACHE_S3_ACCELERATE |
S3.PathStyle | [runners.cache.s3] -> PathStyle | --cache-s3-path-style | $CACHE_S3_PATH_STYLE |
S3.RoleARN | [runners.cache.s3] -> RoleARN | --cache-s3-role-arn | $CACHE_S3_ROLE_ARN |
S3.UploadRoleARN | [runners.cache.s3] -> UploadRoleARN | --cache-s3-upload-role-arn | $CACHE_S3_UPLOAD_ROLE_ARN |
GCS.AccessID | [runners.cache.gcs] -> AccessID | --cache-gcs-access-id | $CACHE_GCS_ACCESS_ID |
GCS.PrivateKey | [runners.cache.gcs] -> PrivateKey | --cache-gcs-private-key | $CACHE_GCS_PRIVATE_KEY |
GCS.CredentialsFile | [runners.cache.gcs] -> CredentialsFile | --cache-gcs-credentials-file | $GOOGLE_APPLICATION_CREDENTIALS |
GCS.BucketName | [runners.cache.gcs] -> BucketName | --cache-gcs-bucket-name | $CACHE_GCS_BUCKET_NAME |
Azure.AccountName | [runners.cache.azure] -> AccountName | --cache-azure-account-name | $CACHE_AZURE_ACCOUNT_NAME |
Azure.AccountKey | [runners.cache.azure] -> AccountKey | --cache-azure-account-key | $CACHE_AZURE_ACCOUNT_KEY |
Azure.ContainerName | [runners.cache.azure] -> ContainerName | --cache-azure-container-name | $CACHE_AZURE_CONTAINER_NAME |
Azure.StorageDomain | [runners.cache.azure] -> StorageDomain | --cache-azure-storage-domain | $CACHE_AZURE_STORAGE_DOMAIN |
runners.cache.s3 部分
以下参数定义 S3 存储用于缓存。
参数 | 类型 | 描述 |
---|---|---|
ServerAddress | 字符串 | S3 兼容服务器的 host:port。如果你使用的是 AWS 以外的服务器,请查阅存储产品文档以确定正确的地址。对于 DigitalOcean,地址必须采用 spacename.region.digitaloceanspaces.com 格式。 |
AccessKey | 字符串 | 为你的 S3 实例指定的访问密钥。 |
SecretKey | 字符串 | 为你的 S3 实例指定的秘密密钥。 |
SessionToken | 字符串 | 使用临时凭据时为你的 S3 实例指定的会话令牌。 |
BucketName | 字符串 | 存储缓存的存储桶名称。 |
BucketLocation | 字符串 | S3 区域的名称。 |
Insecure | 布尔型 | 如果 S3 服务可通过 HTTP 获得,则设置为 true。默认是 false。 |
AuthenticationType | 字符串 | 设置为 iam 或 access-key。如果提供了 ServerAddress、AccessKey 和 SecretKey,则默认是 access-key。如果缺少 ServerAddress、AccessKey 或 SecretKey,则默认为 iam。 |
ServerSideEncryption | 字符串 | 使用 S3 的服务器端加密类型。在极狐GitLab 15.3 及更高版本中,可用类型为 S3 或 KMS。在极狐GitLab 17.5 及更高版本中,支持 DSSE-KMS。 |
ServerSideEncryptionKeyID | 字符串 | 使用 KMS 加密时用于加密的 KMS 密钥的别名或 ID。如果使用别名,请在前面加上 alias/。在极狐GitLab 15.3 及更高版本中可用。 |
DualStack | 布尔型 | 启用 IPv4 和 IPv6 端点。默认是 true。如果使用 AWS S3 Express,请禁用此设置。如果设置了 ServerAddress,极狐GitLab 将忽略此设置。在极狐GitLab 17.5 及更高版本中可用。 |
Accelerate | 布尔型 | 启用 AWS S3 传输加速。如果 ServerAddress 配置为加速端点,极狐GitLab 会自动将其设置为 true。在极狐GitLab 17.5 及更高版本中可用。 |
PathStyle | 布尔型 | 启用路径风格访问。默认情况下,极狐GitLab 根据 ServerAddress 值自动检测此设置。在极狐GitLab 17.5 及更高版本中可用。 |
UploadRoleARN | 字符串 | 已弃用。请改用 RoleARN。指定一个 AWS 角色 ARN,可以与 AssumeRole 一起使用以生成时间限制的 PutObject S3 请求。启用 S3 分段上传。在极狐GitLab 17.5 及更高版本中可用。 |
RoleARN | 字符串 | 指定一个 AWS 角色 ARN,可以与 AssumeRole 一起使用以生成时间限制的 GetObject 和 PutObject S3 请求。启用 S3 分段传输。在极狐GitLab 17.8 及更高版本中可用。 |
示例:
toml1[runners.cache] 2 Type = "s3" 3 Path = "path/to/prefix" 4 Shared = false 5 [runners.cache.s3] 6 ServerAddress = "s3.amazonaws.com" 7 AccessKey = "AWS_S3_ACCESS_KEY" 8 SecretKey = "AWS_S3_SECRET_KEY" 9 BucketName = "runners-cache" 10 BucketLocation = "eu-west-1" 11 Insecure = false 12 ServerSideEncryption = "KMS" 13 ServerSideEncryptionKeyID = "alias/my-key"
如果未指定 ServerAddress、AccessKey 或 SecretKey 并且未提供 AuthenticationType,那么 S3 客户端将使用 gitlab-runner 实例可用的 IAM 实例配置文件。在 autoscale 配置中,这不是执行作业的按需机器。如果 ServerAddress、AccessKey 和 SecretKey 都已指定,但未提供 AuthenticationType,则 access-key 用作身份验证类型。
当您使用 Helm charts 安装极狐GitLab Runner,并且在 values.yaml 文件中将 rbac.create 设置为 true 时,将创建一个 ServiceAccount。此 ServiceAccount 的注释从 rbac.serviceAccountAnnotations 部分中获取。
对于 Amazon EKS 上的 runners,您可以指定一个 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 外,还提供包含用户提供密钥的标头以进行下载请求。这意味着需要将密钥材料传递给作业,而密钥无法保证安全。这确实有可能泄漏解密密钥。
可以上传到 AWS S3 缓存的单个文件的最大大小为 5 GB。
在 S3 桶中为 runner 缓存使用 KMS 密钥加密
GenerateDataKey API 使用 KMS 对称密钥为客户端加密创建数据密钥。KMS 密钥配置必须如下:
属性 | 描述 |
---|---|
密钥类型 | 对称 |
来源 | AWS_KMS |
密钥规范 | SYMMETRIC_DEFAULT |
密钥用途 | 加密和解密 |
分配给 rbac.serviceAccountName 中定义的 ServiceAccount 的角色的 IAM 策略必须有权对 KMS 密钥执行以下操作:
- kms:GetPublicKey
- kms:Decrypt
- kms:Encrypt
- kms:DescribeKey
- kms:GenerateDataKey
使用 RoleARN 启用多部分传输
为了限制对缓存的访问,runner 管理器为作业生成限时的预签名 URLs,用于从缓存下载和上传。然而,AWS S3 限制单个 PUT 请求到 5 GB。对于超过 5 GB 的文件,您必须使用多部分上传 API。
多部分传输仅支持 AWS S3,而不支持其他 S3 提供商。因为 runner 管理器处理不同项目的作业,所以它不能传递具有桶级权限的 S3 凭据。相反,runner 管理器使用限时的预签名 URLs 和范围狭窄的凭据来限制对特定对象的访问。
要在 AWS 上使用 S3 多部分传输,请在 RoleARN 中指定一个 IAM 角色,格式为 arn:aws:iam:::<ACCOUNT ID>:<YOUR ROLE NAME>。此角色生成限时的 AWS 凭据,这些凭据的范围仅限于写入桶中的特定 blob。确保您的原始 S3 凭据可以访问指定 RoleARN 的 AssumeRole。
在 RoleARN 中指定的 IAM 角色必须具有以下权限:
- 对 BucketName 中指定的桶的 s3:GetObject 访问。
- 对 BucketName 中指定的桶的 s3:PutObject 访问。
- 如果启用了带有 KMS 或 DSSE-KMS 的服务器端加密,则需要 kms:Decrypt 和 kms:GenerateDataKey。
例如,假设您有一个名为 my-instance-role 的 IAM 角色,附加到 ARN 为 arn:aws:iam::1234567890123:role/my-instance-role 的 EC2 实例。
您可以创建一个新角色 arn:aws:iam::1234567890123:role/my-upload-role,该角色仅对 BucketName 具有 s3:PutObject 权限。在 my-instance-role 的 AWS 设置中,Trust relationships 可能如下所示:
json1{ 2 "Version": "2012-10-17", 3 "Statement": [ 4 { 5 "Effect": "Allow", 6 "Principal": { 7 "AWS": "arn:aws:iam::1234567890123:role/my-upload-role" 8 }, 9 "Action": "sts:AssumeRole" 10 } 11 ] 12}
您还可以将 my-instance-role 重新用作 RoleARN,避免创建新角色。确保 my-instance-role 具有 AssumeRole 权限。例如,与 EC2 实例关联的 IAM 配置文件可能具有以下 Trust relationships:
json1{ 2 "Version": "2012-10-17", 3 "Statement": [ 4 { 5 "Effect": "Allow", 6 "Principal": { 7 "Service": "ec2.amazonaws.com", 8 "AWS": "arn:aws:iam::1234567890123:role/my-instance-role" 9 }, 10 "Action": "sts:AssumeRole" 11 } 12 ] 13}
您可以使用 AWS 命令行接口验证您的实例是否具有 AssumeRole 权限。例如:
shellaws sts assume-role --role-arn arn:aws:iam::1234567890123:role/my-upload-role --role-session-name gitlab-runner-test1
使用 RoleARN 的上传工作原理
如果存在 RoleARN,每次 runner 上传到缓存时:
-
runner 管理器检索原始 S3 凭据(通过 AuthenticationType、AccessKey 和 SecretKey 指定)。
-
使用 S3 凭据,runner 管理器向 Amazon 安全令牌服务 (STS) 发送请求以获取 AssumeRole,带有 RoleARN。策略请求类似于以下内容:
json1{ 2 "Version": "2012-10-17", 3 "Statement": [ 4 { 5 "Effect": "Allow", 6 "Action": ["s3:PutObject"], 7 "Resource": "arn:aws:s3:::<YOUR-BUCKET-NAME>/<CACHE-FILENAME>" 8 } 9 ] 10}
-
如果请求成功,runner 管理器将获得具有受限会话的临时 AWS 凭据。
-
runner 管理器将这些凭据和 URL 以 s3://<bucket name>/<filename> 格式传递给缓存归档器,然后缓存归档器上传文件。
为 Kubernetes ServiceAccount 资源启用 IAM 角色
要为服务账户使用 IAM 角色,必须为您的集群存在一个 IAM OIDC 提供商。将 IAM OIDC 提供商与集群关联后,您可以创建一个 IAM 角色以与 runner 的服务账户关联。
-
在 Create Role 窗口中,Select type of trusted entity 下,选择 Web Identity。
-
在角色的 Trusted Relationships tab 上:
-
Trusted entities 部分必须具有以下格式: arn:aws:iam::<ACCOUNT_ID>:oidc-provider/oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>。 OIDC ID 可以在 EKS 集群的 Configuration 标签上找到。
-
Condition 部分必须定义在 rbac.serviceAccountName 中定义的极狐GitLab Runner 服务账户或如果 rbac.create 设置为 true 时创建的默认服务账户:
条件 键 值 StringEquals oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>:sub system:serviceaccount:<GITLAB_RUNNER_NAMESPACE>:<GITLAB_RUNNER_SERVICE_ACCOUNT>
-
使用 S3 Express One Zone 桶
History
- 引入于极狐GitLab Runner 17.5.0。
S3 Express One Zone 目录桶与 RoleARN 不兼容,因为 runner 管理器无法限制对特定对象的访问。
- 按照 Amazon 教程设置 S3 Express One Zone 桶。
- 使用 BucketName 和 BucketLocation 配置 config.toml。
- 将 DualStack 设置为 false,因为 S3 Express 不支持双栈端点。
示例 config.toml:
toml1[runners.cache] 2 Type = "s3" 3 [runners.cache.s3] 4 BucketName = "example-express--usw2-az1--x-s3" 5 BucketLocation = "us-west-2" 6 DualStack = false
[runners.cache.gcs] 部分
参数 | 类型 | 描述 |
---|---|---|
CredentialsFile | string | Google JSON 密钥文件的路径。仅支持 service_account 类型。如果配置,此值优先于直接在 config.toml 中配置的 AccessID 和 PrivateKey。 |
AccessID | string | 用于访问存储的 GCP 服务账户的 ID。 |
PrivateKey | string | 用于签署 GCS 请求的私钥。 |
BucketName | string | 存储缓存数据的存储桶名称。 |
示例:
直接在 config.toml 文件中配置的凭据:
toml1[runners.cache] 2 Type = "gcs" 3 Path = "path/to/prefix" 4 Shared = false 5 [runners.cache.gcs] 6 AccessID = "cache-access-account@test-project-123456.iam.gserviceaccount.com" 7 PrivateKey = "-----BEGIN PRIVATE KEY-----\nXXXXXX\n-----END PRIVATE KEY-----\n" 8 BucketName = "runners-cache"
从 GCP 下载的 JSON 文件中的凭据:
toml1[runners.cache] 2 Type = "gcs" 3 Path = "path/to/prefix" 4 Shared = false 5 [runners.cache.gcs] 6 CredentialsFile = "/etc/gitlab-runner/service-account.json" 7 BucketName = "runners-cache"
来自 GCP 中元数据服务器的应用程序默认凭据 (ADC):
当您将极狐GitLab Runner 与 Google Cloud ADC 一起使用时,通常使用默认服务账户。然后您不需要为实例提供凭据:
toml1[runners.cache] 2 Type = "gcs" 3 Path = "path/to/prefix" 4 Shared = false 5 [runners.cache.gcs] 6 BucketName = "runners-cache"
如果您使用 ADC,请确保您使用的服务账户具有 iam.serviceAccounts.signBlob 权限。
[runners.cache.azure] 部分
History
- 引入于极狐GitLab Runner 13.4.0。
以下参数定义了对 Azure Blob 存储的原生支持。虽然 S3 和 GCS 使用 bucket 一词来表示对象集合,但 Azure 使用 container 一词来表示 blob 的集合。
参数 | 类型 | 描述 |
---|---|---|
AccountName | string | 用于访问存储的 Azure Blob 存储账户名称。 |
AccountKey | string | 用于访问容器的存储账户访问密钥。要从配置中省略 AccountKey,请使用 Azure 工作负载或托管身份。 |
ContainerName | string | 用于保存缓存数据的存储容器的名称。 |
StorageDomain | string | 用于服务 Azure 存储端点的域名用于服务 Azure 存储端点(可选)。默认值为 blob.core.windows.net。 |
示例:
toml1[runners.cache] 2 Type = "azure" 3 Path = "path/to/prefix" 4 Shared = false 5 [runners.cache.azure] 6 AccountName = "<AZURE STORAGE ACCOUNT NAME>" 7 AccountKey = "<AZURE STORAGE ACCOUNT KEY>" 8 ContainerName = "runners-cache" 9 StorageDomain = "blob.core.windows.net"
Azure 工作负载和托管身份
History
- 引入于极狐GitLab Runner v17.5.0。
要使用 Azure 工作负载或托管身份,请从配置中省略 AccountKey。当 AccountKey 为空时,runner 尝试:
- 使用 DefaultAzureCredential 获取临时凭据。
- 获取用户委派密钥。
- 使用该密钥生成 SAS 令牌以访问存储账户 blob。
确保为实例分配了 Storage Blob Data Contributor 角色。如果实例无权执行上述操作,极狐GitLab Runner 会报告 AuthorizationPermissionMismatch 错误。
要使用 Azure 工作负载身份,请在 runner.kubernetes 部分中添加与身份关联的 service_account 和 pod 标签 azure.workload.identity/use。例如,如果 service_account 是 gitlab-runner:
toml[runners.kubernetes] service_account = "gitlab-runner" [runners.kubernetes.pod_labels] "azure.workload.identity/use" = "true"
确保 service_account 具有与其关联的 azure.workload.identity/client-id 注释:
yamlserviceAccount: annotations: azure.workload.identity/client-id: <YOUR CLIENT ID HERE>
对于极狐GitLab 17.7 及更高版本,此配置足以设置工作负载身份。
然而,对于极狐GitLab Runner 17.5 和 17.6,您还必须使用以下内容配置 runner 管理器:
- azure.workload.identity/use pod 标签
- 要与工作负载身份一起使用的服务账户
例如,使用极狐GitLab Runner Helm chart:
yamlserviceAccount: name: "gitlab-runner" podLabels: azure.workload.identity/use: "true"
需要标签是因为凭据是从不同的来源检索的。对于缓存下载,凭据是从 runner 管理器中检索的。对于缓存上传,凭据是从运行 helper image 的 pod 中检索的。
[runners.kubernetes] 部分
History
- 引入于极狐GitLab Runner v1.6.0。
以下表格列出了 Kubernetes 执行器可用的配置参数。有关更多参数,请参阅 Kubernetes 执行器文档。
参数 | 类型 | 描述 |
---|---|---|
host | string | 可选。Kubernetes 主机 URL。如果未指定,runner 尝试自动发现它。 |
cert_file | string | 可选。Kubernetes 身份验证证书。 |
key_file | string | 可选。Kubernetes 身份验证私钥。 |
ca_file | string | 可选。Kubernetes 身份验证 CA 证书。 |
image | string | 当未指定图像时,用于作业的默认容器图像。 |
allowed_images | array | 容器图像的通配符列表,这些图像在 .gitlab-ci.yml 中是允许的。如果不存在,则允许所有图像(等同于 ["*/*:*"])。与 Docker 或 Kubernetes 执行器一起使用。 |
allowed_services | array | 在 .gitlab-ci.yml 中允许的服务通配符列表。如果不存在,则允许所有图像(等同于 ["*/*:*"])。与 Docker 或 Kubernetes 执行器一起使用。 |
namespace | string | 运行 Kubernetes 作业的命名空间。 |
privileged | boolean | 以启用特权标志运行所有容器。 |
allow_privilege_escalation | boolean | 可选。以启用 allowPrivilegeEscalation 标志运行所有容器。 |
node_selector | table | 一个 string=string 的 key=value 对的 table。将 pod 的创建限制为符合所有 key=value 对的 Kubernetes 节点。 |
image_pull_secrets | array | 包含 Kubernetes docker-registry secret 名称的项目数组,用于从私有注册表中认证拉取容器图像。 |
logs_base_dir | string | 要添加到生成路径中的基目录以存储构建日志。引入于极狐GitLab Runner 17.2。 |
scripts_base_dir | string | 要添加到生成路径中的基目录以存储构建脚本。引入于极狐GitLab Runner 17.2。 |
service_account | string | 作业/执行器 pod 用于与 Kubernetes API 通信的默认服务账户。 |
示例:
toml1[runners.kubernetes] 2 host = "https://45.67.34.123:4892" 3 cert_file = "/etc/ssl/kubernetes/api.crt" 4 key_file = "/etc/ssl/kubernetes/api.key" 5 ca_file = "/etc/ssl/kubernetes/ca.crt" 6 image = "golang:1.8" 7 privileged = true 8 allow_privilege_escalation = true 9 image_pull_secrets = ["docker-registry-credentials", "optional-additional-credentials"] 10 allowed_images = ["ruby:*", "python:*", "php:*"] 11 allowed_services = ["postgres:9.4", "postgres:latest"] 12 logs_base_dir = "/tmp" 13 scripts_base_dir = "/tmp" 14 [runners.kubernetes.node_selector] 15 gitlab = "true"
辅助镜像
当您使用 docker、docker+machine 或 kubernetes 执行器时,极狐GitLab Runner 使用一个特定的容器来处理 Git、产物和缓存操作。此容器是从名为 helper image 的镜像创建的。
辅助镜像适用于 amd64、arm、arm64、s390x 和 ppc64le 架构。它包含一个 gitlab-runner-helper 二进制文件,这是极狐GitLab Runner 二进制文件的特殊编译版本。它仅包含可用命令的子集,以及 Git、Git LFS 和 SSL 证书存储。
辅助镜像有几种风格:alpine、alpine3.18、alpine3.19、alpine3.21、alpine-latest、ubi-fips 和 ubuntu。由于其小巧的体积,alpine 镜像是默认的。使用 helper_image_flavor = "ubuntu" 选择 ubuntu 风格的辅助镜像。
在极狐GitLab Runner 16.1 到 17.1 中,alpine 风格是 alpine3.18 的别名。在极狐GitLab Runner 17.2 到 17.6 中,它是 alpine3.19 的别名。在极狐GitLab Runner 17.7 及更高版本中,它是 alpine3.21 的别名。
alpine-latest 风格使用 alpine:latest 作为其基础镜像,这可能意味着它更不稳定。
当极狐GitLab Runner 从 DEB 或 RPM 包中安装时,支持的架构的镜像会安装在主机上。如果 Docker Engine 找不到指定的镜像版本,runner 会在运行作业之前自动下载它。docker 和 docker+machine 执行器都以这种方式工作。
对于 alpine 风格,只有默认的 alpine 风格镜像包含在包中。所有其他风格均从注册表中下载。
kubernetes 执行器和极狐GitLab Runner 的手动安装工作方式不同。
- 对于手动安装,gitlab-runner-helper 二进制文件未包含。
- 对于 kubernetes 执行器,Kubernetes API 不允许从本地存档加载 gitlab-runner-helper 镜像。
在这两种情况下,极狐GitLab Runner 下载辅助镜像。极狐GitLab Runner 的修订版和架构定义了要下载的标签。
Kubernetes 上 Arm 的辅助镜像配置
要在 arm64 Kubernetes 集群上使用 arm64 辅助镜像,请在您的 配置文件 中设置以下值。
toml[runners.kubernetes] helper_image = "registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:arm64-latest"
使用旧版本 Alpine Linux 的 runner 镜像
History
- 引入于极狐GitLab Runner 14.5。
镜像是用多个版本的 Alpine Linux 构建的。您可以使用较新的 Alpine 版本,但同时也可以使用较旧的版本。
对于辅助镜像,改变 helper_image_flavor 或阅读 辅助镜像 部分。
对于极狐GitLab Runner 镜像,遵循相同的逻辑,其中 alpine、alpine3.18、alpine3.19、alpine3.21 或 alpine-latest 用作镜像的前缀,在版本之前:
shelldocker pull gitlab/gitlab-runner:alpine3.19-v16.1.0
Alpine pwsh 镜像
从极狐GitLab Runner 16.1 及更高版本开始,所有 alpine 辅助镜像都有一个 pwsh 变体。唯一的例外是 alpine-latest,因为 powershell Docker 镜像基于的极狐GitLab Runner 辅助镜像不支持 alpine:latest。
示例:
shelldocker pull registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:alpine3.21-x86_64-v17.7.0-pwsh
辅助镜像注册表
在极狐GitLab 15.0 及更早版本中,您可以配置辅助镜像以使用来自 Docker Hub 的镜像。
在极狐GitLab 15.1 及更高版本中,辅助镜像从极狐GitLab 容器注册表中拉取。
要从极狐GitLab 注册表检索基础 gitlab-runner-helper 镜像,请使用 helper-image 值:registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}。
极狐GitLab 私有化部署实例也会从 JihuLab.com 上的极狐GitLab 容器注册表中拉取辅助镜像。要检查极狐GitLab 容器注册表的状态,请参阅 极狐GitLab 系统状态。
覆盖辅助镜像
在某些情况下,您可能需要覆盖辅助镜像,原因如下:
-
加快作业执行速度:在网络连接较慢的环境中,多次下载同一镜像会增加执行作业所需的时间。从本地注册表下载辅助镜像,其中存储了 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ 的准确副本,可以加快速度。
-
安全问题:您可能不想下载未经过检查的外部依赖项。可能有一条业务规则,只使用已审核并存储在本地存储库中的依赖项。
-
无网络访问的构建环境:如果您有 在脱机环境中安装的 Kubernetes 集群,您可以使用本地图像注册表或包存储库来拉取 CI/CD 作业中使用的图像。
-
附加软件:您可能希望在辅助镜像中安装一些附加软件,例如 openssh,以支持使用 git+ssh 访问的子模块,而不是 git+http。
在这些情况下,您可以使用 helper_image 配置字段配置自定义镜像,该字段可用于 docker、docker+machine 和 kubernetes 执行器:
toml1[[runners]] 2 (...) 3 executor = "docker" 4 [runners.docker] 5 (...) 6 helper_image = "my.registry.local/gitlab/gitlab-runner-helper:tag"
辅助镜像的版本应被认为是与极狐GitLab Runner 的版本严格耦合的。提供这些镜像的主要原因之一是极狐GitLab Runner 使用 gitlab-runner-helper 二进制文件。此二进制文件是从极狐GitLab Runner 源代码的一部分编译的。此二进制文件使用的内部 API 预计在两个二进制文件中是相同的。
默认情况下,极狐GitLab Runner 引用一个 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ 镜像,其中 XYZ 基于极狐GitLab Runner 架构和 Git 修订版。在极狐GitLab Runner 11.3 及更高版本中,您可以使用 版本变量 之一定义镜像版本:
toml1[[runners]] 2 (...) 3 executor = "docker" 4 [runners.docker] 5 (...) 6 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 会尝试下载适当的镜像。在升级极狐GitLab Runner 之前,应将镜像上传到注册表,否则作业将开始因 "No such image" 错误而失败。
在极狐GitLab Runner 13.2 及更高版本中,除了 $CI_RUNNER_REVISION 外,辅助镜像还以 $CI_RUNNER_VERSION 标记。这两个标签都是有效的,并指向同一个镜像。
toml1[[runners]] 2 (...) 3 executor = "docker" 4 [runners.docker] 5 (...) 6 helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"
使用 PowerShell Core 时
发布了一个适用于 Linux 的辅助镜像版本,其中包含 PowerShell Core,标记为 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ-pwsh。
[runners.custom_build_dir] 部分
History
- 引入于极狐GitLab Runner 11.10。
此部分定义了 自定义构建目录 参数。
如果未明确配置此功能,则对于 kubernetes、docker、docker+machine、docker autoscaler 和 instance 执行器,此功能默认启用。对于所有其他执行器,默认情况下此功能禁用。
此功能要求 GIT_CLONE_PATH 位于 runners.builds_dir 中定义的路径中。要使用 builds_dir,请使用 $CI_BUILDS_DIR 变量。
默认情况下,此功能仅对 docker 和 kubernetes 执行器启用,因为它们提供了一种良好的资源分离方式。可以显式为任何执行器启用此功能,但在与共享 builds_dir 并且 concurrent > 1 的执行器一起使用时,请谨慎使用。
参数 | 类型 | 描述 |
---|---|---|
enabled | boolean | 允许用户为作业定义自定义构建目录。 |
示例:
toml[runners.custom_build_dir] enabled = true
默认构建目录
极狐GitLab Runner 将存储库克隆到一个存在于更好称为 Builds Directory 的基本路径下的路径。此基本目录的默认位置取决于执行器。对于:
- Kubernetes、Docker 和 Docker Machine 执行器,它是在容器内的 /builds。
- 实例,它是在处理 SSH 或 WinRM 连接到目标机器的用户的主目录中的 ~/builds。
- Docker Autoscaler,它是在容器内的 /builds。
- Shell 执行器,它是 $PWD/builds。
- SSH、VirtualBox 和 Parallels 执行器,它是在处理 SSH 连接到目标机器的用户的主目录中的 ~/builds。
- 自定义 执行器,没有提供默认值,必须显式配置,否则作业失败。
用户可以通过 builds_dir 设置显式定义使用的 Builds Directory。
如果您想克隆到自定义目录,还可以指定 GIT_CLONE_PATH,并且以下指南不适用。
极狐GitLab Runner 使用 Builds Directory 运行它执行的所有作业,但使用特定模式 {builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_PROJECT_ID/$NAMESPACE/$PROJECT_NAME 嵌套它们。例如:/builds/2mn-ncv-/0/user/playground。
极狐GitLab Runner 不会阻止您在 Builds Directory 中存储内容。例如,您可以在 /builds/tools 中存储工具,以便在 CI 执行期间使用它们。我们 强烈 不建议这样做,您不应在 Builds Directory 中存储任何内容。极狐GitLab Runner 应该完全控制它,并且在这种情况下不提供稳定性。如果您的 CI 需要依赖项,您必须在其他地方安装它们。
清理 Git 配置
History
- 引入于极狐GitLab Runner 17.10。
在每次构建的开始和结束时,极狐GitLab Runner 会从存储库及其子模块中删除以下文件:
- Git 锁文件 ({index,shallow,HEAD,config}.lock)
- Post-checkout hooks (hooks/post-checkout)
如果您启用 clean_git_config,以下附加文件或目录将从存储库、其子模块和 Git 模板目录中删除:
- .git/config 文件
- .git/hooks 目录
此清理可防止在作业之间缓存自定义、临时或潜在的恶意 Git 配置。
在极狐GitLab Runner 17.10 之前,清理行为有所不同:
- Git 锁文件和 Post-checkout hooks 清理仅在作业开始时发生,而不是在作业结束时。
- 其他 Git 配置(现在由 clean_git_config 控制)除非设置 FF_ENABLE_JOB_CLEANUP,否则不会删除。当您设置此标志时,仅删除主存储库的 .git/config,而不是子模块配置。
clean_git_config 设置默认为 true。但在以下情况下默认为 false:
显式的 clean_git_config 配置优先于默认设置。
[runners.referees] 部分
使用极狐GitLab Runner 裁判将额外的作业监控数据传递到极狐GitLab。裁判是 runner 管理器中的工作者,他们查询并收集与作业相关的其他数据。结果作为作业产物上传到极狐GitLab。
使用 Metrics Runner 裁判
如果运行作业的机器或容器暴露 Prometheus 指标,极狐GitLab Runner 可以在整个作业期间查询 Prometheus 服务器。接收到指标后,它们作为作业产物上传,可以用于以后的分析。
只有 docker-machine 执行器 支持裁判。
为极狐GitLab Runner 配置 Metrics Runner 裁判
在 [[runner]] 部分的 config.toml 文件中定义 [runner.referees] 和 [runner.referees.metrics],并添加以下字段:
设置 | 描述 |
---|---|
prometheus_address | 收集极狐GitLab Runner 实例指标的服务器。作业完成时,runner 管理器必须可以访问它。 |
query_interval | 定义为间隔(以秒为单位)的查询作业关联的 Prometheus 实例的时间序列数据的频率。 |
queries | 为每个间隔执行的 PromQL 查询的数组。 |
以下是 node_exporter 指标的完整配置示例:
toml1[[runners]] 2 [runners.referees] 3 [runners.referees.metrics] 4 prometheus_address = "http://localhost:9090" 5 query_interval = 10 6 metric_queries = [ 7 "arp_entries:rate(node_arp_entries{{selector}}[{interval}])", 8 "context_switches:rate(node_context_switches_total{{selector}}[{interval}])", 9 "cpu_seconds:rate(node_cpu_seconds_total{{selector}}[{interval}])", 10 "disk_read_bytes:rate(node_disk_read_bytes_total{{selector}}[{interval}])", 11 "disk_written_bytes:rate(node_disk_written_bytes_total{{selector}}[{interval}])", 12 "memory_bytes:rate(node_memory_MemTotal_bytes{{selector}}[{interval}])", 13 "memory_swap_bytes:rate(node_memory_SwapTotal_bytes{{selector}}[{interval}])", 14 "network_tcp_active_opens:rate(node_netstat_Tcp_ActiveOpens{{selector}}[{interval}])", 15 "network_tcp_passive_opens:rate(node_netstat_Tcp_PassiveOpens{{selector}}[{interval}])", 16 "network_receive_bytes:rate(node_network_receive_bytes_total{{selector}}[{interval}])", 17 "network_receive_drops:rate(node_network_receive_drop_total{{selector}}[{interval}])", 18 "network_receive_errors:rate(node_network_receive_errs_total{{selector}}[{interval}])", 19 "network_receive_packets:rate(node_network_receive_packets_total{{selector}}[{interval}])", 20 "network_transmit_bytes:rate(node_network_transmit_bytes_total{{selector}}[{interval}])", 21 "network_transmit_drops:rate(node_network_transmit_drop_total{{selector}}[{interval}])", 22 "network_transmit_errors:rate(node_network_transmit_errs_total{{selector}}[{interval}])", 23 "network_transmit_packets:rate(node_network_transmit_packets_total{{selector}}[{interval}])" 24 ]
指标查询采用 canonical_name:query_string 格式。查询字符串支持两个在执行期间被替换的变量:
设置 | 描述 |
---|---|
{selector} | 用于选择由特定极狐GitLab Runner 实例在 Prometheus 中生成的指标的 label_name=label_value 对。 |
{interval} | 使用此裁判的 [runners.referees.metrics] 配置中的 query_interval 参数替换。 |
例如,使用 docker-machine 执行器的共享极狐GitLab Runner 环境,其 {selector} 可能类似于 node=shared-runner-123。