Help us learn about your current experience with the documentation. Take the survey.

在 GitLab CI/CD 中使用 GCP Secret Manager 密钥

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

您可以在 GitLab CI/CD 管道中使用存储在 Google Cloud (GCP) Secret Manager 中的密钥。

使用 GitLab 与 GCP Secret Manager 的流程如下：

GitLab 向 CI/CD 作业颁发 ID token。
Runner 使用 ID token 向 GCP 进行身份验证。
GCP 向 GitLab 验证 ID token。
GCP 颁发短期访问令牌。
Runner 使用访问令牌访问密钥数据。
GCP 检查访问令牌主体的 IAM 密钥权限。
GCP 将密钥数据返回给 Runner。

要使用 GitLab 与 GCP Secret Manager，您必须：

在 GCP Secret Manager 中存储密钥。
配置 GCP Workload Identity Federation，将 GitLab 作为身份提供者。
配置 GCP IAM 权限，授予访问 GCP Secret Manager 的权限。
配置 GitLab CI/CD 与 GCP Secret Manager。

配置 GCP IAM Workload Identity Federation (WIF)

必须配置 GCP IAM WIF 以识别 GitLab 颁发的 ID token，并为它们分配适当的主体的权限。该主体用于授权访问 Secret Manager 资源：

在 GCP 控制台中，转到 IAM & Admin > Workload Identity Federation。
选择 CREATE POOL 并创建一个具有唯一名称的新身份池，例如 gitlab-pool。
选择 ADD PROVIDER 为身份池添加一个具有唯一名称的新 OIDC Provider，例如 gitlab-provider。
1. 将 Issuer (URL) 设置为 GitLab URL，例如 https://gitlab.com。
2. 选择 Default audience，或选择 Allowed audiences 用于自定义受众，该受众用于 GitLab CI/CD ID token 的 aud 字段。

在 Attribute Mapping 下，创建以下映射，其中：

attribute.X 是要在 Google token 中作为声明包含的属性名称。
assertion.X 是要从 GitLab claim 中提取的值。

Google 上的属性	来自 GitLab 的断言
`google.subject`	`assertion.sub`
`attribute.gitlab_project_id`	`assertion.project_id`

授予 GCP IAM 主体访问权限

设置 WIF 后，您必须授予 WIF 主体访问 Secret Manager 中密钥的权限。

在 GCP 控制台中，转到 Security > Secret Manager。
选择您要授予访问权限的密钥名称，查看密钥详情。
从 PERMISSIONS 选项卡中，选择 GRANT ACCESS 来授予通过 WIF 提供者创建的主体集访问权限。外部身份格式为：
```
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.gitlab_project_id/GITLAB_PROJECT_ID
```
在此示例中：
- PROJECT_NUMBER: 您的 Google Cloud 项目编号（不是 ID），可以在项目仪表板中找到。
- POOL_ID: 在第一部分中创建的工作负载身份池的 ID（不是名称），例如 gitlab-pool。
- GITLAB_PROJECT_ID: 在项目概览页面中找到的 GitLab 项目 ID。
分配 Secret Manager Secret Accessor 角色。

配置 GitLab CI/CD 以使用 GCP Secret Manager 密钥

您必须添加这些 CI/CD 变量来提供有关您 GCP Secret Manager 的详细信息：

GCP_PROJECT_NUMBER: GCP 项目编号。
GCP_WORKLOAD_IDENTITY_FEDERATION_POOL_ID: WIF 池 ID，例如 gitlab-pool。
GCP_WORKLOAD_IDENTITY_FEDERATION_PROVIDER_ID: WIF 提供者 ID，例如 gitlab-provider。

然后，您可以通过使用 gcp_secret_manager 关键字定义它们，在 CI/CD 作业中使用存储在 GCP Secret Manager 中的密钥：

job_using_gcp_sm:
  id_tokens:
    GCP_ID_TOKEN:
      # `aud` 必须与 WIF 身份池中定义的受众匹配。
      aud: https://iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/${GCP_WORKLOAD_IDENTITY_FEDERATION_POOL_ID}/providers/${GCP_WORKLOAD_IDENTITY_FEDERATION_PROVIDER_ID}
  secrets:
    DATABASE_PASSWORD:
      gcp_secret_manager:
        name: my-project-secret  # 这是 GCP Secret Manager 中定义的密钥名称
        version: 1               # 可选：默认为 `latest`。
      token: $GCP_ID_TOKEN

使用来自不同 GCP 项目的密钥

GCP 中的密钥名称是按项目定义的。默认情况下，gcp_secret_manager:name 中指定的密钥是从 GCP_PROJECT_NUMBER 中指定的项目读取的。

要从包含 WIF 池的不同项目中读取密钥，使用完全限定的密钥名称，格式为 projects/<项目编号>/secrets/<密钥名称>。

例如，如果 my-project-secret 在 GCP 项目编号 123456789 中，那么您可以通过以下方式访问该密钥：

job_using_gcp_sm:
  # ... 如前所述配置 ...
  secrets:
    DATABASE_PASSWORD:
      gcp_secret_manager:
        name: projects/123456789/secrets/my-project-secret  # GCP Secret Manager 中定义的密钥的完全限定名称
        version: 1                                          # 可选：默认为 `latest`。
      token: $GCP_ID_TOKEN

故障排除

错误：映射的属性 `google.subject` 大小超过 127 字节限制

长的分支路径可能导致作业因以下错误而失败，因为 assertion.sub 属性超过了 127 个字符：

ERROR: Job failed (system failure): resolving secrets: failed to exchange sts token: googleapi: got HTTP response code 400 with body:
{"error":"invalid_request","error_description":"The size of mapped attribute google.subject exceeds the 127 bytes limit.
Either modify your attribute mapping or the incoming assertion to produce a mapped attribute that is less than 127 bytes."}

长的分支路径可能由以下原因引起：

深度嵌套的子组。
长的组、仓库或分支名称。

例如，对于 gitlab-org/gitlab 分支，负载为 project_path:gitlab-org/gitlab:ref_type:branch:ref:{branch_name}。为了使字符串保持少于 127 个字符，分支名称必须为 76 个字符或更少。此限制由 Google Cloud IAM 强制执行，在 Google issue #264362370 中跟踪。

解决此问题的唯一方法是使用更短的名称为您的分支和仓库。

`The secrets provider can not be found. Check your CI/CD variables and try again.` 消息

当尝试启动配置为访问 GCP Secret Manager 的作业时，您可能会收到此错误：

The secrets provider can not be found. Check your CI/CD variables and try again.

作业无法创建，因为一个或多个必需的变量未定义：

GCP_PROJECT_NUMBER
GCP_WORKLOAD_IDENTITY_FEDERATION_POOL_ID
GCP_WORKLOAD_IDENTITY_FEDERATION_PROVIDER_ID

`WARNING: Not resolved: no resolver that can handle the secret` 警告

Google Cloud Secret Manager 集成至少需要 GitLab 16.8 和 GitLab Runner 16.8。如果作业由使用早于 16.8 版本的 Runner 执行，则会显示此警告。

在 GitLab.com 上，存在一个已知问题导致 SaaS Runner 运行旧版本。作为临时解决方案，直到此问题修复，您可以注册自己的 GitLab Runner，版本为 16.8 或更高。