使用 Cloud KMS 中的加密凭据

Cloud Key Management Service 是 Google Cloud 服务，可让您管理和使用加密密钥。本页面介绍如何在 Cloud Build 中使用 Cloud KMS 中的加密信息。

准备工作

启用 Cloud Build and Cloud KMS API。
启用 API
如需使用本指南中的命令行示例，请安装并配置 Google Cloud CLI。

注意：如果您之前安装了 gcloud CLI，请运行 gcloud components update 以确保您拥有最新的可用版本。
使用 Cloud KMS 加密敏感信息。Cloud KMS 将加密内容保存在文件中。
[可选] 如需将构建配置为使用加密数据，请将 ENCRYPTED_FILE 转换为 base64（对于使用加密文件的构建配置，无需执行此步骤）：
```
    base64 ENCRYPTED_FILE
```

必需的 IAM 权限

向 Cloud Build 服务账号授予 Cloud KMS CryptoKey Decrypter (roles/cloudkms.cryptoKeyDecrypter) IAM 角色：

在 Google Cloud 控制台中，转到 Cloud Build 设置页面：

打开“设置”页面

找到具有 Cloud KMS CryptoKey Decrypter 角色的行，并将其状态设置为已启用。

配置构建以使用加密数据

在项目根目录中，创建一个名为 cloudbuild.yaml 或 cloudbuild.json 的Cloud Build 构建配置文件。
在您的构建配置文件中：
- 在所有构建 steps 之后，添加 availableSecrets 字段以将加密值指定为环境变量，以及添加 kmsKeyName 以用于解密该值。您可以在 kmsKeyName 的值中使用替代变量。
- 在您要指定 Secret 的构建步骤中：
  - 添加指向 bash 的 entrypoint 字段，以在构建步骤中使用 bash 工具。这是引用 Secret 的环境变量所必需的。
  - 添加 secretEnv 字段以指定加密值的环境变量。
  - 在 args 字段中，添加 -c 标志作为第一个参数。您在 -c 之后传递的任何字符串均被视为命令。如需详细了解如何使用 -c 运行 bash 命令，请参阅 bash 文档。
  - 在 args 字段中指定加密值时，请使用前缀为 $$ 的环境变量指定该加密值。
注意：您只能在构建步骤的 args 字段中使用环境变量引用加密值。
以下示例构建配置文件展示了如何登录 Docker 和拉取私有映像：
YAML
```
 steps:
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
   secretEnv: ['USERNAME', 'PASSWORD']
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker pull $$USERNAME/IMAGE:TAG']
   secretEnv: ['USERNAME']
 availableSecrets:
   inline:
   - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME
     envMap:
       USERNAME: 'ENCRYPTED_USERNAME'
   - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME
     envMap:
       PASSWORD: 'ENCRYPTED_PASSWORD'
```
JSON
```
{
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=$$USERNAME --password=$$PASSWORD"
    ],
    "secretEnv": [
      "USERNAME",
      "PASSWORD"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker pull $$USERNAME/REPOSITORY:TAG"
     ],
     "secretEnv": [
      "USERNAME"
    ]
  }
  ],
  "availableSecrets": {
    "inline": [{
      "kmsKeyName":  "projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME",
      "envMap": {
        "USERNAME": "ENCRYPTED_USERNAME"
       }
   },
   {
    "kmsKeyName": "projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME",
    "envMap": {
        "PASSWORD": "ENCRYPTED_PASSWORD"
       }
   }]
 }
}
```
将上述命令中的占位值替换为以下内容：
- PROJECT_ID：包含您的 Cloud KMS 服务的 Google Cloud 项目的 ID。
- USERNAME_KEYRING_NAME：Docker 用户名的密钥环名称。
- USERNAME_KEY_NAME：Docker 用户名的密钥名称。
- ENCRYPTED_USERNAME：您的 base64 格式的加密 Docker 用户名。
- PASSWORD_KEYRING_NAME：Docker 密码的密钥环名称。
- PASSWORD_KEY_NAME：Docker 密码的密钥名称。
- ENCRYPTED_PASSWORD：Base64 格式的加密 Docker 密码。
- REPOSITORY：要从中拉取映像的 Docker 代码库的名称。
- TAG：您的映像的标记名称。
  
  注意：secretEnv 字段不支持替代变量。如果托管该密钥的 Google Cloud 项目发生更改，则该项目中的加密内容也会更改。
使用构建配置文件手动启动构建或使用触发器自动执行构建。

将构建配置为使用加密文件

在项目根目录中，创建一个名为 cloudbuild.yaml 或 cloudbuild.json 的Cloud Build 构建配置文件。

在构建配置文件中，在执行与解密文件交互的任何构建步骤之前，添加 gcloud 构建步骤以使用加密密钥解密加密文件。以下示例构建配置文件展示了如何使用包含 Docker 密码的加密文件登录 Docker：

YAML

steps:
- name: gcr.io/cloud-builders/gcloud
  args:
  - kms
  - decrypt
  - "--ciphertext-file=ENCRYPTED_PASSWORD_FILE"
  - "--plaintext-file=PLAINTEXT_PASSWORD_FILE"
  - "--location=global"
  - "--keyring=KEYRING_NAME"
  - "--key=KEY_NAME"
- name: gcr.io/cloud-builders/docker
  entrypoint: bash
  args:
  - "-c"
  - docker login --username=DOCKER_USERNAME --password-stdin < PLAINTEXT_PASSWORD_FILE

JSON

{
  "steps": [
  {
    "name": "gcr.io/cloud-builders/gcloud",
    "args": [
      "kms",
      "decrypt",
      "--ciphertext-file=ENCRYPTED_PASSWORD_FILE",
      "--plaintext-file=PLAINTEXT_PASSWORD_FILE",
      "--location=global",
      "--keyring=KEYRING_NAME",
      "--key=KEY_NAME"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=DOCKER_USERNAME --password-stdin < PLAINTEXT_PASSWORD_FILE"
    ]
   }
  ]
}

将上述命令中的占位值替换为以下内容：

KEYRING_NAME：Docker 密码的密钥环名称。
KEY_NAME：Docker 密码的密钥名称。
ENCRYPTED_PASSWORD_FILE：包含 Docker 密码加密文件。
PLAINTEXT_PASSWORD_FILE：包含 Docker 密码的明文文件。

使用构建配置文件手动启动构建或使用触发器自动执行构建。

将构建配置为使用加密数据（旧版）

要使用 Cloud KMS 加密敏感数据并在构建配置文件中使用该数据，请执行以下操作：

在构建配置文件中，添加 secrets 字段以指定加密值，并添加 CryptoKey 用于解密该值。然后，在要使用加密变量的构建步骤中，添加 secretEnv 字段将变量指定为环境变量。在 secretEnv 字段中添加变量名称。如果您指定变量值或具有相同名称的非密钥环境变量，则 Cloud Build 会抛出错误。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: 'bash'
  args: ['-c', 'docker login --username=user-name --password=$$PASSWORD']
  secretEnv: ['PASSWORD']
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', 'user-name/myubuntu']
secrets:
- kmsKeyName: projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name
  secretEnv:
    PASSWORD: 'encrypted-password'

JSON

{
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=user-name --password=$$PASSWORD"
    ],
    "secretEnv": [
      "PASSWORD"
     ]
   },
   {
     "name": "gcr.io/cloud-builders/docker",
     "args": [
       "push",
       "user-name/myubuntu"
      ]
   }
   ],
   "secrets": [
   {
     "kmsKeyName": "projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name",
     "secretEnv": {
       "PASSWORD": "encrypted-password"
     }
   }
   ]
}

后续步骤

了解如何将构建配置为从 Secret Manager 访问 Secret。
了解如何访问私有 GitHub 代码库。