Kubernetes 执行器

使用 Kubernetes 执行器将 Kubernetes 集群用于您的构建。执行器调用 Kubernetes 集群 API，并为每个极狐GitLab CI 作业创建一个 Pod。

Kubernetes 执行器将构建分为多个步骤：

1. 准备：在 Kubernetes 集群上创建 Pod。此步骤会创建构建和服务运行所需的容器。
2. 预构建：克隆、恢复缓存，并下载之前阶段的产物。此步骤在 Pod 中的一个特殊容器上运行。
3. 构建：用户构建。
4. 构建后：创建缓存，将产物上传至极狐GitLab。此步骤同样使用 Pod 中的特殊容器。

Runner 如何创建 Kubernetes Pod#

下图展示了极狐GitLab 实例与托管在 Kubernetes 集群上的 Runner 之间的交互。Runner 调用 Kubernetes API 在集群上创建 Pod。

对于 .gitlab-ci.yml 或 config.toml 文件中定义的每个 service，Pod 由以下容器组成：

• 一个定义为 build 的构建容器。
• 一个定义为 helper 的辅助容器。
• 一个服务容器，其命名遵循以下逻辑：
  • 如果服务具有一个有效的 DNS 标签名称别名，且该别名未被其他服务容器使用，则使用该别名作为容器名称。
  • 如果没有可用的有效别名，则容器命名为 svc-N，其中 N 是从 0 开始的顺序索引。

服务和容器在同一个 Kubernetes Pod 中运行，并共享相同的 localhost 地址。以下限制适用：

• 服务可通过其 DNS 名称访问。如果您使用的是旧版本，则必须使用 localhost。
• 不能同时使用多个占用相同端口的服务。例如，不能同时运行两个 mysql 服务。

Rendering chart...

图中的交互适用于任何 Kubernetes 集群。例如，托管在主要公有云提供商上的交钥匙解决方案，或私有化部署的 Kubernetes 安装。

连接到 Kubernetes API#

使用以下选项连接到 Kubernetes API。所提供的用户账户必须具有在指定命名空间中创建、列出和附加到 Pod 的权限。

如果您在 Kubernetes 集群中运行 GitLab Runner，请省略这些字段，以便 GitLab Runner 自动发现 Kubernetes API。

如果您在集群外部运行 GitLab Runner，这些设置可确保 GitLab Runner 能够访问集群上的 Kubernetes API。您可以指定带有认证详细信息的 host，或使用 context 引用 kubectl 配置中的特定上下文。

为 Kubernetes API 调用设置 bearer token#

要为创建 Pod 的 API 调用设置 bearer token，请使用 KUBERNETES_BEARER_TOKEN 变量。这允许项目所有者使用项目密钥变量来指定 bearer token。

指定 bearer token 时，您必须设置 Host 配置项。

yaml
variables:
  KUBERNETES_BEARER_TOKEN: thebearertokenfromanothernamespace

配置 Runner API 权限#

要配置核心 API 组的权限，请更新 GitLab Runner Helm Chart 的 values.yml 文件。

您可以：

• 将 rbac.create 设置为 true。
• 在 values.yml 文件中指定具有以下权限的服务账户 serviceAccount.name: <service_account_name>。

您可以使用以下 YAML 角色定义来创建具有所需权限的角色。

yaml
1apiVersion: rbac.authorization.k8s.io/v1
2kind: Role
3metadata:
4  name: gitlab-runner
5  namespace: default
6rules:
7- apiGroups: ["apps"]
8  resources: ["deployments"]
9  verbs:
10  - "create" # Required when `kubernetes.autoscaler`
11  - "delete" # Required when `kubernetes.autoscaler`
12  - "get" # Required when `kubernetes.autoscaler`
13  - "list" # Required when `kubernetes.autoscaler`
14  - "update" # Required when `kubernetes.autoscaler`
15- apiGroups: [""]
16  resources: ["events"]
17  verbs:
18  - "list" # Required when `print_pod_warning_events=true`
19  - "watch" # Required when `FF_PRINT_POD_EVENTS=true`
20- apiGroups: [""]
21  resources: ["namespaces"]
22  verbs:
23  - "create" # Required when `kubernetes.NamespacePerJob=true`
24  - "delete" # Required when `kubernetes.NamespacePerJob=true`
25- apiGroups: ["policy"]
26  resources: ["poddisruptionbudgets"]
27  verbs:
28  - "create" # Required when `pod_disruption_budget=true`
29  - "get" # Required when `pod_disruption_budget=true`
30- apiGroups: [""]
31  resources: ["pods"]
32  verbs:
33  - "create"
34  - "delete"
35  - "get"
36  - "list" # Required when using Informers (https://docs.gitlab.com/runner/executors/kubernetes/#informers)
37  - "watch" # Required when `FF_KUBERNETES_HONOR_ENTRYPOINT=true`, `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`, using Informers (https://docs.gitlab.com/runner/executors/kubernetes/#informers)
38- apiGroups: [""]
39  resources: ["pods/attach"]
40  verbs:
41  - "create" # Required when `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
42  - "delete" # Required when `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
43  - "get" # Required when `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
44  - "patch" # Required when `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
45- apiGroups: [""]
46  resources: ["pods/exec"]
47  verbs:
48  - "create"
49  - "delete"
50  - "get"
51  - "patch"
52- apiGroups: [""]
53  resources: ["pods/log"]
54  verbs:
55  - "get" # Required when `FF_KUBERNETES_HONOR_ENTRYPOINT=true`, `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`, `FF_WAIT_FOR_POD_TO_BE_REACHABLE=true`
56  - "list" # Required when `FF_KUBERNETES_HONOR_ENTRYPOINT=true`, `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
57- apiGroups: ["scheduling.k8s.io"]
58  resources: ["priorityclasses"]
59  verbs:
60  - "create" # Required when `kubernetes.autoscaler`
61  - "get" # Required when `kubernetes.autoscaler`
62- apiGroups: [""]
63  resources: ["secrets"]
64  verbs:
65  - "create"
66  - "delete"
67  - "get"
68  - "update"
69- apiGroups: [""]
70  resources: ["serviceaccounts"]
71  verbs:
72  - "get"
73- apiGroups: [""]
74  resources: ["services"]
75  verbs:
76  - "create"
77  - "get"

其他详细信息：

• event 权限仅在极狐GitLab 16.2.1 及更高版本中需要。
• namespace 权限仅在通过 namespace_per_job 启用命名空间隔离时需要。
• pods/log 权限仅在以下任一场景成立时需要：
  • FF_KUBERNETES_HONOR_ENTRYPOINT 功能标志已启用。
  • 当 CI_DEBUG_SERVICES 变量设置为 true 时，FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY 功能标志被禁用。
  • FF_WAIT_FOR_POD_TO_BE_REACHABLE 功能标志已启用。

Informer#

在 GitLab Runner 17.9.0 及更高版本中，Kubernetes Informer 会跟踪构建 Pod 的变更。这有助于执行器更快地检测到变更。

Informer 需要针对 pods 的 list 和 watch 权限。当执行器启动构建时，它会检查 Kubernetes API 中的权限。如果所有权限均已授予，执行器将使用 Informer。如果缺少任何权限，GitLab Runner 会记录一条警告。构建将继续，并使用之前的机制来跟踪构建 Pod 的状态和变更。

配置设置#

在 config.toml 文件中使用以下设置来配置 Kubernetes 执行器。

CPU 请求和限制#

内存请求和限制#

辅助容器内存大小建议#

为获得最佳性能，请根据工作负载需求设置辅助容器内存限制：

• 带缓存和产物生成的工作负载：最低 250 MiB
• 不带缓存/产物的基础工作负载：可能可以在较低限制（128-200 MiB）下运行

基础配置示例：

toml
1[[runners]]
2  executor = "kubernetes"
3  [runners.kubernetes]
4    helper_memory_limit = "250Mi"
5    helper_memory_request = "250Mi"
6    helper_memory_limit_overwrite_max_allowed = "1Gi"

作业级内存覆盖：

使用 KUBERNETES_HELPER_MEMORY_LIMIT 变量为特定作业调整内存，无需管理员更改：

yaml
job_with_higher_helper_memory_limit:
  variables:
    KUBERNETES_HELPER_MEMORY_LIMIT: "512Mi"
  script:

此方法允许开发者按作业优化资源使用，同时通过 helper_memory_limit_overwrite_max_allowed 维持集群范围的限制。

存储请求和限制#

其他 config.toml 设置#

配置示例#

以下示例展示了 Kubernetes 执行器的 config.toml 文件配置示例。

toml
1concurrent = 4
2
3[[runners]]
4  name = "myRunner"
5  url = "https://gitlab.com/ci"
6  token = "......"
7  executor = "kubernetes"
8  [runners.kubernetes]
9    host = "https://45.67.34.123:4892"
10    cert_file = "/etc/ssl/kubernetes/api.crt"
11    key_file = "/etc/ssl/kubernetes/api.key"
12    ca_file = "/etc/ssl/kubernetes/ca.crt"
13    namespace = "gitlab"
14    namespace_overwrite_allowed = "ci-.*"
15    bearer_token_overwrite_allowed = true
16    privileged = true
17    cpu_limit = "1"
18    memory_limit = "1Gi"
19    service_cpu_limit = "1"
20    service_memory_limit = "1Gi"
21    helper_cpu_limit = "500m"
22    helper_memory_limit = "100Mi"
23    poll_interval = 5
24    poll_timeout = 3600
25    dns_policy = "cluster-first"
26    priority_class_name = "priority-1"
27    logs_base_dir = "/tmp"
28    scripts_base_dir = "/tmp"
29    [runners.kubernetes.node_selector]
30      gitlab = "true"
31    [runners.kubernetes.node_tolerations]
32      "node-role.kubernetes.io/master" = "NoSchedule"
33      "custom.toleration=value" = "NoSchedule"
34      "empty.value=" = "PreferNoSchedule"
35      "onlyKey" = ""

使用暂停 Pod 预热集群容量#

您可以配置 Kubernetes 执行器来维护暂停 Pod，以预热集群容量。当作业启动时，低优先级的暂停 Pod 会被抢占，作业 Pod 会立即调度到现有节点上。此配置减少了等待集群自动扩缩器配置新节点所带来的作业启动延迟。

暂停 Pod 的工作原理#

1. Runner 根据配置的策略创建一个用于管理暂停 Pod 的 Deployment。
2. 暂停 Pod 使用优先级较低的优先级类，因此当更高优先级的作业 Pod 需要资源时，Kubernetes 会抢占它们。
3. 当暂停 Pod 被抢占时，作业 Pod 会立即取代其位置。
4. Deployment 会重新创建被抢占的暂停 Pod，这可能会触发集群自动扩缩器添加新节点。

配置暂停 Pod#

要启用暂停 Pod，请在您的 config.toml 中添加一个 [runners.kubernetes.autoscaler] 部分：

toml
1[[runners]]
2  name = "kubernetes-runner"
3  executor = "kubernetes"
4  [runners.kubernetes]
5    namespace = "gitlab-runner"
6    cpu_request = "500m"
7    memory_request = "1Gi"
8    [runners.kubernetes.autoscaler]
9      max_pause_pods = 10
10      [[runners.kubernetes.autoscaler.policy]]
11        idle_count = 5
12        periods = ["* 8-17 * * mon-fri"]
13        timezone = "UTC"
14      [[runners.kubernetes.autoscaler.policy]]
15        idle_count = 0
16        periods = ["* * * * *"]

自动扩缩器设置#

用于抢占的优先级类#

要使暂停 Pod 被作业 Pod 抢占，它们必须具有较低的优先级。默认情况下，Runner 会自动创建一个名为 gitlab-runner-idle-capacity 的 PriorityClass，优先级为 -1。由于没有优先级类的 Pod 使用优先级 0，作业 Pod 将抢占暂停 Pod。

要改用自定义 PriorityClass，请在配置中指定：

toml
[runners.kubernetes.autoscaler]
  pause_pod_priority_class_name = "my-custom-priority-class"

如果您的作业 Pod 使用自定义优先级类，请确保其值高于暂停 Pod 的优先级类。

策略设置#

您可以定义多个策略。根据当前时间，使用最后一个匹配的策略。

Cron 语法#

periods 设置使用包含五个字段的标准 cron 格式：

plaintext
1 ┌────────── minute (0 - 59)
2 │ ┌──────── hour (0 - 23)
3 │ │ ┌────── day of month (1 - 31)
4 │ │ │ ┌──── month (1 - 12)
5 │ │ │ │ ┌── day of week (0 - 7, where 0 and 7 are Sunday, or MON-SUN)
6 * * * * *

示例：

创建优先级类#

暂停 Pod 需要优先级低于作业 Pod 的优先级类。在配置暂停 Pod 之前，请先创建优先级类：

yaml
1apiVersion: scheduling.k8s.io/v1
2kind: PriorityClass
3metadata:
4  name: pause-pods
5value: -10
6globalDefault: false
7description: "Low priority class for runner pause pods"

所需的 RBAC 权限#

要使用暂停 Pod，请为 Runner 服务账户配置额外权限以管理 Deployments 和 PriorityClasses：

yaml
1- apiGroups: ["apps"]
2  resources: ["deployments"]
3  verbs: ["get", "list", "create", "update", "delete"]
4- apiGroups: ["scheduling.k8s.io"]
5  resources: ["priorityclasses"]
6  verbs: ["get", "create"]

配置执行器服务账户#

要配置执行器服务账户，您可以设置 KUBERNETES_SERVICE_ACCOUNT 环境变量或使用 --kubernetes-service-account 标志。

Pod 和容器#

您可以配置 Pod 和容器来控制作业的执行方式。

作业 Pod 的默认标记#

作业 Pod 的默认注解#

运行作业的 Pod 上默认添加以下注解：

要覆盖默认注解，请在 GitLab Runner 配置中使用 pod_annotations。 您还可以在 .gitlab-ci.yml 文件中为每个 CI/CD 作业覆盖注解。

Pod 生命周期#

Pod 的生命周期可能受到以下因素影响：

• 在 TOML 配置文件中设置 pod_termination_grace_period_seconds 属性。 Pod 上运行的进程可以在 TERM 信号发送后继续运行给定的时长。 如果 Pod 在此时间段后仍未成功终止，则会发送 kill 信号。
• 启用 FF_USE_POD_ACTIVE_DEADLINE_SECONDS 功能标志。 启用后，当作业超时时，运行 CI/CD 作业的 Pod 会被标记为失败，所有关联容器都会被终止。要让作业先在极狐GitLab 上超时， 请将 activeDeadlineSeconds 设置为 configured timeout + 1 second。

为保护作业 Pod 免受自愿性干扰（例如节点排空和集群升级）的影响，请开启 pod_disruption_budget 选项。

开启后，此设置会为每个作业 Pod 创建一个 PodDisruptionBudget，并设置 minAvailable: 1。此操作可防止 Kubernetes 驱逐 API 在自愿性干扰期间驱逐该 Pod。

toml
[runners.kubernetes]
  pod_disruption_budget = true

PodDisruptionBudget：

• 当作业 Pod 通过 Kubernetes 所有者引用被删除时，会自动删除。
• 无法防止非自愿性干扰，例如节点故障或内存不足导致的终止。
• 需要额外的 RBAC 权限。详情请参见配置 Runner API 权限。

覆盖 Pod 容忍度#

要覆盖 Kubernetes Pod 容忍度：

1. 在 config.toml 或 Helm values.yaml 文件中，为 node_tolerations_overwrite_allowed 定义一个正则表达式，以启用对 CI 作业 Pod 容忍度的覆盖。 此正则表达式用于验证以 KUBERNETES_NODE_TOLERATIONS_ 开头的 CI 变量名的值。

   toml
   1runners:
   2 ...
   3 config: |
   4   [[runners]]
   5     [runners.kubernetes]
   6       node_tolerations_overwrite_allowed = ".*"

2. 在 .gitlab-ci.yml 文件中，定义一个或多个 CI 变量以覆盖 CI 作业 Pod 容忍度。

   yaml
   1variables:
   2  KUBERNETES_NODE_TOLERATIONS_1: 'node-role.kubernetes.io/master:NoSchedule'
   3  KUBERNETES_NODE_TOLERATIONS_2: 'custom.toleration=value:NoSchedule'
   4  KUBERNETES_NODE_TOLERATIONS_3: 'empty.value=:PreferNoSchedule'
   5  KUBERNETES_NODE_TOLERATIONS_4: 'onlyKey'
   6  KUBERNETES_NODE_TOLERATIONS_5: '' # tolerate all taints

覆盖 Pod 标记#

要为每个 CI/CD 作业覆盖 Kubernetes Pod 标记：

1. 在 .config.yaml 文件中，为 pod_labels_overwrite_allowed 定义一个正则表达式。

2. 在 .gitlab-ci.yml 文件中，将 KUBERNETES_POD_LABELS_* 变量设置为 key=value 的值。Pod 标记将被覆盖为 key=value。您可以应用多个值：

   yaml
   variables:
     KUBERNETES_POD_LABELS_1: "Key1=Val1"
     KUBERNETES_POD_LABELS_2: "Key2=Val2"
     KUBERNETES_POD_LABELS_3: "Key3=Val3"

覆盖 Pod 注解#

要为每个 CI/CD 作业覆盖 Kubernetes Pod 注解：

1. 在 .config.yaml 文件中，为 pod_annotations_overwrite_allowed 定义一个正则表达式。

2. 在 .gitlab-ci.yml 文件中，设置 KUBERNETES_POD_ANNOTATIONS_* 变量，并使用 key=value 作为值。 Pod 注解将被覆盖为 key=value。您可以指定多个注解：

   yaml
   variables:
     KUBERNETES_POD_ANNOTATIONS_1: "Key1=Val1"
     KUBERNETES_POD_ANNOTATIONS_2: "Key2=Val2"
     KUBERNETES_POD_ANNOTATIONS_3: "Key3=Val3"

在下面的示例中，设置了 pod_annotations 和 pod_annotations_overwrite_allowed。 此配置允许覆盖在 config.toml 中配置的任何 pod_annotations。

toml
1[[runners]]
2  # usual configuration
3  executor = "kubernetes"
4  [runners.kubernetes]
5    image = "alpine"
6    pod_annotations_overwrite_allowed = ".*"
7    [runners.kubernetes.pod_annotations]
8      "Key1" = "Val1"
9      "Key2" = "Val2"
10      "Key3" = "Val3"
11      "Key4" = "Val4"

覆盖生成的 Pod 规格#

此功能处于测试版阶段。强烈建议您先在测试 Kubernetes 集群上使用此功能，然后再在生产集群上使用。要使用此功能，您必须启用 FF_USE_ADVANCED_POD_SPEC_CONFIGURATION 功能标志。

要在该功能正式发布前提供反馈，请在 issue 556286 上留言。

要修改由 Runner Manager 生成的 PodSpec，请在 config.toml 文件中使用 pod_spec 设置。

有关 Runner Operator 的特定配置，请参见补丁结构。

pod_spec 设置：

• 覆盖并补全生成的 Pod 规格中的字段。
• 覆盖可能在您的 config.toml 中 [runners.kubernetes] 下已设置的配置值。

您可以配置多个 pod_spec 设置。

您不能在同一个 pod_spec 配置中同时设置 patch_path 和 patch，否则会发生错误。

在 config.toml 中配置多个 pod_spec 的示例：

toml
1[[runners]]
2  [runners.kubernetes]
3    [[runners.kubernetes.pod_spec]]
4      name = "hostname"
5      patch = '''
6        hostname: "custom-pod-hostname"
7      '''
8      patch_type = "merge"
9    [[runners.kubernetes.pod_spec]]
10      name = "subdomain"
11      patch = '''
12        subdomain: "subdomain"
13      '''
14      patch_type = "strategic"
15    [[runners.kubernetes.pod_spec]]
16      name = "terminationGracePeriodSeconds"
17      patch = '''
18        [{"op": "replace", "path": "/terminationGracePeriodSeconds", "value": 60}]
19      '''
20      patch_type = "json"

合并补丁策略#

merge 补丁策略会对现有的 PodSpec 应用键值替换。 如果使用此策略，config.toml 中的 pod_spec 配置会在最终 PodSpec 对象生成前覆盖其中的值。由于值会被完全覆盖，您应谨慎使用此补丁策略。

使用 merge 补丁策略的 pod_spec 配置示例：

toml
1concurrent = 1
2check_interval = 1
3log_level = "debug"
4shutdown_timeout = 0
5
6[session_server]
7  session_timeout = 1800
8
9[[runners]]
10  name = ""
11  url = "https://gitlab.example.com"
12  id = 0
13  token = "__REDACTED__"
14  token_obtained_at = 0001-01-01T00:00:00Z
15  token_expires_at = 0001-01-01T00:00:00Z
16  executor = "kubernetes"
17  shell = "bash"
18  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true", "CUSTOM_VAR=value"]
19  [runners.kubernetes]
20    image = "alpine"
21    ...
22    [[runners.kubernetes.pod_spec]]
23      name = "build envvars"
24      patch = '''
25        containers:
26        - env:
27          - name: env1
28            value: "value1"
29          - name: env2
30            value: "value2"
31          name: build
32      '''
33      patch_type = "merge"

使用此配置，最终的 PodSpec 只有一个名为 build 的容器，并带有两个环境变量 env1 和 env2。上面的示例会导致相关 CI 作业失败，原因如下：

• helper 容器规格被移除。
• build 容器规格丢失了由 GitLab Runner 设置的所有必要配置。

为防止作业失败，在此示例中，pod_spec 必须包含由 GitLab Runner 生成的未更改的属性。

JSON 补丁策略#

json 补丁策略使用 JSON Patch 规范来控制要更新的 PodSpec 对象和数组。您不能对 array 属性使用此策略。

使用 json 补丁策略的 pod_spec 配置示例。在此配置中，一个新的 key: value pair 被添加到现有的 nodeSelector 中。现有值不会被覆盖。

toml
1concurrent = 1
2check_interval = 1
3log_level = "debug"
4shutdown_timeout = 0
5
6[session_server]
7  session_timeout = 1800
8
9[[runners]]
10  name = ""
11  url = "https://gitlab.example.com"
12  id = 0
13  token = "__REDACTED__"
14  token_obtained_at = 0001-01-01T00:00:00Z
15  token_expires_at = 0001-01-01T00:00:00Z
16  executor = "kubernetes"
17  shell = "bash"
18  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true", "CUSTOM_VAR=value"]
19  [runners.kubernetes]
20    image = "alpine"
21    ...
22    [[runners.kubernetes.pod_spec]]
23      name = "val1 node"
24      patch = '''
25        [{ "op": "add", "path": "/nodeSelector", "value": { key1: "val1" } }]
26      '''
27      patch_type = "json"

策略性补丁策略#

此 strategic 补丁策略使用现有的 patchStrategy，将其应用于 PodSpec 对象的每个字段。

使用 strategic 补丁策略的 pod_spec 配置示例。在此配置中，构建容器上设置了一个 resource request。

toml
1concurrent = 1
2check_interval = 1
3log_level = "debug"
4shutdown_timeout = 0
5
6[session_server]
7  session_timeout = 1800
8
9[[runners]]
10  name = ""
11  url = "https://gitlab.example.com"
12  id = 0
13  token = "__REDACTED__"
14  token_obtained_at = 0001-01-01T00:00:00Z
15  token_expires_at = 0001-01-01T00:00:00Z
16  executor = "kubernetes"
17  shell = "bash"
18  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true", "CUSTOM_VAR=value"]
19  [runners.kubernetes]
20    image = "alpine"
21    ...
22    [[runners.kubernetes.pod_spec]]
23      name = "cpu request 500m"
24      patch = '''
25        containers:
26        - name: build
27          resources:
28            requests:
29              cpu: "500m"
30      '''
31      patch_type = "strategic"

使用此配置，构建容器上会设置一个 resource request。

最佳实践#

• 在生产环境中部署之前，先在测试环境中测试添加的 pod_spec。
• 确保 pod_spec 配置不会对 GitLab Runner 生成的规格产生负面影响。
• 不要对复杂的 Pod 规格更新使用 merge 补丁策略。
• 在配置可用的情况下，尽可能使用 config.toml。例如，以下配置会用自定义 pod_spec 中设置的环境变量替换由 GitLab Runner 设置的第一个环境变量，而不是将环境变量集添加到现有列表中。

toml
1concurrent = 1
2check_interval = 1
3log_level = "debug"
4shutdown_timeout = 0
5
6[session_server]
7  session_timeout = 1800
8
9[[runners]]
10  name = ""
11  url = "https://gitlab.example.com"
12  id = 0
13  token = "__REDACTED__"
14  token_obtained_at = 0001-01-01T00:00:00Z
15  token_expires_at = 0001-01-01T00:00:00Z
16  executor = "kubernetes"
17  shell = "bash"
18  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true", "CUSTOM_VAR=value"]
19  [runners.kubernetes]
20    image = "alpine"
21    ...
22    [[runners.kubernetes.pod_spec]]
23      name = "build envvars"
24      patch = '''
25        containers:
26        - env:
27          - name: env1
28            value: "value1"
29          name: build
30      '''
31      patch_type = "strategic"

通过修改 Pod Spec 为每个构建作业创建 PVC#

要为每个构建作业创建一个 PersistentVolumeClaim，请务必查看如何启用 Pod Spec 功能。

Kubernetes 允许您创建一个附加到 Pod 生命周期的临时 PersistentVolumeClaim。 如果您的 Kubernetes 集群上启用了动态供应，则此方法可行。 每个 PVC 都可以请求一个新的 Volume。该卷也与 Pod 的生命周期绑定。

启用动态供应后，可以按如下方式修改 config.toml 以创建临时 PVC：

toml
1[[runners.kubernetes.pod_spec]]
2  name = "ephemeral-pvc"
3  patch = '''
4    containers:
5    - name: build
6      volumeMounts:
7      - name: builds
8        mountPath: /builds
9    - name: helper
10      volumeMounts:
11      - name: builds
12        mountPath: /builds
13    volumes:
14    - name: builds
15      ephemeral:
16        volumeClaimTemplate:
17          spec:
18            storageClassName: <The Storage Class that will dynamically provision a Volume>
19            accessModes: [ ReadWriteOnce ]
20            resources:
21              requests:
22                storage: 1Gi
23  '''

为 Pod 设置安全策略#

在 config.toml 中配置安全上下文，为构建 Pod 设置安全策略。

使用以下选项：

config.toml 中的 Pod 安全上下文示例：

toml
1concurrent = %(concurrent)s
2check_interval = 30
3[[runners]]
4  name = "myRunner"
5  url = "gitlab.example.com"
6  executor = "kubernetes"
7  [runners.kubernetes]
8    helper_image = "gitlab-registry.example.com/helper:latest"
9    [runners.kubernetes.pod_security_context]
10      run_as_non_root = true
11      run_as_user = 59417
12      run_as_group = 59417
13      fs_group = 59417

移除旧的 Runner Pod#

有时旧的 Runner Pod 不会被清理。当 Runner Manager 被错误关闭时，可能会发生这种情况。

要处理这种情况，您可以使用 GitLab Runner Pod Cleanup 应用程序来安排清理旧 Pod。有关更多信息，请参见：

• GitLab Runner Pod Cleanup 项目的 README。
• GitLab Runner Pod Cleanup 文档。

为容器设置安全策略#

在 config.toml 执行器中配置容器安全上下文，为构建、辅助或服务 Pod 设置容器安全策略。

使用以下选项：

在 config.toml 的以下示例中，安全上下文配置：

• 设置 Pod 安全上下文。
• 为构建和辅助容器覆盖 run_as_user 和 run_as_group。
• 指定所有服务容器从 Pod 安全上下文继承 run_as_user 和 run_as_group。

toml
1concurrent = 4
2check_interval = 30
3[[runners]]
4  name = "myRunner"
5  url = "gitlab.example.com"
6  executor = "kubernetes"
7  [runners.kubernetes]
8    helper_image = "gitlab-registry.example.com/helper:latest"
9    [runners.kubernetes.pod_security_context]
10      run_as_non_root = true
11      run_as_user = 59417
12      run_as_group = 59417
13      fs_group = 59417
14    [runners.kubernetes.init_permissions_container_security_context]
15      run_as_user = 1000
16      run_as_group = 1000
17    [runners.kubernetes.build_container_security_context]
18      run_as_user = 65534
19      run_as_group = 65534
20      [runners.kubernetes.build_container_security_context.capabilities]
21        add = ["NET_ADMIN"]
22    [runners.kubernetes.helper_container_security_context]
23      run_as_user = 1000
24      run_as_group = 1000
25    [runners.kubernetes.service_container_security_context]
26      run_as_user = 1000
27      run_as_group = 1000

设置 seccomp 和 AppArmor 配置文件#

您可以使用嵌套的 seccomp_profile 和 app_armor_profile 配置部分，为构建 Pod 配置 seccomp 和 AppArmor 配置文件。

这些字段用原生 Kubernetes API 字段取代了已弃用的基于注解的方法（container.apparmor.security.beta.kubernetes.io 和 seccomp.security.alpha.kubernetes.io 注解）。

在以下示例中，为构建容器将 seccomp 和 AppArmor 配置文件设置为 Unconfined，以启用无根镜像构建（例如，使用 BuildKit）：

toml
1concurrent = 4
2check_interval = 30
3[[runners]]
4  name = "myRunner"
5  url = "gitlab.example.com"
6  executor = "kubernetes"
7  [runners.kubernetes]
8    [runners.kubernetes.pod_security_context]
9      run_as_non_root = true
10      run_as_user = 1001
11      [runners.kubernetes.pod_security_context.seccomp_profile]
12        type = "RuntimeDefault"
13    [runners.kubernetes.build_container_security_context]
14      run_as_user = 1001
15      run_as_group = 1001
16      [runners.kubernetes.build_container_security_context.seccomp_profile]
17        type = "Unconfined"
18      [runners.kubernetes.build_container_security_context.app_armor_profile]
19        type = "Unconfined"

seccomp_profile 和 app_armor_profile 部分在 pod_security_context 和所有容器安全上下文（build_container_security_context、helper_container_security_context、service_container_security_context、init_permissions_container_security_context）中都可用。

对于 Localhost 类型的配置文件，请指定配置文件路径：

toml
1[runners.kubernetes.build_container_security_context.seccomp_profile]
2  type = "Localhost"
3  localhost_profile = "profiles/my-seccomp-profile.json"
4
5[runners.kubernetes.build_container_security_context.app_armor_profile]
6  type = "Localhost"
7  localhost_profile = "my-apparmor-profile"

设置拉取策略#

在 config.toml 文件中使用 pull_policy 参数来指定一个或多个拉取策略。 该策略控制镜像的获取和更新方式，并适用于构建镜像、辅助镜像和任何服务。

要确定使用哪种策略，请参见关于拉取策略的 Kubernetes 文档。

单个拉取策略：

toml
[runners.kubernetes]
  pull_policy = "never"

多个拉取策略：

toml
[runners.kubernetes]
  # use multiple pull policies
  pull_policy = ["always", "if-not-present"]

当您定义多个策略时，会依次尝试每个策略，直到成功获取镜像。 例如，当您使用 [ always, if-not-present ] 时，如果 always 策略因临时镜像仓库问题而失败，则会使用 if-not-present 策略。

要重试失败的拉取：

toml
[runners.kubernetes]
  pull_policy = ["always", "always"]

极狐GitLab 的命名约定与 Kubernetes 不同。

指定容器能力#

您可以指定要在容器中使用的 Kubernetes 能力。

要指定容器能力，请在 config.toml 中使用 cap_add 和 cap_drop 选项。容器运行时也可以定义默认的能力列表，例如 Docker 或容器中的那些。

Runner 默认会移除一份能力列表。您在 cap_add 选项中列出的能力不会被移除。

config.toml 文件中的配置示例：

toml
1concurrent = 1
2check_interval = 30
3[[runners]]
4  name = "myRunner"
5  url = "gitlab.example.com"
6  executor = "kubernetes"
7  [runners.kubernetes]
8    # ...
9    cap_add = ["SYS_TIME", "IPC_LOCK"]
10    cap_drop = ["SYS_ADMIN"]
11    # ...

指定能力时：

• 用户定义的 cap_drop 优先于用户定义的 cap_add。如果您在两个设置中定义了相同的能力，则只有 cap_drop 中的能力会传递给容器。
• 从传递给容器配置的能力标识符中移除 CAP_ 前缀。例如，如果您想添加或移除 CAP_SYS_TIME 能力，请在配置文件中输入字符串 SYS_TIME。
• Kubernetes 集群的所有者可以定义 PodSecurityPolicy，在其中允许、限制或默认添加特定能力。这些规则优先于任何用户定义的配置。

配置容器用户和群组#

使用 Kubernetes 安全上下文配置来配置容器运行所使用的用户和群组。 管理员可以控制容器安全，并允许作业为特定容器类型指定用户。

配置优先级#

Runner 按以下顺序应用用户配置：

对于构建容器和 service 容器：

1. 容器安全上下文（run_as_user/run_as_group）：管理员控制此配置
2. Pod 安全上下文（run_as_user/run_as_group）：管理员控制 Pod 级默认值
3. 作业配置（.gitlab-ci.yml）：用户控制此配置

对于 helper 容器：

1. Helper 容器安全上下文（run_as_user/run_as_group）：管理员控制此配置
2. Pod 安全上下文（run_as_user/run_as_group）：管理员控制 Pod 级默认值

出于安全隔离考虑，作业配置不适用于 helper 容器。

管理员可以出于安全合规目的覆盖用户指定的值。Helper 容器保持与作业规范的隔离。

Kubernetes 的要求#

Kubernetes 要求用户和群组 ID 使用数值：

• 用户和群组 ID 必须是整数
• SecurityContext 使用 run_as_user 和 run_as_group，并且只接受数值
• 在作业配置中，仅指定用户时使用“1000”，指定用户和群组时使用“1000:1001”

覆盖用户和群组设置#

使用 Pod 级和容器级安全上下文来覆盖用户和群组设置：

toml
1[[runners]]
2  name = "k8s-runner"
3  url = "https://gitlab.example.com"
4  executor = "kubernetes"
5  [runners.kubernetes]
6    allowed_users = ["1000", "1001", "65534"]
7    allowed_groups = ["1001", "65534"]
8
9    # Pod security context - provides defaults for all containers
10    [runners.kubernetes.pod_security_context]
11      run_as_user = 1500
12      run_as_group = 1500
13
14    # Build container security context - overrides pod context
15    [runners.kubernetes.build_container_security_context]
16      run_as_user = 2000
17      run_as_group = 2001
18
19    # Helper container security context - overrides pod context
20    [runners.kubernetes.helper_container_security_context]
21      run_as_user = 3000
22      run_as_group = 3001
23
24    # Service container security context - overrides pod context
25    [runners.kubernetes.service_container_security_context]
26      run_as_user = 4000
27      run_as_group = 4001

在此示例中：

• Pod 安全上下文为没有特定配置的容器设置默认值（1500:1500）
• 容器安全上下文覆盖 Pod 默认值
• 用户 1500、2000、3000 和 4000 不在 allowed_users 列表中，但安全上下文可以使用它们，因为这些值会绕过允许列表验证
• 此能力使管理员可以在 Pod 级和容器级获得不受限制的覆盖控制

您可以独立配置每种容器类型。安全上下文配置 优先于作业配置中的任何用户指定。

在作业配置中指定用户#

作业可以在镜像配置中指定用户：

yaml
1# Job with custom user
2job:
3  image:
4    name: alpine:latest
5    kubernetes:
6      user: "1000"
7  script:
8    - whoami
9    - id
10
11# Job with user and group
12job_with_group:
13  image:
14    name: alpine:latest
15    kubernetes:
16      user: "1000:1001"
17  script:
18    - whoami
19    - id
20
21# Job using environment variable
22job_dynamic:
23  image:
24    name: alpine:latest
25    kubernetes:
26      user: "${CUSTOM_USER_ID}"
27  variables:
28    CUSTOM_USER_ID: "1000"
29  script:
30    - whoami

安全验证#

Runner 仅针对作业级配置，根据允许列表验证用户和群组 ID：

• 根用户/群组（UID/GID 0）：作业配置始终需要明确的允许列表权限
• allowed_users 为空：允许任何非根作业用户
• 指定了 allowed_users：只允许列出的作业用户
• allowed_groups 为空：允许任何非根作业群组
• 指定了 allowed_groups：只允许列出的作业群组
• 安全上下文配置：不根据允许列表进行验证（管理员覆盖）

toml
[runners.kubernetes]
  allowed_users = ["1000", "65534"]
  allowed_groups = ["1001", "65534"]

容器行为与优先级#

安全上下文配置遵循以下优先级顺序（从高到低）：

1. 容器安全上下文
2. Pod 安全上下文
3. 作业配置

toml
1[runners.kubernetes]
2  # Pod-level defaults
3  [runners.kubernetes.pod_security_context]
4    run_as_user = 1500
5    run_as_group = 1500
6
7  # Container-specific overrides
8  [runners.kubernetes.build_container_security_context]
9    run_as_user = 1000
10    run_as_group = 1001
11  [runners.kubernetes.helper_container_security_context]
12    run_as_user = 1000
13    run_as_group = 1001

yaml
job:
  image:
    name: alpine:latest
    kubernetes:
      user: "2000:2001"  # Ignored - container security context uses 1000:1001

每种容器类型都使用其安全上下文配置，并以 Pod 级配置作为回退：

• 构建容器：首先使用 build_container_security_context，然后使用 pod_security_context，最后使用来自 .gitlab-ci.yml 的作业级用户配置。
• Helper 容器：首先使用 helper_container_security_context，然后使用 pod_security_context。不会继承作业级用户配置。
• Service 容器：首先使用 service_container_security_context，然后使用 pod_security_context，最后使用作业级用户配置。

这种方法让您可以精细控制每种容器类型的安全配置，同时 保持 helper 容器与作业规范的隔离。

与 Docker 执行器的对比#

排查用户和群组配置问题#

错误：failed to parse UID 或 failed to parse GID#

• 确保用户 ID 是数值："1000" 而不是 "user"
• 检查格式：用户和群组使用 "1000:1001"
• 不允许使用负值

错误：user "1000" is not in the allowed list#

此错误仅发生在作业级用户配置（.gitlab-ci.yml）中。 请将该用户添加到 Runner 配置中的 allowed_users，或者移除 allowed_users 以允许任何非根作业用户。 安全上下文和 Pod 安全上下文中的用户不会根据允许列表进行验证。

错误：group "1001" is not in the allowed list#

此错误仅发生在作业级群组配置（.gitlab-ci.yml）中。 请将该群组添加到 Runner 配置中的 allowed_groups，或者移除 allowed_groups 以允许任何非根作业群组。 安全上下文和 Pod 安全上下文中的群组不会根据允许列表进行验证。

错误：user "0" is not in the allowed list（根用户被阻止）#

此错误仅发生在作业配置（.gitlab-ci.yml）中指定根用户时。 来自作业配置的根用户（UID 0）需要明确权限：请将 "0" 添加到 allowed_users。 或者，使用安全上下文或 Pod 安全上下文来设置根用户：run_as_user = 0（绕过允许列表验证）。

容器以与预期不同的用户身份运行#

检查 Runner 配置是否使用安全上下文覆盖了作业配置（安全上下文始终优先）。 如果只使用作业配置，请验证 allowed_users 是否包含所需的用户 ID。 安全上下文值不会根据允许列表进行验证，并提供管理员覆盖能力。

覆盖容器资源#

您可以为每个 CI/CD 作业覆盖 Kubernetes CPU 和内存分配。 您可以为构建容器、helper 容器和 service 容器应用请求和限制设置。

要覆盖容器资源，请在 .gitlab-ci.yml 文件中使用以下变量。

这些变量的值受该资源的最大覆盖 设置限制。如果尚未为某个资源设置最大覆盖值，则不会使用该变量。

yaml
1 variables:
2   KUBERNETES_CPU_REQUEST: "3"
3   KUBERNETES_CPU_LIMIT: "5"
4   KUBERNETES_MEMORY_REQUEST: "2Gi"
5   KUBERNETES_MEMORY_LIMIT: "4Gi"
6   KUBERNETES_EPHEMERAL_STORAGE_REQUEST: "512Mi"
7   KUBERNETES_EPHEMERAL_STORAGE_LIMIT: "1Gi"
8
9   KUBERNETES_HELPER_CPU_REQUEST: "3"
10   KUBERNETES_HELPER_CPU_LIMIT: "5"
11   KUBERNETES_HELPER_MEMORY_REQUEST: "2Gi"
12   KUBERNETES_HELPER_MEMORY_LIMIT: "4Gi"
13   KUBERNETES_HELPER_EPHEMERAL_STORAGE_REQUEST: "512Mi"
14   KUBERNETES_HELPER_EPHEMERAL_STORAGE_LIMIT: "1Gi"
15
16   KUBERNETES_SERVICE_CPU_REQUEST: "3"
17   KUBERNETES_SERVICE_CPU_LIMIT: "5"
18   KUBERNETES_SERVICE_MEMORY_REQUEST: "2Gi"
19   KUBERNETES_SERVICE_MEMORY_LIMIT: "4Gi"
20   KUBERNETES_SERVICE_EPHEMERAL_STORAGE_REQUEST: "512Mi"
21   KUBERNETES_SERVICE_EPHEMERAL_STORAGE_LIMIT: "1Gi"

定义 service 列表#

在 config.toml 中定义 service 列表。

toml
1concurrent = 1
2check_interval = 30
3[[runners]]
4  name = "myRunner"
5  url = "gitlab.example.com"
6  executor = "kubernetes"
7  [runners.kubernetes]
8    helper_image = "gitlab-registy.example.com/helper:latest"
9    [[runners.kubernetes.services]]
10      name = "postgres:12-alpine"
11      alias = "db1"
12    [[runners.kubernetes.services]]
13      name = "registry.example.com/svc1"
14      alias = "svc1"
15      entrypoint = ["entrypoint.sh"]
16      command = ["executable","param1","param2"]
17      environment = ["ENV=value1", "ENV2=value2"]

如果 service 环境包含 HEALTHCHECK_TCP_PORT，GitLab Runner 会等待该 service 在该端口上响应，然后才开始运行用户 CI 脚本。您也可以在 .gitlab-ci.yml 的 services 部分中配置 HEALTHCHECK_TCP_PORT 环境变量。

覆盖 service 容器资源#

如果作业有多个 service 容器，您可以为每个 service 容器设置明确的 资源请求和限制。 使用每个 service 中的 variables 属性 来覆盖 .gitlab-ci.yml 中指定的容器资源。

yaml
1  services:
2    - name: redis:5
3      alias: redis5
4      variables:
5        KUBERNETES_SERVICE_CPU_REQUEST: "3"
6        KUBERNETES_SERVICE_CPU_LIMIT: "6"
7        KUBERNETES_SERVICE_MEMORY_REQUEST: "3Gi"
8        KUBERNETES_SERVICE_MEMORY_LIMIT: "6Gi"
9        KUBERNETES_EPHEMERAL_STORAGE_REQUEST: "2Gi"
10        KUBERNETES_EPHEMERAL_STORAGE_LIMIT: "3Gi"
11    - name: postgres:12
12      alias: MY_relational-database.12
13      variables:
14        KUBERNETES_CPU_REQUEST: "2"
15        KUBERNETES_CPU_LIMIT: "4"
16        KUBERNETES_MEMORY_REQUEST: "1Gi"
17        KUBERNETES_MEMORY_LIMIT: "2Gi"
18        KUBERNETES_EPHEMERAL_STORAGE_REQUEST: "1Gi"
19        KUBERNETES_EPHEMERAL_STORAGE_LIMIT: "2Gi"

这些特定设置优先于作业的通用设置。 这些值仍然受该资源的最大覆盖设置 限制。

覆盖 Kubernetes 默认 service account#

要在 .gitlab-ci.yml 文件中为每个 CI/CD 作业覆盖 Kubernetes service account， 请设置变量 KUBERNETES_SERVICE_ACCOUNT_OVERWRITE。

您可以使用此变量来指定附加到命名空间的 service account，这在复杂的 RBAC 配置中可能是必需的。

yaml
variables:
  KUBERNETES_SERVICE_ACCOUNT_OVERWRITE: ci-service-account

为确保 CI 运行期间只使用指定的 service account，请为以下任一项定义正则表达式：

• service_account_overwrite_allowed 设置。
• KUBERNETES_SERVICE_ACCOUNT_OVERWRITE_ALLOWED 环境变量。

如果两者都不设置，则覆盖功能会被禁用。

设置 RuntimeClass#

使用 runtime_class_name 为每个作业容器设置 RuntimeClass。

如果您指定了 RuntimeClass 名称，但未在集群中配置它，或者该功能不受支持， 执行器将无法创建作业。

toml
1concurrent = 1
2check_interval = 30
3[[runners]]
4  name = "myRunner"
5  url = "gitlab.example.com"
6  executor = "kubernetes"
7  [runners.kubernetes]
8    runtime_class_name = "myclass"

更改构建日志和脚本的基础目录#

您可以更改 emptyDir 卷挂载到 Pod 中用于构建日志和脚本的目录。 您可以使用该目录来：

• 使用修改后的镜像运行作业 Pod。
• 以非特权用户身份运行。
• 自定义 SecurityContext 设置。

要更改目录：

• 对于构建日志，设置 logs_base_dir。
• 对于构建脚本，设置 scripts_base_dir。

期望的值是一个表示基础目录的字符串，结尾不带斜杠 （例如，/tmp 或 /mydir/example）。该目录必须已经存在。

此值会被添加到生成的构建日志和脚本路径之前。 例如：

toml
1[[runners]]
2  name = "myRunner"
3  url = "gitlab.example.com"
4  executor = "kubernetes"
5  [runners.kubernetes]
6    logs_base_dir = "/tmp"
7    scripts_base_dir = "/tmp"

此配置将导致 emptyDir 卷挂载在：

• 构建日志的 /tmp/logs-${CI_PROJECT_ID}-${CI_JOB_ID} 而不是默认的 /logs-${CI_PROJECT_ID}-${CI_JOB_ID}。
• 构建脚本的 /tmp/scripts-${CI_PROJECT_ID}-${CI_JOB_ID}。

用户命名空间#

在 Kubernetes 1.30 及更高版本中，您可以使用用户命名空间将容器内运行的用户与主机上的用户隔离开来。 在容器中以 root 身份运行的进程可以在主机上以不同的非特权用户身份运行。

借助用户命名空间，您可以更好地控制使用哪些镜像来运行 CI/CD 作业。 需要额外设置的操作（例如以 root 身份运行）也可以正常工作， 而不会在主机上增加额外的攻击面。

要使用此功能，请确保您的集群已正确配置。 以下示例为 hostUsers 键添加 pod_spec， 并同时禁用特权 Pod 和权限提升：

toml
1[[runners]]
2  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true"]
3  builds_dir = "/tmp/builds"
4[runners.kubernetes]
5  logs_base_dir = "/tmp"
6  scripts_base_dir = "/tmp"
7  privileged = false
8  allowPrivilegeEscalation = false
9[[runners.kubernetes.pod_spec]]
10  name = "hostUsers"
11  patch = '''
12    [{"op": "add", "path": "/hostUsers", "value": false}]
13  '''
14  patch_type = "json"

使用用户命名空间时，您不能使用构建目录（builds_dir）、 构建日志（logs_base_dir）或构建脚本（scripts_base_dir）的默认路径。 即使是容器的 root 用户也没有挂载卷的权限。 他们也无法在容器文件系统的根目录中创建目录。

相反，您可以更改构建日志和脚本的基础目录。 您还可以通过设置 [[runners]].builds_dir 来更改构建目录。

操作系统、架构和 Windows 内核版本#

如果配置的集群中有运行不同操作系统的节点，GitLab Runner 使用 Kubernetes 执行器时可以在不同 操作系统上运行构建。

系统会确定 helper 镜像的操作系统、架构和 Windows 内核版本 （如果适用）。然后，它会将这些参数用于构建的其他方面，例如 要使用的容器或镜像。

下图说明了系统如何检测这些详细信息：

Rendering chart...

以下是影响构建的操作系统、架构和 Windows 内核版本选择的唯一参数。

• helper_image_autoset_arch_and_os 配置
• 来自以下来源的 kubernetes.io/os、kubernetes.io/arch 和 node.kubernetes.io/windows-build 标记选择器：
  • node_selector 配置
  • node_selector 覆盖

其他参数不会影响上述选择过程。 但是，您可以使用 affinity 等参数来进一步限制构建所调度到的节点。

节点#

指定执行构建的节点#

使用 node_selector 选项来指定 Kubernetes 集群中可用于执行构建的节点。 它是 string=string 格式（在环境变量中为 string:string）的 key=value 对。

Runner 使用所提供的信息来确定构建的操作系统和架构。这可以确保 使用正确的 helper 镜像。默认操作系统和架构为 linux/amd64。

您可以使用特定标记来调度具有不同操作系统和架构的节点。

linux/arm64 示例#

toml
1[[runners]]
2  name = "myRunner"
3  url = "gitlab.example.com"
4  executor = "kubernetes"
5
6  [runners.kubernetes.node_selector]
7    "kubernetes.io/arch" = "arm64"
8    "kubernetes.io/os" = "linux"

windows/amd64 示例#

Windows 版 Kubernetes 存在某些限制。 如果您使用进程隔离，还必须使用 node.kubernetes.io/windows-build 标记提供特定的 Windows 构建版本。

toml
1[[runners]]
2  name = "myRunner"
3  url = "gitlab.example.com"
4  executor = "kubernetes"
5
6  # The FF_USE_POWERSHELL_PATH_RESOLVER feature flag has to be enabled for PowerShell
7  # to resolve paths for Windows correctly when Runner is operating in a Linux environment
8  # but targeting Windows nodes.
9  environment = ["FF_USE_POWERSHELL_PATH_RESOLVER=true"]
10
11  [runners.kubernetes.node_selector]
12    "kubernetes.io/arch" = "amd64"
13    "kubernetes.io/os" = "windows"
14    "node.kubernetes.io/windows-build" = "10.0.20348"

覆盖节点选择器#

要覆盖节点选择器：

1. 在 config.toml 或 Helm values.yaml 文件中，启用节点选择器的覆盖：

   toml
   1runners:
   2  ...
   3  config: |
   4    [[runners]]
   5      [runners.kubernetes]
   6        node_selector_overwrite_allowed = ".*"

2. 在 .gitlab-ci.yml 文件中，定义用于覆盖节点选择器的变量：

   yaml
   variables:
     KUBERNETES_NODE_SELECTOR_* = ''

在以下示例中，为了覆盖 Kubernetes 节点架构， 设置在 config.toml 和 .gitlab-ci.yml 文件中进行配置：

toml
1concurrent = 1
2check_interval = 1
3log_level = "debug"
4shutdown_timeout = 0
5
6listen_address = ':9252'
7
8[session_server]
9  session_timeout = 1800
10
11[[runners]]
12  name = ""
13  url = "https://gitlab.com/"
14  id = 0
15  token = "__REDACTED__"
16  token_obtained_at = "0001-01-01T00:00:00Z"
17  token_expires_at = "0001-01-01T00:00:00Z"
18  executor = "kubernetes"
19  shell = "bash"
20  [runners.kubernetes]
21    host = ""
22    bearer_token_overwrite_allowed = false
23    image = "alpine"
24    namespace = ""
25    namespace_overwrite_allowed = ""
26    pod_labels_overwrite_allowed = ""
27    service_account_overwrite_allowed = ""
28    pod_annotations_overwrite_allowed = ""
29    node_selector_overwrite_allowed = "kubernetes.io/arch=.*" # <--- allows overwrite of the architecture

yaml
job:
  image: IMAGE_NAME
  variables:
    KUBERNETES_NODE_SELECTOR_ARCH: 'kubernetes.io/arch=amd64'  # <--- select the architecture

定义节点亲和性列表#

定义要在构建时添加到 Pod 规范的节点亲和性 列表。

toml
1concurrent = 1
2[[runners]]
3  name = "myRunner"
4  url = "gitlab.example.com"
5  executor = "kubernetes"
6  [runners.kubernetes]
7    [runners.kubernetes.affinity]
8      [runners.kubernetes.affinity.node_affinity]
9        [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution]]
10          weight = 100
11          [runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference]
12            [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference.match_expressions]]
13              key = "cpu_speed"
14              operator = "In"
15              values = ["fast"]
16            [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference.match_expressions]]
17              key = "mem_speed"
18              operator = "In"
19              values = ["fast"]
20        [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution]]
21          weight = 50
22          [runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference]
23            [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference.match_expressions]]
24              key = "core_count"
25              operator = "In"
26              values = ["high", "32"]
27            [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference.match_fields]]
28              key = "cpu_type"
29              operator = "In"
30              values = ["arm64"]
31      [runners.kubernetes.affinity.node_affinity.required_during_scheduling_ignored_during_execution]
32        [[runners.kubernetes.affinity.node_affinity.required_during_scheduling_ignored_during_execution.node_selector_terms]]
33          [[runners.kubernetes.affinity.node_affinity.required_during_scheduling_ignored_during_execution.node_selector_terms.match_expressions]]
34            key = "kubernetes.io/e2e-az-name"
35            operator = "In"
36            values = [
37              "e2e-az1",
38              "e2e-az2"
39            ]