极狐GitLab Runner Helm Chart

将极狐GitLab Runner 实例部署到 Kubernetes 集群的官方方法是使用 gitlab-runner Helm Chart。

这个图表将极狐GitLab Runner 配置为：

使用极狐GitLab Runner 的 Kubernetes 执行器运行。
对于每个来自极狐GitLab CI/CD 的新作业，在特定的命名空间中部署新的 Pod 进行运行。

先决条件

从集群可以访问您的极狐GitLab 服务器的 API。
Kubernetes 1.4+ 并启用 Beta API。
为集群本地安装并认证 kubectl CLI。
您的机器本地安装 Helm 客户端。

使用 Helm Chart 安装极狐GitLab Runner

添加极狐GitLab Helm 仓库：

helm repo add gitlab https://charts.gitlab.io

如果使用的是 Helm 2，您必须初始化 Helm：

helm init

如果您无法访问最新版本的极狐GitLab Runner，您应该更新 Chart。要更新 Chart，请运行：

helm repo update gitlab

要查看您有权访问的极狐GitLab Runner 版本列表，请运行：

helm search repo -l gitlab/gitlab-runner

如果您在 values.yaml 中配置了极狐GitLab Runner，请运行以下命令：

# For Helm 2
helm install --namespace <NAMESPACE> --name gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner

# For Helm 3
helm install --namespace <NAMESPACE> gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner

其中：

<NAMESPACE> 是您想安装极狐GitLab Runner 的 Kubernetes 命名空间。
<CONFIG_VALUES_FILE> 是包含自定义配置的 Values 文件的路径。如果您想创建，请参见使用 Helm Chart 配置极狐GitLab Runner。

如果您想安装特定版本的极狐GitLab Runner Helm Chart，请向 helm install 命令中添加 --version <RUNNER_HELM_CHART_VERSION>。您可以用这种方法安装任何版本的 Chart，但是更新的 values.yml 可能不适用于旧版本的 Chart。

使用 Helm Chart 升级极狐GitLab Runner

在升级极狐GitLab Runner 前，在极狐GitLab 中停止 Runner 并确保作业都已经完成。停止 Runner 可以防止作业出现问题，例如完成时的授权问题。

极狐GitLab Runner Chart 安装完成后，使用 helm upgrade 完成配置变更和图表更新。

helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner

其中：

<NAMESPACE> 是安装极狐GitLab Runner 的 Kubernetes 命名空间。
<CONFIG_VALUES_FILE> 是包含自定义配置的 Values 文件的路径。如果您想创建，请参见使用 Helm Chart 配置极狐GitLab Runner。
<RELEASE-NAME> 是安装图表时您为它取的名字。在使用 Helm Chart 安装极狐GitLab Runner中，我们将其称为 gitlab-runner。

如果您想升级到特定版本的极狐GitLab Runner Helm Chart，而不是最新的版本，请在 helm upgrade 命令中添加 --version <RUNNER_HELM_CHART_VERSION>。

查看可用的极狐GitLab Runner Helm Chart 版本

Helm Chart 和极狐GitLab Runner 版本规则不同。使用以下命令在 Helm Chart 和极狐GitLab Runner 间进行版本映射：

# For Helm 2
helm search -l gitlab/gitlab-runner

# For Helm 3
helm search repo -l gitlab/gitlab-runner

输出示例如下：

NAME                 CHART VERSION APP VERSION DESCRIPTION
gitlab/gitlab-runner 0.51.0        15.10.0     GitLab Runner
gitlab/gitlab-runner 0.50.1        15.9.1      GitLab Runner
gitlab/gitlab-runner 0.50.0        15.9.0      GitLab Runner
gitlab/gitlab-runner 0.49.3        15.8.3      GitLab Runner
gitlab/gitlab-runner 0.49.2        15.8.2      GitLab Runner
gitlab/gitlab-runner 0.49.1        15.8.1      GitLab Runner
gitlab/gitlab-runner 0.49.0        15.8.0      GitLab Runner
...

使用 Helm Chart 配置极狐GitLab Runner

为您的极狐GitLab Runner 配置创建 values.yaml 文件。关于您的 Values 文件如何覆盖默认文件，请参见 Helm 文档。

可以在 Chart 仓库的 values.yaml 中找到默认配置。

必要配置

如果想使极狐GitLab Runner 生效，您的配置文件必须指定以下内容：

gitlabUrl - 注册 Runner 的极狐GitLab 服务器的完整 URL。例如，https://gitlab.example.com。
runnerRegistrationToken：
- 在极狐GitLab UI 中创建 Runner 时获取的身份验证令牌。
- 直接设置令牌或将其存储在 seret 中。
- 您还可以使用从您的极狐GitLab 实例检索的注册令牌。注册令牌已被弃用，并将在 17.0 中删除。

如果您无法执行额外配置的话，您现在已经可以安装极狐GitLab Runner 了。

额外配置

配置模板引入于 Helm Chart 0.23.0。

您可以使用配置模板文件在 Kubernetes 中配置极狐GitLab Runner 构建 Pod 的行为。您可以使用配置模板配置 Runner 上的任意字段，同时 Helm Chart 对特定 Runner 配置选项毫无感知。

以下是图表仓库内 values.yaml 文件中发现的默认设置的代码片段。需要注意，对于 config: 部分，当我们向 values.yaml 嵌入 config.toml 时，格式应该为 toml (<parameter> = <value> 而不是 <parameter>: <value>)。

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"

执行器特定的配置记载在 values.yaml 中。

使用配置模板设置附加选项（已移除）

此功能移除于极狐GitLab 16.0。使用”配置模版设置附加选项”代替。

通过配置模板使用缓存

如果您想通过配置模板使用缓存，请在 values.yaml 中设置以下变量：

带有您的密钥存储提供者 (s3access、gcsaccess、google-application-credentials 或 azureaccess)的密钥名称的 runners.cache.secretName。
带有缓存的其他设置的 runners.config。使用 toml 格式。

S3

例如，以下是使用静态证书配置S3 的示例：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"
      [runners.cache]
        Type = "s3"
        Path = "runner"
        Shared = true
        [runners.cache.s3]
          ServerAddress = "s3.amazonaws.com"
          BucketName = "my_bucket_name"
          BucketLocation = "eu-west-1"
          Insecure = false
          AuthenticationType = "access-key"

  cache:
    secretName: s3access

创建包含 accesskey 和 secretkey 的 s3access Kubernetes 密钥：

kubectl create secret generic s3access \
    --from-literal=accesskey="YourAccessKey" \
    --from-literal=secretkey="YourSecretKey"

Google Cloud Storage (GCS)

直接配置的静态证书

以下示例展示如何配置使用带有访问 ID 和私钥的证书配置 GCS：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"
      [runners.cache]
        Type = "gcs"
        Path = "runner"
        Shared = true
        [runners.cache.gcs]
          BucketName = "runners-cache"

  cache:
    secretName: gcsaccess

创建包含 gcs-access-id 和 gcs-private-key 的 gcsaccess Kubernetes 密钥：

kubectl create secret generic gcsaccess \
    --from-literal=gcs-access-id="YourAccessID" \
    --from-literal=gcs-private-key="YourPrivateKey"

从 GCP 下载的 JSON 文件中的静态证书

以下示例展示如何使用从谷歌云平台下载的 JSON 文件中的证书配置 GCS：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"
      [runners.cache]
        Type = "gcs"
        Path = "runner"
        Shared = true
        [runners.cache.gcs]
          BucketName = "runners-cache"

  cache:
    secretName: google-application-credentials

secrets:
  - name: google-application-credentials

创建 Kubernetes Secret google-application-credentials 并使用它加载 JSON 文件：

kubectl create secret generic google-application-credentials \
    --from-file=gcs-application-credentials-file=./path-to-your-google-application-credentials-file.json

Azure

以下示例展示如何配置 Azure Blob Storage：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"
      [runners.cache]
        Type = "azure"
        Path = "runner"
        Shared = true
        [runners.cache.azure]
          ContainerName = "CONTAINER_NAME"
          StorageDomain = "blob.core.windows.net"

  cache:
    secretName: azureaccess

创建包含 azure-account-name 和 azure-account-keyazureaccess 的 Kubernetes 密钥：

kubectl create secret generic azureaccess \
    --from-literal=azure-account-name="YourAccountName" \
    --from-literal=azure-account-key="YourAccountKey"

阅读更多关于 values.yaml 中 Helm Chart 的缓存内容。

启用 RBAC 支持

如果您的集群启用了 RBAC，您可以选择让图表创建它自己的服务账户或您自己提供一个。

如果您想让图表为您创建服务账户，请将 rbac.create 设置为 “true”：

rbac:
  create: true

如果您想使用已经存在的服务账户，请使用：

rbac:
  create: false
  serviceAccountName: your-service-account

控制最大 Runner 并发

Kubernetes 上部署的单个极狐GitLab Runner 可以自动启动额外 Runner Pod，进而并行执行多个作业。 concurrent 设置控制了一次允许使用的最多的 Pod，默认为 10：

## Configure the maximum number of concurrent jobs
## ref: https://docs.gitlab.cn/runner/configuration/advanced-configuration.html#the-global-section
##
concurrent: 10

使用极狐GitLab Runner 运行 Docker-in-Docker 容器

关于如何启用，请参见为 Runner 运行特权容器；关于如何运行 dind，请参见极狐GitLab Runner 文档。

为 Runner 运行特权容器

您可以使用特权容器运行极狐 GitLab Runner。如果您需要在极狐GitLab CI/CD 作业中使用 Docker 可执行文件，您可能需要启用它。

与此而来的可能是一些风险，详情请参见极狐GitLab CI/CD Runner 文档。

以非特权模式构建容器的最佳实践

使用 Docker-in-Docker 在容器内构建容器需要 Docker 特权模式。但是谷歌的 Kaniko 在非特权模式下也可以实现，在 Kubernetes 极狐GitLab Runner 上也进行了测试。

使用私有镜像库中的镜像

使用私有镜像库中的镜像需要配置 imagePullSecrets。更多关于如何创建 imagePullSecrets 的信息，请参见文档。

您必须在 CI/CD 作业使用的 Kubernetes 命名空间中创建一个或多个密钥。

您可以使用以下命令创建可以和 image_pull_secrets 一起使用的密钥：

kubectl create secret docker-registry <SECRET_NAME> \
  --namespace <NAMESPACE> \
  --docker-server="https://<REGISTRY_SERVER>" \
  --docker-username="<REGISTRY_USERNAME>" \
  --docker-password="<REGISTRY_PASSWORD>"

如果您配置 runners.imagePullSecrets，容器会向镜像入口点脚本添加 --kubernetes-image-pull-secrets "<SECRET_NAME>"。无需配置 Kubernetes 执行器 config.toml 设置中的 image_pull_secrets 参数。

runners:
  ## Specify one or more imagePullSecrets
  ##
  ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
  ##
  imagePullSecrets: [your-image-pull-secret]

记录下格式。这个值没有像 Kubernetes 资源中规定的那样以 name 标签为前缀。无论是否使用多个镜像库证书，您都需要一个或多个密钥名称阵列。

为访问极狐GitLab 提供自定义证书

您可以向极狐GitLab Runner Helm Chart 提供 Kubernetes Secret，它用于填充容器的 /home/gitlab-runner/.gitlab-runner/certs 目录。

Secret 中的每个密钥名称都用作目录中的文件名称，文件内容用作与密钥相关联的值：

密钥/文件名称的格式应该是 <gitlab.hostname>.crt，例如： gitlab.your-domain.com.crt。
中级证书都需要连接到同一个文件中的服务器证书。
使用证书所注册的主机名。

如果您使用自动生成的自签名通配符证书安装极狐GitLab Helm Chart，会为您创建一个 Secret。

## Set the certsSecretName to pass custom certificates for GitLab Runner to use
## Provide resource name for a Kubernetes Secret Object in the same namespace,
## this is used to populate the /home/gitlab-runner/.gitlab-runner/certs/ directory
## ref: https://docs.gitlab.com/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates-targeting-the-gitlab-server
##
certsSecretName: RELEASE-wildcard-tls-chain

极狐GitLab Runner Helm Chart 不会为您创建 Secret。如果想创建 Secret，您可以让 Kubernetes 将证书存储为 Secret，并以文件的形式向极狐GitLab Runner 容器展示。为此，运行以下命令：

kubectl create secret generic <SECRET_NAME> \
  --namespace <NAMESPACE> \
  --from-file=<CERTIFICATE_FILENAME>

其中：

<NAMESPACE> 是您想安装极狐GitLab Runner 的 Kubernetes 命名空间。
<SECRET_NAME> 是 Kubernetes Secret 资源名称。（例如：gitlab-domain-cert）。
<CERTIFICATE_FILENAME> 是您当前目录中的证书的文件名称，且该目录会导入到 Secret 中。

如果源文件 <CERTIFICATE_FILENAME> 不在当前目录中或者不遵从 <gitlab.hostname.crt> 格式，那么就需要指定目标上要使用的文件名称：

kubectl create secret generic <SECRET_NAME> \
  --namespace <NAMESPACE> \
  --from-file=<TARGET_FILENAME>=<CERTIFICATE_FILENAME>

其中：

<TARGET_FILENAME> 是展示到 Runner 容器的证书文件的名称（例如：gitlab.hostname.crt）。
<CERTIFICATE_FILENAME> 是与您当前的目录有关的证书的文件名称，且该目录会导入到 Secret 中（例如：cert-directory/my-gitlab-certificate.crt）。

然后您需要向极狐GitLab Runner Chart 提供 Secret 的名称。向您的 values.yaml 中添加以下内容：

## Set the certsSecretName in order to pass custom certificates for GitLab Runner to use
## Provide resource name for a Kubernetes Secret Object in the same namespace,
## this is used to populate the /home/gitlab-runner/.gitlab-runner/certs/ directory
## ref: https://docs.gitlab.cn/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates
##
certsSecretName: <SECRET NAME>

其中：

<SECRET_NAME> 是 Kubernetes Secret 资源名称，在上面的例子中是：gitlab-domain-cert。

关于更多极狐GitLab Runner 使用这些证书的信息，请参见 Runner 文档。

向 CI 环境变量密钥设置 Pod 标记

目前无法在 values.yaml 文件中将环境变量用作 Pod 标记。

在 Secret 中存储注册令牌或 Runner 令牌

DISCLAIMER: 此页面包含与即将推出的产品、特性和功能相关的信息。请务必注意，所提供的信息仅供参考。请不要依赖此信息进行购买或规划。与所有项目一样，本页提及的项目可能会发生变化或延迟。任何产品、特性或功能的开发、发布和时间安排由极狐GitLab 公司自行决定。

要注册新的 Runner，您可以在 values.yml 中指定 runnerRegistrationToken。

要注册现有 Runner，请使用 runnerToken。

将令牌存储在 values.yml 中可能存在安全风险，尤其是当您将这些令牌提交到 git 时。相反，您可以将这些令牌的值存储到 Kubernetes Secret 中，然后在拥有同样 Secret 名称的 values.yml 中更新 runners.secret 的值。

如果您拥有已经注册的 Runner，并想要使用它，请使用识别 Runner 的令牌设置 runner-token。如果您想注册一个新的 Runner，您可以使用您想要的注册令牌设置 runner-registration-token。

我们计划为在极狐GitLab UI 中创建的 Runner 包含一个身份验证令牌，您也可以将其包含在参数中。

示例：

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "NlZrN1pzb3NxUXlmcmVBeFhUWnIK" #base64 encoded registration token
  runner-token: ""

runners:
  secret: gitlab-runner-secret

这个例子使用 gitlab-runner-secret Secret 并使用 runner-registration-token 的值注册新的 Runner。

转换到基于 Ubuntu 的 `gitlab-runner` Docker 镜像

极狐GitLab Runner Helm Chart 默认使用 musl libc 的 Alpine 版本的 gitlab/gitlab-runner 镜像。某些情况下，您可能想要转换到使用 glibc 且基于 Ubuntu 的镜像。

为此，您需要使用以下值更新 values.yaml 文件：

# Specify the Ubuntu image. Remember to set the version. You can also use the `ubuntu` or `latest` tags.
image: gitlab/gitlab-runner:v15.11.0

# Update the security context values to the user ID in the ubuntu image
securityContext:
  fsGroup: 999
  runAsUser: 999

以非根用户身份运行

非根用户默认无法使用极狐GitLab Runner 镜像。极狐GitLab Runner UBI 和极狐GitLab Runner Helper UBI 镜像就是专为这种情况设计的。如果您想使用，请更改极狐GitLab Runner 和极狐GitLab Runner Helper 镜像：

任何用户 ID 都能使用镜像。很重要的一点是，这个用户 ID 是根用户的一部分，但这并未给予它任何特权。

image: registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-ocp:v15.11.0

securityContext:
  runAsNonRoot: true
  runAsUser: 999

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        helper_image = "registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-helper-ocp:x86_64-v15.11.0"
        [runners.kubernetes.pod_security_context]
          run_as_non_root = true
          run_as_user = 59417

使用符合 FIPS 的极狐GitLab Runner

如果想使用符合 FIPS 的极狐GitLab Runner，请按照以下方式更改极狐GitLab Runner 镜像和 Helper 镜像：

image: gitlab/gitlab-runner:ubi-fips

runners:
    config: |
        [[runners]]
          [runners.kubernetes]
            helper_image_flavor = "ubi-fips"

使用 Helm Chart 卸载极狐GitLab Runner

在卸载极狐GitLab Runner 之前，在极狐GitLab 中暂停 Runner 并确保作业都已完成。暂停 Runner 是为了防止作业出现问题，例如完成时出现授权错误。

如果您想卸载极狐GitLab Runner Chart，请运行以下命令：

helm delete --namespace <NAMESPACE> <RELEASE-NAME>

其中：

<NAMESPACE> 是安装极狐GitLab Runner 的 Kubernetes 命名空间。
<RELEASE-NAME> 是安装 Chart 时您给它取的名称。在使用 Helm Chart 安装极狐GitLab Runner中，我们将其称为 gitlab-runner。

排除 Kubernetes 安装故障

`ERROR: Job failed (system failure): secrets is forbidden`

如果您看见以下错误：

Using Kubernetes executor with image alpine ...
ERROR: Job failed (system failure): secrets is forbidden: User "system:serviceaccount:gitlab:default" cannot create resource "secrets" in API group "" in the namespace "gitlab"

请启用 RBAC 支持以更改错误。

`Unable to mount volumes for pod`

如果您看到所需 Secret 的挂载卷失败，请确保您已遵循将注册令牌或 Runner 令牌存储在 Secret 中。

谷歌云存储产物上传缓慢

由于 Runner Helper Pod 受 CPU 限制，上传到谷歌云存储的产物可能会性能下降，进而导致带宽速率较低。

可以通过增加 Helper Pod CPU 限制的方式缓解这个情况：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        helper_cpu_limit = "250m"

`PANIC: creating directory: mkdir /nonexistent: permission denied`

要解决此问题，请切换到基于 Ubuntu 的极狐GitLab Runner Docker 镜像。

FATAL: Runner configuration other than name and executor configuration is reserved and cannot be specified when registering with a runner token. This configuration is specified on the GitLab server. Please try again without specifying those arguments

安装极狐GitLab Runner Helm Chart 后，您可能会在 Pod 日志中收到此错误。如果您使用身份验证令牌并通过 secret 提供令牌，就会发生这种情况。要修复此错误，请检查您的值 YAML 文件并确保您没有使用任何已弃用的值。

极狐GitLab Runner Helm Chart

先决条件

使用 Helm Chart 安装极狐GitLab Runner

使用 Helm Chart 升级极狐GitLab Runner

查看可用的极狐GitLab Runner Helm Chart 版本

使用 Helm Chart 配置极狐GitLab Runner

必要配置

额外配置

使用配置模板设置附加选项（已移除）

通过配置模板使用缓存

S3

Google Cloud Storage (GCS)

直接配置的静态证书

从 GCP 下载的 JSON 文件中的静态证书

Azure

启用 RBAC 支持

控制最大 Runner 并发

使用极狐GitLab Runner 运行 Docker-in-Docker 容器

为 Runner 运行特权容器

以非特权模式构建容器的最佳实践

使用私有镜像库中的镜像

为访问极狐GitLab 提供自定义证书

向 CI 环境变量密钥设置 Pod 标记

在 Secret 中存储注册令牌或 Runner 令牌

转换到基于 Ubuntu 的 gitlab-runner Docker 镜像

以非根用户身份运行

使用符合 FIPS 的极狐GitLab Runner

使用 Helm Chart 卸载极狐GitLab Runner

排除 Kubernetes 安装故障

ERROR: Job failed (system failure): secrets is forbidden

Unable to mount volumes for pod

谷歌云存储产物上传缓慢

PANIC: creating directory: mkdir /nonexistent: permission denied

FATAL: Runner configuration other than name and executor configuration is reserved and cannot be specified when registering with a runner token. This configuration is specified on the GitLab server. Please try again without specifying those arguments

转换到基于 Ubuntu 的 `gitlab-runner` Docker 镜像

`ERROR: Job failed (system failure): secrets is forbidden`

`Unable to mount volumes for pod`

`PANIC: creating directory: mkdir /nonexistent: permission denied`