Shape the future of software delivery and make your voice heard by taking the 2021 State of DevOps survey.

Using encrypted credentials from Cloud KMS

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

Before you begin

  • Enable the Cloud Build and Cloud KMS APIs.

    Enable the APIs

  • To use the command-line examples in this guide, install and configure the Cloud SDK.

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

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

        base64 ENCRYPTED_FILE
    

Required IAM permissions

Grant the Cloud KMS CryptoKey Decrypter (roles/cloudkms.cryptoKeyDecrypter) 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.

Configuring builds to use encrypted data

  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:

    • After all the build steps, add an availableSecrets field to specify the encrypted value as an environment variable and the kmsKeyName to use to decrypt it. You can use substitution variables in the value of kmsKeyName.
    • In the build step where you want to specify the secret:
      • Add an entrypoint field pointing to bash to use the bash tool in the build step. This is required to refer to the environment variable for the secret.
      • Add a secretEnv field specifying the environment variable for the encrypted value.
      • In the args field, add a -c flag as the first argument. Any string you pass after -c is treated as a command. For more information on running bash commands with -c, see the bash documentation.
      • When specifying the encrypted value in the args field, specify it using the environment variable prefixed with $$.

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

  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)

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

What's next