Cloud Key Management Service is a Google Cloud service that enables you to manage anduse cryptographic keys. This page explains how to use encrypted information fromCloud KMS in Cloud Build.

Note: Secret Manager is the recommended techniquefor managing sensitive data with Cloud Build. For existing projects, youcan continue using Cloud KMS, but for new projects, use Secret Manager.For instructions on configuring builds to access secrets from Secret Manager,seeUsing secrets from Secret Manager.

Before you begin

• 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 theserviceusage.services.enable permission.Learn how to grant roles.

  Enable the APIs

• To use the command-line examples in this guide, install andconfigure theGoogle Cloud CLI.

  Note: If you've installed gcloud CLI previously, make sure you have thelatest available version by runninggcloud components update.

• Encrypt the sensitive information usingCloud KMS.Cloud KMS saves your encrypted content in a file.

• [OPTIONAL] To configure builds to use encrypted data, convert theENCRYPTED_FILE to base64 (this step is not requiredfor build configs that use encrypted files):

      base64ENCRYPTED_FILE

Required IAM permissions

Grant theCloud KMS CryptoKey Decrypter (roles/cloudkms.cryptoKeyDecrypter)IAM role to the build service account:

1. In the Google Cloud console, go to the Cloud BuildSettingspage:

   Open the Settings page

2. Locate the row with theCloud KMS CryptoKey Decrypter role and set itsStatus toENABLED.

Warning: Granting the Cloud KMS CryptoKey Decrypter role to the defaultCloud Build service account allows the service account to decrypt theencrypted information.Build triggersuse the default Cloud Build service account to execute builds. Therefore,any user who uses build triggers to run builds will have permissions granted tothe service account at build time. This allows users without the CryptoKey Decrypterrole to use build triggers to perform a build that decrypts the encrypted information.This action is logged in the project'sbuild history.

Configuring builds to use encrypted data

1. In your project root directory, create a Cloud Build build configfile namedcloudbuild.yaml orcloudbuild.json.

2. In your build config file:

   • After all the buildsteps, add anavailableSecrets field to specify theencrypted value as an environment variable and thekmsKeyName to use to decrypt it.You can usesubstitution variablesin the value ofkmsKeyName.
   • In the build step where you want to specify the secret:
     • Add anentrypoint field pointing tobash to use the bash tool in thebuild step. This is required to refer to the environment variable for thesecret.
     • Add asecretEnv field specifying the environment variable for theencrypted value.
     • In theargs field, add a-c flag as the first argument. Any stringyou pass after -c is treated as a command. For more information on runningbash commands with -c, see thebash documentation.
     • When specifying the encrypted value in theargs field, specify it using theenvironment variable prefixed with$$.
   Note: You can refer to encrypted values using environment variables only in theargs field of a build step.

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

   YAML

   steps:-name:'gcr.io/cloud-builders/docker'entrypoint:'bash'args:['-c','dockerlogin--username=$$USERNAME--password=$$PASSWORD']secretEnv:['USERNAME','PASSWORD']-name:'gcr.io/cloud-builders/docker'entrypoint:'bash'args:['-c','dockerpull$$USERNAME/IMAGE:TAG']secretEnv:['USERNAME']availableSecrets:inline:-kmsKeyName:projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAMEenvMap:USERNAME:'ENCRYPTED_USERNAME'-kmsKeyName:projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAMEenvMap: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 projectwhich contains your Cloud KMS service.
   • USERNAME_KEYRING_NAME: The key ring name ofyour Docker username.
   • USERNAME_KEY_NAME: The key nameof your Docker username.
   • ENCRYPTED_USERNAME: Your encryptedDocker username in base64 format.
   • PASSWORD_KEYRING_NAME: The key ring name ofyour Docker password.
   • PASSWORD_KEY_NAME: The key nameof your Docker password.
   • ENCRYPTED_PASSWORD: Your encryptedDocker password in base64 format.
   • REPOSITORY: The name of your Docker repository fromwhere you're pulling the image.

   • TAG: The tag name of your image.

     Note: ThesecretEnv field does not support substitution variables. Ifthe Google Cloud project hosting the key changes, the encrypted contentswithin that project also change.

3. Use the build config file tomanually start a buildor toautomate builds using triggers.

Configuring builds to use encrypted files

1. In your project root directory, create a Cloud Build build configfile namedcloudbuild.yaml orcloudbuild.json.

2. In your build config file, before any build steps that interact with the decryptedfile, add agcloud build step to decrypt the encrypted file using theencryption key. The following example build config file shows how to login toDocker using the encrypted file with Docker password:

   YAML

   steps:-name:gcr.io/cloud-builders/gcloudargs:-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/dockerentrypoint:bashargs:-"-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 ofyour Docker password.
   • KEY_NAME: The key nameof your Docker password.
   • ENCRYPTED_PASSWORD_FILE: Encrypted file with yourDocker password.
   • PLAINTEXT_PASSWORD_FILE: Plaintext file with yourDocker password.

3. Use the build config file tomanually start a buildor toautomate 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 thenewerway 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 asecrets field to specify the encryptedvalue and theCryptoKey to use to decrypt it. Then, in the build stepwhere you want to use the encrypted variable, add asecretEnv field tospecify the variable as an environment variable. Include the variable's namein thesecretEnv field. If you specify the variable value, or a non-secretenvironment variable with the same name, Cloud Build throws an error.

   YAML

   steps:-name:'gcr.io/cloud-builders/docker'entrypoint:'bash'args:['-c','dockerlogin--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-namesecretEnv: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"}}]}

What's next

• Learn how toconfigure builds to access secrets from Secret Manager.
• Learn how toaccess private GitHub repositories.