• 使用配置模板的缓存
  • Amazon S3
  • Google Cloud Storage (GCS)
    • 直接配置静态凭证
    • 从 GCP 下载的 JSON 文件中的静态凭证
  • Azure
• 启用 RBAC 支持
• 控制最大 runner 并发数
• 使用极狐GitLab Runner 运行 Docker-in-Docker 容器
• 使用 runners 的特权容器
  • 在没有特权模式下构建容器的最佳实践
• 从私有镜像仓库中使用镜像
• 使用自定义证书访问极狐GitLab
  • 准备您的证书
  • 创建 Kubernetes 密钥
  • 将密钥提供给 chart
• 将 pod 标签设置为 CI 环境变量键
• 切换到基于 Ubuntu 的 gitlab-runner Docker 镜像
• 使用非 root 用户运行
• 使用符合 FIPS 的极狐GitLab Runner
• 使用配置模板

配置极狐GitLab Runner Helm chart

此页面描述了您可以添加到极狐GitLab Runner Helm chart 的可选配置。

使用配置模板的缓存

要在您的配置模板中使用缓存，请在 values.yaml 中设置以下变量：

• runners.cache.secretName: 您的对象存储提供商的密钥名称。选项：s3access，gcsaccess，google-application-credentials 或 azureaccess。
• runners.config: 其他设置请参阅 缓存，以 TOML 格式。

Amazon S3

要配置使用静态凭证的 Amazon S3：

1. 将以下示例添加到您的 values.yaml，根据需要更改值：

   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
   

2. 创建一个包含 accesskey 和 secretkey 的 s3access Kubernetes 密钥：

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

Google Cloud Storage (GCS)

Google Cloud Storage 可以通过多种方式使用静态凭证进行配置。

直接配置静态凭证

要配置 GCS 凭证 使用访问 ID 和私钥：

1. 将以下示例添加到您的 values.yaml，根据需要更改值：

   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
   

2. 创建一个包含 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，从 Google Cloud Platform 下载：

1. 将以下示例添加到您的 values.yaml，根据需要更改值：

   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
   

2. 创建一个名为 google-application-credentials 的 Kubernetes 密钥，并加载 JSON 文件。根据需要更改路径：

   kubectl create secret generic google-application-credentials \
       --from-file=gcs-application-credentials-file=./PATH-TO-CREDENTIALS-FILE.json
   

Azure

要配置 Azure Blob Storage：

1. 将以下示例添加到您的 values.yaml，根据需要更改值：

   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
   

2. 创建一个包含 azure-account-name 和 azure-account-key 的 azureaccess Kubernetes 密钥：

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

要了解有关 Helm chart 缓存的更多信息，请参阅 values.yaml。

启用 RBAC 支持

如果您的集群启用了 RBAC（基于角色的访问控制），chart 可以创建自己的服务账户，或者您可以提供一个。

• 要让 chart 为您创建服务账户，请将 rbac.create 设置为 true：

  rbac:
    create: true
  

• 要使用现有的服务账户，请设置一个 serviceAccountName：

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

控制最大 runner 并发数

在 Kubernetes 上部署的单个 runner 可以通过启动额外的 Runner pods 来并行运行多个作业。要更改一次允许的最大 pods 数量，请编辑 concurrent 设置。默认值为 10：

## 配置最大并发作业数
## ref: https://gitlab.cn/docs/runner/configuration/advanced-configuration.html#the-global-section
##
concurrent: 10

有关此设置的更多信息，请参阅极狐GitLab Runner 的高级配置文档中的全局部分。

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

要使用 Docker-in-Docker 容器与极狐GitLab Runner ：

• 要启用它，请参阅使用 runners 的特权容器。
• 有关运行 Docker-in-Docker 的说明，请参阅极狐GitLab Runner 文档。

使用 runners 的特权容器

要在您的极狐GitLab CI/CD 作业中使用 Docker 可执行文件，请配置 runner 以使用特权容器。

前提条件：

• 您了解风险，这些风险在极狐GitLab CI/CD Runner 文档中进行了描述。
• 您的极狐GitLab Runner 实例已注册到极狐GitLab 的特定项目，并且您信任其 CI/CD 作业。

要在 values.yaml 中启用特权模式，请添加以下行：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        # 启用特权标志运行所有容器。
        privileged = true
        ...

有关更多信息，请参阅有关 [runners.kubernetes] 部分的高级配置信息。

在没有特权模式下构建容器的最佳实践

在容器内使用 Docker-in-Docker 构建容器需要 Docker 特权模式。Google 的 Kaniko 是一种无需特权模式即可工作的替代方案，并且已经在 Kubernetes 极狐GitLab Runner 上进行了测试。

从私有镜像仓库中使用镜像

要从私有镜像仓库中使用镜像，请配置 imagePullSecrets。

1. 在用于 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>"
   

2. 对于极狐GitLab Runner Helm chart 版本 0.53.x 及更高版本，请在 config.toml 中从模板中设置 image_pull_secret，其提供在 runners.config：

   runners:
     config: |
       [[runners]]
         [runners.kubernetes]
           ## 指定一个或多个 imagePullSecrets
           ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
           ##
           image_pull_secrets = [your-image-pull-secret]
   

   有关更多信息，请参阅 Kubernetes 文档中的从私有镜像仓库中拉取镜像。

3. 对于极狐GitLab Runner Helm chart 版本 0.52 及更早版本，请在 values.yaml 中为 runners.imagePullSecrets 设置一个值。当您设置此值时，容器会将 --kubernetes-image-pull-secrets "<SECRET_NAME>" 添加到镜像入口点脚本中。这消除了在 Kubernetes 执行器 config.toml 设置中配置 image_pull_secrets 参数的需要。

   runners:
     imagePullSecrets: [your-image-pull-secret]
   

有关如何创建 imagePullSecrets 的更多详细信息，请参阅 Kubernetes 文档中的从私有镜像仓库中拉取镜像。

使用自定义证书访问极狐GitLab

要使用自定义证书，请向极狐GitLab Runner Helm chart 提供一个 Kubernetes 密钥。此密钥将添加到容器的 /home/gitlab-runner/.gitlab-runner/certs 目录中：

1. 准备您的证书
2. 创建 Kubernetes 密钥
3. 将密钥提供给 chart

准备您的证书

Kubernetes 密钥中的每个键名都用作目录中的文件名，文件内容是与键关联的值：

• 使用的文件名应为 <gitlab.hostname>.crt 格式，例如 gitlab.your-domain.com.crt。
• 将任何中间证书与您的服务器证书连接到同一文件中。
• 使用的主机名应为注册证书的主机名。

创建 Kubernetes 密钥

如果您使用 自动生成的自签名通配符证书 方法安装了极狐GitLab Helm chart，则已为您创建了一个密钥。

如果您没有使用自动生成的自签名通配符证书安装极狐GitLab Helm chart，请创建一个密钥。这些命令会将您的证书存储为 Kubernetes 中的密钥，并将其作为文件呈现给极狐GitLab Runner 容器。

• 如果您的证书在当前目录中，并遵循 <gitlab.hostname.crt> 格式，请根据需要修改此命令：

  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>：要导入到密钥中的当前目录中的证书的文件名。

• 如果您的证书在其他目录中，或者不遵循 <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> 是相对于您当前目录的证书文件名，以导入到密钥中。例如：cert-directory/my-gitlab-certificate.crt。

将密钥提供给 chart

在 values.yaml 中，将 certsSecretName 设置为同一命名空间中的 Kubernetes 密钥对象的资源名称。这使您能够传递极狐GitLab Runner 使用的自定义证书。在前面的示例中，资源名称是 gitlab-domain-cert：

 certsSecretName: <SECRET NAME>

有关更多信息，请参阅针对极狐GitLab 服务器的自签名证书的支持选项。

将 pod 标签设置为 CI 环境变量键

您无法在 values.yaml 文件中将环境变量用作 pod 标签。

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

默认情况下，极狐GitLab Runner Helm chart 使用 gitlab/gitlab-runner 镜像的 Alpine 版本，该版本使用 musl libc。您可能需要切换到基于 Ubuntu 的镜像，该镜像使用 glibc。

要执行此操作，请使用以下值指定您的 values.yaml 文件中的镜像：

# 指定 Ubuntu 镜像，并设置版本。您也可以使用 `ubuntu` 或 `latest` 标签。
image: gitlab/gitlab-runner:v17.3.0

# 更新安全上下文值以匹配 Ubuntu 镜像中的用户 ID
securityContext:
  fsGroup: 999
  runAsUser: 999

使用非 root 用户运行

默认情况下，极狐GitLab Runner 镜像不适用于非 root 用户。极狐GitLab Runner UBI 和极狐GitLab Runner Helper UBI 镜像是为这种情况设计的。

要使用它们，请在 values.yaml 中更改极狐GitLab Runner 和极狐GitLab Runner Helper 镜像：

image:
  registry: registry.gitlab.com
  image: gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-ocp
  tag: v16.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-v16.11.0"
            [runners.kubernetes.pod_security_context]
              run_as_non_root = true
              run_as_user = 59417

虽然 run_as_user 指向 nonroot 用户的用户 ID (59417)，但这些镜像适用于任何用户 ID。重要的是这个用户 ID 是 root 组的一部分。成为 root 组的一部分并没有赋予它任何特定的权限。

使用符合 FIPS 的极狐GitLab Runner

要使用符合 FIPS 的极狐GitLab Runner，请在 values.yaml 中更改极狐GitLab Runner 镜像和 Helper 镜像：

image:
  registry: docker.io
  image: gitlab/gitlab-runner
  tag: ubi-fips

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

使用配置模板

要在 Kubernetes 中配置极狐GitLab Runner 构建 pod 的行为，请使用配置模板文件。配置模板可以配置 runner 的任何字段，而无需与 Helm chart 共享特定的 runner 配置选项。例如，这些默认设置可以在 chart 仓库中的 values.yaml 文件 中找到：

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

config: 部分中的值应使用 TOML (<parameter> = <value> 而不是 <parameter>: <value>)，因为 config.toml 被嵌入到 values.yaml 中。

有关执行器特定的配置，请参阅 values.yaml 文件。