Using customer managed encryption keys

This topic shows how to protect Cloud Run services and data related to those services using Cloud KMS customer managed encryption keys (CMEK). This feature allows containers to be deployed with a CMEK key to protect the container image content.

You should be aware of the following:

  • File metadata, such as the file path, is not encrypted.
  • If a CMEK key is disabled, the container image cannot be deployed and new instances cannot start.

Because the CMEK key is within your control and is not controlled by Google, no one, including Google, can access the data protected by these encryption keys when the keys are disabled or destroyed.

Allowing Cloud Run to access a key

You can use an existing Cloud KMS symmetric key or you can create a new symmetric key. However, in order to allow a Cloud Run service to access the key, you must add the Cloud Run service account as a Member of the key, and grant it the Cloud KMS CryptoKey Encrypter/Decrypter role:

Console

  1. Go to the Cryptographic keys page in the Cloud Console

  2. Click the key ring for your key to open its key list page.

  3. Select the key and in the right side permissions tab, click Add Member.

  4. In the New members textbox, copy the email of the Cloud Run service agent. It has the suffix @serverless-robot-prod.iam.gserviceaccount.com.

  5. Grant it the role Cloud KMS CryptoKey Encrypter/Decrypter.

Command line

Use the following gcloud kms command:

gcloud kms keys add-iam-policy-binding 
(KEY : --keyring=KEYRING --location=LOCATION)
--member=MEMBER --role='roles/cloudkms.cryptoKeyEncrypterDecrypter'

Replace

  • KEYRING with the name of your key ring.
  • LOCATION with the name of your region.
  • MEMBER with the email of the Cloud Run service agent. It has the suffix @serverless-robot-prod.iam.gserviceaccount.com.

You need permission to administer Cloud KMS resources in the Google Cloud project to grant the IAM role roles/cloudkms.cryptoKeyEncrypterDecrypter. Only IAM members with Owner (roles/owner) or Cloud KMS Admin (roles/cloudkms.admin) roles can grant or revoke access to Cloud KMS resources.

Enabling CMEK for a Cloud Run service:

Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.

Console

  1. Go to Cloud Run

  2. Click Create Service if you are configuring a new service you are deploying to. If you are configuring an existing service, click on the service, then click Edit and Deploy New Revision.

  3. If you are configuring a new service, fill out the initial service settings page as desired, then click Next > Advanced settings to reach the service configuration page.

  4. Click the Security tab.

    image

  5. Select the checkbox Use a customer-managed encryption key (CMEK) , then select the desired key from the Select a customer-managed key pulldown menu.

  6. Click Create or Deploy.

Command line

To set a key on a service, use either of the following commands:

gcloud beta run deploy SERVICE --image IMAGE_URL --key KEY
gcloud beta run services update SERVICE --key KEY

Replace

  • SERVICE with the name of your service.
  • IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest
  • KEY with the fully qualified key name, in this format:projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME

YAML

You can download and view existing service configuration using the gcloud run services describe --format export command, which yields cleaned results in YAML format. You can then modify the fields described below and upload the modified YAML using the gcloud beta run services replace command. Make sure you only modify fields as documented.

  1. To view and download the configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. Update the run.googleapis.com/encryption-key annotation:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
        metadata:
          annotations:
            run.googleapis.com/encryption-key: projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME

    Replace

    • SERVICE with the name of your Cloud Run service.
    • PROJECT_NAME with the name of the project the key was created in.
    • LOCATION with the location the key was created in. Must match the Cloud Run service location.
    • RING_NAME with the name of the key ring.
    • KEY_NAME with the name of the key.
  3. Replace the service with its new configuration using the following command:

    gcloud beta run services replace service.yaml

Referencing keys from other projects

You can reference a key from another project, if your project's service account has been allowed to encrypt/decrypt the key.

Console

  1. Go to Cloud Run

  2. Click Create Service if you are configuring a new service you are deploying to. If you are configuring an existing service, click on the service, then click Edit and Deploy New Revision.

  3. If you are configuring a new service, fill out the initial service settings page as desired, then click Next > Advanced settings to reach the service configuration page.

  4. Click the Security tab.

    image

  5. In the Security tab:

    1. Select the checkbox Use a customer-managed encryption key (CMEK) .
    2. Select Don't see your key? Enter key resource ID from the Select a customer-managed key pulldown list, to display the following form:

      Cross project keys

    3. In the Add a secret by resource ID form, enter the secret from the other project, in the format projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME. You can alternatively copy and paste the resource ID from the other project if you have access to it, by selecting the key, clicking the Actions ellipsis at the right of the secret, and selecting Copy resource ID from the pulldown menu.
    4. Click Deploy.

  6. Click Create or Deploy.

Command line

To set a key on a service, use one of the following commands:

gcloud beta run deploy SERVICE --image IMAGE_URL --key KEY
gcloud beta run services update SERVICE --key KEY

Replace

  • SERVICE with the name of your service.
  • IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest
  • KEY with the fully qualified key name, in this format:projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME

Viewing security settings

To view the current security settings for your service:

Console

  1. Go to Cloud Run

  2. Click the service you are interested in to open the Service details page.

  3. Click the Revisions tab.

  4. In the details panel at the right, the security setting is listed under the Security tab.

Command line

  1. Use the following command:

    gcloud run services describe SERVICE
  2. Locate the security setting in the returned configuration.

What's next