Console
Start free

Using customer managed encryption keys

By default, Cloud Run encrypts customer content at rest. Cloud Run handles encryption for you without any additional actions on your part. This option is called Google default encryption.

If you want to control your encryption keys, then you can use customer-managed encryption keys (CMEKs) in Cloud KMS with CMEK-integrated services including Cloud Run. Using Cloud KMS keys gives you control over their protection level, location, rotation schedule, usage and access permissions, and cryptographic boundaries. Using Cloud KMS also lets you view audit logs and control key lifecycles. Instead of Google owning and managing the symmetric key encryption keys (KEKs) that protect your data, you control and manage these keys in Cloud KMS.

After you set up your resources with CMEKs, the experience of accessing your Cloud Run resources is similar to using Google default encryption. For more information about your encryption options, see Customer-managed encryption keys (CMEK).

To learn about protecting your data with CMEK on functions created using gcloud functions commands or the Cloud Functions v2 API, see Protect your data with CMEK.

You should be aware of the following:

CMEK with Cloud KMS Autokey

You can either create CMEKs manually to protect your Cloud Run resources or use Cloud KMS Autokey. With Autokey, key rings and keys are generated on demand to support resource creation in Cloud Run. Service agents that use the keys for encrypt and decrypt operations are created if they don't already exist and are granted the required Identity and Access Management (IAM) roles. For more information, see Autokey overview.

To set up CMEK manually, follow the instructions to configure CMEK for a service or a worker pool.

To set up CMEK using Autokey, follow the instructions to configure Autokeys for a service or a worker pool.

Autokey is not available for functions created using gcloud functions commands or the Cloud Functions v2 API.

Cloud KMS quotas and Cloud Run

You can set your CMEK to one of the available protection levels to indicate how cryptographic operations are performed. When you use CMEK in Cloud Run, your projects can consume Cloud KMS cryptographic requests quotas. For example, CMEK-encrypted repositories can consume these quotas for each upload or download.

Encryption and decryption operations using CMEK keys affect Cloud KMS quotas in these ways:

For more information, see Cloud KMS quotas.

Autoscaling behavior affected by CMEK

The expected autoscaling for your Cloud Run service can be impacted when you use customer managed encryption keys. For example, latency for starting new instances can increase due to delays in contacting external key management systems during key operations.

The following table shows the possible changes in behavior due to use of CMEK:

CMEK-related operation Autoscaling behavior
Key disabled/destroyed/revoked New instances won't start.
External key manager cannot be contacted If the key request can be retried, no instances are shutdown during the retries and no new instances will start. Scale-out can appear slower than expected.
If the key request cannot be retried, no new instances are started, and running instances are shut down after a waiting period.
KMS quota exceeded If this quota is exceeded, RESOURCE_EXHAUSTED errors are logged, and new instances won't start. You can request additional quota to fix this.

Before you begin

Allow Cloud Run to access a key

To use CMEK for Cloud Run, perform the following steps:

  1. Configure Artifact Registry to use CMEK.

  2. Using the Artifact Registry Docker Quickstart as a reference create a Docker repository push an image to it.

  3. Use an existing Cloud KMS symmetric key or create a new symmetric key.

  4. To allow Cloud Run access to the key, grant the Cloud Run service agent the Cloud KMS CryptoKey Encrypter/Decrypter role:

    Console

    1. Go to the Cryptographic keys page

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

    4. In the New principals field, copy the Cloud Run service agent email. It has the following suffix:

      service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com.

    5. In the Select a role field, select Cloud KMS CryptoKey Encrypter/Decrypter.

    6. Click Save

    gcloud

    Use the following gcloud kms command:

    gcloud kms keys add-iam-policy-binding KEY_NAME \
--keyring=KEYRING \
--location=LOCATION \
--member serviceAccount:service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com \
--role='roles/cloudkms.cryptoKeyEncrypterDecrypter'

    Replace the following:

    • KEY_NAME: the name of your key.
    • KEYRING: the name of your key ring.
    • LOCATION: the name of your region.
    • PROJECT_NUMBER: the project number where you intend to deploy the Cloud Run service or worker pool.

    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.

Configure CMEK for a 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

  • In the Google Cloud console, go to Cloud Run:

    Go to Cloud Run

  • Select Services from the Cloud Run navigation menu, and click Deploy container to configure a new service. If you are configuring an existing service, click the service, then click Edit and deploy new revision.

  • If you are configuring a new service, fill out the initial service settings page, then click Containers, Networking, Security to expand the service configuration page.

    • Click the Security tab.

    image

    Under Encryption:
    1. Select Cloud KMS key.
    2. For Key type, select Cloud KMS.
    3. From the Select a Cloud KMS key menu, choose one of the following options:

      4. To copy and paste the resource name from another project that you have access to:

    4. From the Key revocation action menu, choose one of the following options:

    5. Click Create or Deploy.

    gcloud

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

    gcloud run deploy SERVICE \
--image IMAGE_URL \
--key KEY \
--post-key-revocation-action-type KEY_REVOCATION_ACTION
--encryption-key-shutdown-hours SHUTDOWN_HOURS
     
    gcloud run services update SERVICE --key KEY
--post-key-revocation-action-type KEY_REVOCATION_ACTION
--encryption-key-shutdown-hours SHUTDOWN_HOURS

    Replace the following:

    YAML

    1. If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:

      gcloud run services describe SERVICE --format export > service.yaml

    2. Update the following CMEK annotations to the values that you want:

      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/KEYRING_NAME/cryptoKeys/KEY_NAME
        run.googleapis.com/post-key-revocation-action-type: KEY_REVOCATION_ACTION
        run.googleapis.com/encryption-key-shutdown-hours: SHUTDOWN_HOURS
      name: REVISION

      Replace the following:

      • SERVICE: the name of your Cloud Run service.
      • PROJECT_NAME: the name of the project the key was created in.
      • LOCATION: the location the key was created in. Must match the Cloud Run service location.
      • KEYRING_NAME: the name of the key ring.
      • KEY_NAME: the name of the key.
      • KEY_REVOCATION_ACTION: shut-down or prevent-new, depending on your key revocation preferences.
      • SHUTDOWN_HOURS: the number of hours to delay before the service shuts down after revocation.
      • REVISION with a new revision name or delete it (if present). If you supply a new revision name, it must meet the following criteria:
        • Starts with SERVICE-
        • Contains only lowercase letters, numbers and -
        • Does not end with a -
        • Does not exceed 63 characters

    3. Replace the service with its new configuration using the following command:

      gcloud run services replace service.yaml

    Terraform

    To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

    Add the following to a google_cloud_run_v2_service resource in your Terraform configuration.

    resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE"
  location = "europe-west1"

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    encryption_key = "projects/PROJECT_NAME/locations/LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME"
  }
}

    Replace the following:

    Use Autokey for services

    If you haven't already done so, Enable Cloud KMS Autokey.

    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

  • In the Google Cloud console, go to Cloud Run:

    Go to Cloud Run

  • Select Services from the Cloud Run navigation menu, and click Deploy container to configure a new service. If you are configuring an existing service, click the service, then click Edit and deploy new revision.

  • If you are configuring a new service, fill out the initial service settings page, then click Containers, Networking, Security to expand the service configuration page.

    • Click the Security tab.

    image

    Under Encryption:
    1. From the Key type menu, select Cloud KMS with Autokey.
    2. Click Request a key.
    3. Click Create.

      The key's details are shown after resource creation.

    4. From the Key revocation action menu, choose one of the following options:

    5. Click Create or Deploy.

    View security settings for services

    To view the security settings for your Cloud Run service:

    Console

    1. In the Google Cloud console, go to the Cloud Run Services page:

      Go to Cloud Run

    2. Click your service 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.

    gcloud

    1. Run the following command to view the security settings:

      gcloud run services describe SERVICE

    2. Locate the security setting in the returned configuration.

    Additional configuration for source-based deployments

    Cloud Run source deployments and functions involve an additional build step. To ensure the CMEK compliance of this step, you must do the following:

    1. Create your own CMEK-encrypted Cloud Storage bucket. For details, refer to the CMEK documentation for Cloud Storage.

    2. Upload your source code to the CMEK-encrypted storage bucket as a zipped archive file.

    3. Create your own CMEK-encrypted Artifact Registry repository. For details, refer to the CMEK documentation for Artifact Registry. This repository stores artifacts produced by the build process.

    4. Deploy the function, passing the build resources by using the --source and --image flags.

        gcloud run deploy FUNCTION \
        --key KEY \
        --source CUSTOM_BUCKET_WITH_SOURCE_CODE \
        --image CUSTOM_AR_REPOSITORY \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE \
        --region REGION

    Replace the following:

    Additionally, if you use Eventarc for triggering your functions, familiarize yourself with the CMEK configuration for Eventarc. In particular, full compliance in such cases requires encrypting channels corresponding to the event types being used.

    Test CMEK revocation for services

    To verify that CMEK protection is working, you can disable the key you used to enable CMEK for a service, then try to invoke your service:

    1. Run the following command to confirm the service is accessible: 

      curl SERVICE_URL

      Replace SERVICE_URL with the service URL. You can find this in the console UI after deployment: the container URL is displayed next to the text URL:.

    2. Disable the key version.

    3. Wait the number of SHUTDOWN_HOURS you specified. If you did not specify the number of shutdown hours, re-enable your key and edit or redeploy your service with the value set to the minimum of one hour. If you deployed source code, attempt to view the source code. The attempt should fail.

    4. After waiting the SHUTDOWN_HOURS duration you set re-run the following command and confirm the service is no longer accessible:

       curl SERVICE_URL

    5. After you have verified that the key version is disabled, enable the key.

    Configure CMEK for a worker pool

    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

  • In the Google Cloud console, go to Cloud Run:

    Go to Cloud Run

  • Select Worker pools from the menu, and click Deploy container to configure a new worker pool. If you are configuring an existing worker pool, click the worker pool, then click Edit and deploy new revision.

  • If you are configuring a new worker pool, fill out the initial worker pool page, then click Containers, Networking, Security to expand the worker pools configuration page.

    • Click the Security tab.

    image

    Under Encryption:
    1. Select Cloud KMS key.
    2. For Key type, select Cloud KMS.
    3. From the Select a Cloud KMS key menu, choose one of the following options:

      4. To copy and paste the resource name from another project that you have access to:

    4. From the Key revocation action menu, choose one of the following options:

    5. Click Create or Deploy.

    gcloud

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

    gcloud run worker-pools deploy WORKER_POOL \
--image IMAGE_URL \
--key KEY \
--post-key-revocation-action-type KEY_REVOCATION_ACTION
--encryption-key-shutdown-hours SHUTDOWN_HOURS
     
    gcloud run worker-pools update WORKER_POOL --key KEY
--post-key-revocation-action-type KEY_REVOCATION_ACTION
--encryption-key-shutdown-hours SHUTDOWN_HOURS

    Replace the following:

    YAML

    1. If you are creating a new worker pool, skip this step. If you are updating an existing worker pool, download its YAML configuration:

      gcloud run worker-pools describe WORKER_POOL --format export > workerpool.yaml

    2. Update the following CMEK annotations in the WorkerPool configuration:

      apiVersion: run.googleapis.com/v1
kind: WorkerPool
metadata:
  name: WORKER_POOL
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/encryption-key: projects/PROJECT_NAME/locations/LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME
        run.googleapis.com/post-key-revocation-action-type: KEY_REVOCATION_ACTION
        run.googleapis.com/encryption-key-shutdown-hours: SHUTDOWN_HOURS

      Replace the following:

      • WORKER_POOL: the name of your worker pool.
      • PROJECT_NAME: the name of the project the key was created in.
      • LOCATION: the location the key was created in. Must match the Cloud Run worker pool location.
      • KEYRING_NAME: the name of the key ring.
      • KEY_NAME: the name of the key.
      • KEY_REVOCATION_ACTION: shut-down or prevent-new, depending on your key revocation preferences.
      • SHUTDOWN_HOURS: the number of hours to delay before the worker pool shuts down after revocation.

    3. Replace the worker pool with its new configuration using the following command:

      gcloud run worker-pools replace workerpool.yaml

    Use Autokey for worker pools

    If you haven't already done so, Enable Cloud KMS Autokey.

    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

  • In the Google Cloud console, go to Cloud Run:

    Go to Cloud Run

  • Select Worker pools from the menu, and click Deploy container to configure a new worker pool. If you are configuring an existing worker pool, click the worker pool, then click Edit and deploy new revision.

  • If you are configuring a new worker pool, fill out the initial worker pool page, then click Containers, Networking, Security to expand the worker pools configuration page.

    • Click the Security tab.

    image

    Under Encryption:
    1. From the Key type menu, select Cloud KMS with Autokey.
    2. Click Request a key.
    3. Click Create.

      The key's details are shown after resource creation.

    4. From the Key revocation action menu, choose one of the following options:

    5. Click Create or Deploy.

    View security settings for worker pools

    To view the security settings for your Cloud Run worker pool:

    Console

    1. In the Google Cloud console, go to the Cloud Run worker pools page:

      Go to Cloud Run worker pools

    2. Click your worker pool to open the Worker pools details page.

    3. Click the Revisions tab.

    4. Locate the security setting in the configuration details.

    gcloud

    1. Use the following command:

      gcloud run worker-pools describe WORKER_POOL

    2. Locate the security setting in the returned configuration.

    Understand audit logs and error messages

    If you are responsible for monitoring audit logs, one of your tasks might be to verify CMEK operations in your Cloud Run service or worker pool. In this case, you need to understand the related audit logs.

    If you are responsible for addressing and fixing runtime errors for your Cloud Run service or worker pool, you might need to troubleshoot CMEK-related errors logged during the operation of the Cloud Run resource.

    The following sections provide information needed for the preceding tasks.

    Audit logs

    KMS audit logs provide an audit trail for every operation performed with a key. For CMEK-enabled Cloud Run resources, Cloud Run adds Cloud Run-specific caller context that details why the customer key was accessed by the system. The following table lists the contexts you might see in the audit logs:

    Reason for key access Description
    Decrypting CMEK-encrypted layer during container clone start. Logged whenever a new instance is started.
    Encrypting a newly created data-encryption-key w/ the customer-managed-encryption-key. Logged during deployment of a CMEK-enabled service or worker pool, where the data encryption key is wrapped by the CMEK.
    Decrypting an existing encrypted data-encryption-key, under the same customer-managed-encryption-key, to be used to encrypt container contents. Logged when a new instance starts up, which requires decryption of the image.
    Performing an encrypt operation on dummy data to check the customer-managed-encryption-key status and access. Logged whenever there is a validation check on the key, which is done periodically.
    Performing a decrypt operation on dummy data to check the customer-managed-encryption-key status and access. Logged whenever there is a validation check on the key, which is done periodically.

    For specifics about audit log format and content, refer to the KMS audit logging page.

    Error messages

    Note that error messages provided by an external key manager are directly passed through to the Cloud Run logs for your service.

    The following table lists the CMEK-related error messages you might see, along with descriptions and possible remedies.

    Message Description
    User's service account does not have CMEK decrypter permission. Service account: %s Remedy: Allow the Cloud Run resource to access the key
    User's KMS operation quota has been exceeded. CMEK key: %s The CMEK-enabled resource has exceeded KMS quotas. Remedy: Request more KMS quota
    User's CMEK key has been disabled. CMEK key: %s The CMEK was revoked. Remedy: Change the resource's CMEK and redeploy it.
    User's CMEK key has been destroyed. CMEK key: %s The CMEK was deleted. Remedy: Change the resource's CMEK and redeploy it.
    User's CMEK key has been scheduled for deletion. CMEK Key: %s The CMEK was scheduled for deletion. Remedy: Change the resource's CMEK and redeploy it.

    What's next