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: ["configmaps"]
17  verbs:
18  - "create" # Required when `FF_SUSPENDABLE_ENVIRONMENTS=true`
19  - "delete" # Required when `FF_SUSPENDABLE_ENVIRONMENTS=true`
20  - "get" # Required when `FF_SUSPENDABLE_ENVIRONMENTS=true`
21  - "update" # Required when `FF_SUSPENDABLE_ENVIRONMENTS=true`
22- apiGroups: [""]
23  resources: ["events"]
24  verbs:
25  - "list" # Required when `hostUsers=false`, `print_pod_warning_events=true`
26  - "watch" # Required when `FF_PRINT_POD_EVENTS=true`
27- apiGroups: [""]
28  resources: ["namespaces"]
29  verbs:
30  - "create" # Required when `kubernetes.NamespacePerJob=true`
31  - "delete" # Required when `kubernetes.NamespacePerJob=true`
32  - "get" # Required when `FF_SUSPENDABLE_ENVIRONMENTS=true`
33- apiGroups: [""]
34  resources: ["persistentvolumeclaims"]
35  verbs:
36  - "create" # Required when `FF_SUSPENDABLE_ENVIRONMENTS=true`
37  - "delete" # Required when `FF_SUSPENDABLE_ENVIRONMENTS=true`
38- apiGroups: [""]
39  resources: ["pods"]
40  verbs:
41  - "create"
42  - "delete"
43  - "get"
44  - "list" # Required when using Informers (https://docs.gitlab.com/runner/executors/kubernetes/#informers)
45  - "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)
46- apiGroups: [""]
47  resources: ["pods/attach"]
48  verbs:
49  - "create" # Required when `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
50  - "delete" # Required when `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
51  - "get" # Required when `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
52  - "patch" # Required when `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
53- apiGroups: [""]
54  resources: ["pods/exec"]
55  verbs:
56  - "create"
57  - "delete"
58  - "get"
59  - "patch"
60- apiGroups: [""]
61  resources: ["pods/log"]
62  verbs:
63  - "get" # Required when `FF_CONCRETE=true`, `FF_KUBERNETES_HONOR_ENTRYPOINT=true`, `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`, `FF_WAIT_FOR_POD_TO_BE_REACHABLE=true`
64  - "list" # Required when `FF_KUBERNETES_HONOR_ENTRYPOINT=true`, `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false`
65- apiGroups: ["policy"]
66  resources: ["poddisruptionbudgets"]
67  verbs:
68  - "create" # Required when `pod_disruption_budget=true`
69  - "get" # Required when `pod_disruption_budget=true`
70- apiGroups: ["scheduling.k8s.io"]
71  resources: ["priorityclasses"]
72  verbs:
73  - "create" # Required when `kubernetes.autoscaler`
74  - "get" # Required when `kubernetes.autoscaler`
75- apiGroups: [""]
76  resources: ["secrets"]
77  verbs:
78  - "create"
79  - "delete"
80  - "get"
81  - "update"
82- apiGroups: [""]
83  resources: ["serviceaccounts"]
84  verbs:
85  - "get"
86- apiGroups: [""]
87  resources: ["services"]
88  verbs:
89  - "create"
90  - "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 功能标志已启用。

Informers#

在极狐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 属性。 在发送 TERM 信号后，Pod 上运行的进程可以在给定的时长内继续运行。 如果 Pod 在此时间段后仍未成功终止，则会发送 kill 信号。
• 启用 FF_USE_POD_ACTIVE_DEADLINE_SECONDS 功能标志。 启用后，当作业超时时，运行 CI/CD 作业的 Pod 会被标记为 失败，并且所有关联的容器都会被终止。为了让作业先在极狐GitLab 上超时， activeDeadlineSeconds 被设置为 configured timeout + 1 second。

保护作业 Pod 免遭驱逐#

要保护作业 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 文件中，要启用 CI 作业 Pod 容忍的覆盖，请为 node_tolerations_overwrite_allowed 定义一个正则表达式。 此正则表达式会验证以 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 文件中，使用 key=value 值设置 KUBERNETES_POD_LABELS_* 变量。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 功能标志。

要在该功能正式发布之前提供反馈，请在议题 556286中留下评论。

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

有关 Runner Operator 特定的配置，请参阅 patch 结构。

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 patch 策略会对现有 PodSpec 应用键值替换。如果您使用此策略，config.toml中的 pod_spec 配置覆盖生成前最终 PodSpec 对象中的值。由于这些值会被完全覆盖，因此应谨慎使用此 patch 策略。

使用 merge patch 策略的 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 patch 策略使用 JSON Patch 规范 来控制要更新的 PodSpec 对象和数组。您不能对 array 属性使用此策略。

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

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 patch 策略使用应用于 PodSpec 对象每个字段的现有 patchStrategy。

使用 strategic patch 策略的 pod_spec 配置示例。在此配置中，会在 build 容器上设置 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"

使用此配置后，会在 build 容器上设置 resource request。

最佳实践#

• 在生产环境中部署之前，先在测试环境中测试添加的 pod_spec。
• 确保 pod_spec 配置不会对极狐GitLab Runner 生成的规范产生负面影响。
• 不要对复杂的 Pod 规范更新使用 merge patch 策略。
• 在配置可用的情况下，尽可能使用 config.toml。例如，以下配置会将由极狐GitLab Runner 设置的第一个环境变量替换为自定义 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: 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 执行器中配置容器安全上下文， 为 build、helper 或 service Pod 设置容器安全策略。

使用以下选项：

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

• 设置 Pod 安全上下文。
• 为 build 和 helper 容器覆盖 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 配置节， 为 build Pod 配置 seccomp 和 AppArmor 配置文件。

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

在下面的示例中，build 容器的 seccomp 和 AppArmor 配置文件被设置为 Unconfined， 以启用无 root 镜像构建（例如使用 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 参数来指定单个或多个拉取策略。该策略控制镜像的获取和更新方式，适用于 build 镜像、helper 镜像以及任何服务。

要确定使用哪个策略，请参阅 有关拉取策略的 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 或 container中的列表。

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 按以下顺序应用用户配置：

对于 build 和服务容器：

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：

• Root 用户/组（UID/GID 0）：作业配置始终需要显式的允许名单权限
• 空的 allowed_users：允许任何非 root 作业用户
• 指定了 allowed_users：仅允许列出的作业用户
• 空的 allowed_groups：允许任何非 root 作业组
• 指定了 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 容器：首先使用 build_container_security_context，然后使用 pod_security_context，最后使用 .gitlab-ci.yml中的作业级用户配置。
• Helper 容器：首先使用 helper_container_security_context，然后使用 pod_security_context。不继承作业级用户配置。
• 服务容器：首先使用 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 以允许任何非 root 作业用户。安全上下文和 Pod 安全上下文中的用户不根据允许名单验证。

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

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

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

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

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

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

覆盖容器资源#

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

要覆盖容器资源，请在 .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"

定义服务列表#

在 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    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"]
18    [[runners.kubernetes.services]]
19      name = "redis:7"
20      alias = "cache"
21      suspend_data_path = "/data"  # persists Redis data across suspend/resume cycles

每个 [[runners.kubernetes.services]] 条目支持以下字段：

suspend_data_path的行为取决于您的配置：

• 在可挂起作业（启用了 FF_SUSPENDABLE_ENVIRONMENTS）中，如果未设置 command 或 entrypoint， Runner 会在该路径挂载挂起 PVC 的子目录，以便数据在挂起和 恢复周期中得以保留。
• 如果设置了 command 或 entrypoint，Runner 会改为持久化整个服务容器， 因此此设置不会生效。
• 当为空且未设置 command 或 entrypoint 时，服务容器没有持久存储。

如果服务环境包含 HEALTHCHECK_TCP_PORT，极狐GitLab Runner 会等待服务在该端口上响应，然后再启动用户 CI 脚本。您还可以在 .gitlab-ci.yml的 services 节中配置 HEALTHCHECK_TCP_PORT 环境变量。

覆盖服务容器资源#

如果作业有多个服务容器，您可以为每个服务容器设置显式的资源请求和限制。使用每个服务中的 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 默认服务账号#

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

您可以使用此变量指定附加到命名空间的服务账号，在复杂的 RBAC 配置中可能需要这样做。

yaml
variables:
  KUBERNETES_SERVICE_ACCOUNT_OVERWRITE: ci-service-account

为确保 CI 运行期间仅使用指定的服务账号，请为以下任一项定义正则表达式：

• 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 内核版本#

使用 Kubernetes 执行器的极狐GitLab Runner 可以在不同的 操作系统上运行构建，前提是所配置的集群有运行这些操作系统的节点。

系统会确定 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 格式的 key=value 对（在环境变量的情况下为 string:string）。

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