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-data.

    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-data 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-data --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-data --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-data --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-data --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"
         ]
      }
      ]
    }
    
  6. Use the build config file to manually start a build or to automate builds using triggers.

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-data 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-data. The -n flag instructs echo to not include a terminating newline:

         echo -n secret-data | 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"
                }
             }
             ]
         }
        
    • 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.

What's next