使用 Cloud KMS 中的加密凭据

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

注意：Secret Manager 是使用 Cloud Build 管理敏感数据的推荐方法。对于现有项目，您可以继续使用 Cloud KMS，但对于新项目，请使用 Secret Manager。如需了解如何将构建配置为从 Secret Manager 访问 Secret，请参阅使用 Secret Manager 中的 Secret。

准备工作

• Enable the Cloud Build and Cloud KMS APIs.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

  Enable the APIs

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

  注意： 如果您之前已经安装了 gcloud CLI，请运行 gcloud components update 以确保您拥有最新版本。

• 使用 Cloud KMS 加密敏感信息。Cloud KMS 将加密内容保存在文件中。

• [可选] 如需将构建配置为使用加密数据，请将 ENCRYPTED_FILE 转换为 base64（对于使用加密文件的构建配置，无需执行此步骤）：

      base64 ENCRYPTED_FILE
  

必需的 IAM 权限

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

1. 在 Google Cloud 控制台中，前往 Cloud Build 设置页面：

   打开“设置”页面

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

警告： 向默认 Cloud Build 服务账号授予 Cloud KMS CryptoKey Decrypter 角色可允许该服务账号解密加密信息。构建触发器使用默认的 Cloud Build 服务账号执行构建。因此，任何使用构建触发器运行构建的用户都将在构建时向服务账号授予权限。这样，不具有 CryptoKey Decrypter 角色的用户能够使用构建触发器来执行解密加密信息的构建。此操作记录在项目的构建记录中。

配置构建以使用加密数据

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

2. 在您的构建配置文件中：

   • 在所有构建 steps 之后，添加 availableSecrets 字段以将加密值指定为环境变量，以及添加 kmsKeyName 以用于解密该值。您可以在 kmsKeyName 的值中使用替代变量。
   • 在您要指定 Secret 的构建步骤中：
     • 添加指向 bash 的 entrypoint 字段，以在构建步骤中使用 bash 工具。这是引用 Secret 的环境变量所必需的。
     • 添加 secretEnv 字段以指定加密值的环境变量。
     • 在 args 字段中，添加 -c 标志作为第一个参数。您在 -c 之后传递的任何字符串均被视为命令。如需详细了解如何使用 -c 运行 bash 命令，请参阅 bash 文档。
     • 在 args 字段中指定加密值时，请使用前缀为 $$.
   Note: You can refer to encrypted values using environment variables only in the args field of a build step.

   The following example build config file shows how to login to Docker and pull a private image:

   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"
          }
      }]
    }
   }
   
   

   Replace the placeholder values in the above commands with the following:

   • PROJECT_ID: The ID of the Google Cloud project which contains your Cloud KMS service.
   • USERNAME_KEYRING_NAME: The key ring name of your Docker username.
   • USERNAME_KEY_NAME: The key name of your Docker username.
   • ENCRYPTED_USERNAME: Your encrypted Docker username in base64 format.
   • PASSWORD_KEYRING_NAME: The key ring name of your Docker password.
   • PASSWORD_KEY_NAME: The key name of your Docker password.
   • ENCRYPTED_PASSWORD: Your encrypted Docker password in base64 format.
   • REPOSITORY: The name of your Docker repository from where you're pulling the image.

   • TAG: The tag name of your image.

     Note: The secretEnv field does not support substitution variables. If the Google Cloud project hosting the key changes, the encrypted contents within that project also change.

3. Use the build config file to manually start a build or to automate builds using triggers.

Configuring builds to use encrypted files

1. In your project root directory, create a Cloud Build build config file named cloudbuild.yaml or cloudbuild.json.

2. In your build config file, before any build steps that interact with the decrypted file, add a gcloud build step to decrypt the encrypted file using the encryption key. The following example build config file shows how to login to Docker using the encrypted file with Docker password:

   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"
       ]
      }
     ]
   }
   

   Replace the placeholder values in the above commands with the following:

   • KEYRING_NAME: The key ring name of your Docker password.
   • KEY_NAME: The key name of your Docker password.
   • ENCRYPTED_PASSWORD_FILE: Encrypted file with your Docker password.
   • PLAINTEXT_PASSWORD_FILE: Plaintext file with your Docker password.

3. Use the build config file to manually start a build or to automate builds using triggers.

Configuring builds to use encrypted data (legacy)

Warning: This is the legacy method of using Cloud KMS with Cloud Build. This method will continue to work, but we recommend that you use the newer way of configuring builds to use encrypted data.

To encrypt sensitive data using Cloud KMS and use that data in a build config file:

1. In your build config file, add a secrets field to specify the encrypted value and the CryptoKey to use to decrypt it. Then, in the build step where you want to use the encrypted variable, add a secretEnv field to specify the variable as an environment variable. Include the variable's name in the secretEnv field. If you specify the variable value, or a non-secret environment variable with the same name, Cloud Build throws an error.

   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 代码库。