Using secrets and credentials

This page explains how to include sensitive information such as passwords and API keys in Cloud Build.

Before including sensitive information in your builds, you must either store it in Secret Manager, or encrypt it using Cloud Key Management Service and only include the encrypted information in Cloud Build. Secret Manager is the recommended technique for managing sensitive data with Cloud Build. For existing projects, you can continue using Cloud KMS, but for new projects use Secret Manager.

Before you begin

To run the gcloud commands described in this page, install the gcloud command-line tool.

• If you've already installed Cloud SDK previously, make sure you have the latest available version by running gcloud components update.

Using Secret Manager

Secret Manager is a Google Cloud service that securely stores API keys, passwords, and other sensitive data.

To store data in Secret Manager and use that data in Cloud Build:

1. Enable the Secret Manager API:

   Enable the Secret Manager API

2. Grant the Secret Accessor IAM role to the Cloud Build service account:

   1. Open the IAM page in the Cloud Console:

      Open the IAM page

   2. Select your project and click Open.

   3. In the permissions table, locate the email ending with @cloudbuild.gserviceaccount.com, and click on the pencil icon.

   4. Add Secret Manager Secret Accessor role.

   5. Click Save.

3. Store data in Secret Manager:

   1. Go to the Secret Manager page in the Cloud Console:

      Go to the Secret Manager page

   2. On the Secret Manager page, click Create Secret.

   3. On the Create secret page, under Name, enter secret-name.

   4. In the Secret value field, enter your data.

   5. Leave the Regions section unchanged.

   6. Click the Create secret button.

   For instructions on using Secret Manager using the gcloud command-line tool, see the Secret Manager Quickstart. For instructions on granting access to a specific secret see managing access to secrets.

4. In your build config file, add a build step to access the secret version in Secret Manager and store it in a file. The following build step accesses secret-name and stores it in a file named decrypted-data.txt:

   YAML

   steps:
   - name: gcr.io/cloud-builders/gcloud
     entrypoint: 'bash'
     args: [ '-c', "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > decrypted-data.txt" ]
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/gcloud",
       "entrypoint": "bash",
       "args": [
         "-c",
         "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > decrypted-data.txt"
       ]
     }
     ]
   }
   

5. Use the file with the decrypted data in a build step. The following code snippet uses decrypted-data.txt to login to a private Docker registry:

   YAML

   steps:
   - name: gcr.io/cloud-builders/gcloud
     entrypoint: 'bash'
     args: [ '-c', "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > decrypted-data.txt" ]
   - name: gcr.io/cloud-builders/docker
     entrypoint: 'bash'
     args: [ '-c', 'docker login --username=my-user --password-stdin < decrypted-data.txt']
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/gcloud",
       "entrypoint": "bash",
       "args": [
         "-c",
         "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > password.txt"
        ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=my-user --password-stdin < decrypted-data.txt"
        ]
     }
     ]
   }
   

Note: To use the secret in an environment variable, you need to prefix the variable name with an underscore "_" and escape the value using '\('. For example: _VARIABLE_NAME=$(cat password.txt) && echo -n \)_VARIABLE_NAME.

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

Warning: Users who do not have permission to access secrets in Secret Manager, but who have permission to execute builds, can execute a build that uses information in Secret Manager using the Cloud Build service account's access. This means that if the Cloud Build service account has access to Secret Manager, any user who has access to create builds can access secrets stored in Secret Manager. This access is logged in the project's build history.

Using Cloud KMS

Cloud KMS is a Google Cloud service that enables you to manage and use cryptographic keys.

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

1. Enable the Cloud KMS API:

   Enable the Cloud KMS API

2. Grant the Cloud KMS CryptoKey Decrypter IAM role to the Cloud Build service account:

   1. In the Cloud Console, go to the Cloud Build Settings page:

      Open the Settings page

   2. Locate the row with the Cloud KMS CryptoKey Decrypter role and set its Status to ENABLED.

3. Open a terminal window.

4. Create a new Cloud KMS key-ring with name keyring-name:

     gcloud kms keyrings create keyring-name --location global
   

5. Create a new Cloud KMS key key-name for the key-ring keyring-name:

     gcloud kms keys create key-name \
         --location global --keyring keyring-name \
         --purpose encryption
   

6. Configure Cloud Build to use encrypted data:

   • To use encrypted variables:

     1. Encrypt secret-name using key-name and keyring-name. The encrypted value is a base64-encoded string. Ensure that you do not include any extraneous characters, such as spaces or newlines in secret-name. The -n flag instructs echo to not include a terminating newline:

         echo -n secret-name | gcloud kms encrypt --plaintext-file=- \
             --ciphertext-file=- --location=global --keyring=keyring-name \
             --key=key-name | base64
        

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

     Note: The kmsKeyName field and the secretEnv field do not support substitution variables. If the project ID hosting the key changes, the encrypted contents within that project also change.

   • To use encrypted files:

     1. Encrypt the file named secrets.json using keyring-name and keyring-name. This produces an encrypted file named secrets.json.enc. secrets.json must be no larger than 64 KiB.

         gcloud kms encrypt --plaintext-file=secrets.json \
             --ciphertext-file=secrets.json.enc \
             --location=global --keyring=keyring-name\
             --key=key-name
        

     2. In your build config file, before any build steps that interact with the decrypted secrets.json file, add a build step that calls the gcloud Cloud Build to decrypt secrets.json.enc using the encryption key. This build step is similar to the commands used to encrypt the file.

        YAML

         steps:
         - name: gcr.io/cloud-builders/gcloud
           args:
           - kms
           - decrypt
           - --ciphertext-file=secrets.json.enc
           - --plaintext-file=secrets.json
           - --location=global
           - --keyring=keyring-name
           - --key=key-name
           # more steps here
        

        JSON

         {
           "steps": [
            {
              "name": "gcr.io/cloud-builders/gcloud",
              "args": [
                "kms",
                "decrypt",
                "--ciphertext-file=secrets.json.enc",
                "--plaintext-file=secrets.json",
                "--location=global",
                "--keyring=keyring-name",
                "--key=key-name"
              ]
            }
            ]
         }
        

        After this step completes, any subsequent steps can use the decrypted secrets.json file. For example, you can use the secrets in this file to fetch external dependencies or to include secret tokens in Docker container images you build.

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

Warning: Users who do not have permission to use the key to decrypt, but who have permission to execute builds, can perform a build that uses the key to decrypt using the Cloud Build service account's access. This means that if the Cloud Build service account has access to a key, any user who has access to create builds can access the key. This access is logged in the project's build history.

What's next

• Learn about additional authenticated data.
• Learn more about the Cloud KMS object hierarchy.