Protect your data with CMEK

Note: This content applies only to Cloud Run functions—formerly Cloud Functions (2nd gen).

For the 1st gen version of this document, see Protect your data with CMEK (1st gen).

By default, Cloud Run functions encrypts customer content at rest. Cloud Run functions 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 functions. 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 life cycles. 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 functions resources is similar to using Google default encryption. For more information about your encryption options, see Customer-managed encryption keys (CMEK).

The following types of Cloud Run functions data are encrypted when using a CMEK:

• Function source code uploaded for deployment and stored by Google in Cloud Storage, used in the build process.
• The results of the function build process, including:
  • The container image built from your function source code.
  • Each instance of the function that is deployed.

The function build process itself is protected by an ephemeral key uniquely generated for each build. See CMEK compliance in Cloud Build for more information. Additionally, note the following:

• File metadata, such as file system paths or modification timestamps, is not encrypted.

• If a key is disabled, the container image cannot be deployed and new instances cannot start.

• Cloud Run functions CMEK protection only applies to Google-managed Cloud Run functions resources; you are responsible for protecting data and resources managed by you, such as your source code repositories, event channels that live in the customer project, or any services used by your functions.

Setting up CMEK for Cloud Run functions entails the following:

• Granting the necessary service accounts access to the key:

  • For all functions, you need to grant the Cloud Run functions, Artifact Registry, and Cloud Storage service accounts access to the key.

  • For event-driven Cloud Run functions, you also need to complete CMEK setup for Cloud Run and Eventarc.

• Creating a CMEK-protected Artifact Registry repository to store your function images.

• Enabling CMEK on your function.

• Optionally, enable CMEK organization policies to enforce all new functions to be CMEK compliant.

These steps are described in more detail below.

Before you begin

1. Create a single-region key to use to encrypt your functions. To learn how to create a key, see Creating symmetric encryption keys.

2. Create an Artifact Registry repository that has CMEK enabled. You must use the same key for the Artifact Registry repository as you do when enabling CMEK for a function.

3. For event-driven functions, follow the additional setup steps outlined in Enable CMEK for a Google channel.

Granting service accounts access to the key

For all functions, you must grant the following service accounts access to the key:

• Cloud Run functions service agent ([e-mail])

• Artifact Registry service agent ([e-mail])

• Cloud Storage service agent ([e-mail])

You must additionally grant the following service accounts access to the key:

• Cloud Run service agent ([e-mail])

• Eventarc service agent ([e-mail])

To grant these service accounts access to the key, add each service account as a principal of the key and then grant the service account the Cloud KMS CryptoKey Encrypter/Decrypter role:

Console

1. Go to the Cloud Key Management Service page in the Google Cloud console:
   Go to the Cloud KMS page

2. Click the name of the key ring that contains the chosen key.

3. Click the name of the key to view the key details.

4. In the Permissions tab, click Grant access.

5. In the New principals field, enter the email addresses of all three service accounts discussed earlier to assign permissions to all three accounts at once.

6. In the Select a role menu, select Cloud KMS CryptoKey Encrypter/Decrypter.

7. Click Save.

gcloud

For each service account discussed earlier, run the following command:

gcloud kms keys add-iam-policy-binding KEY \
--keyring KEY_RING \
--location LOCATION \
--member serviceAccount:SERVICE_AGENT_EMAIL \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter

Replace the following:

• KEY: The name of the key. For example, my-key.

• KEY_RING: The name of the key ring. For example, my-keyring.

• LOCATION: The location of the key. For example, us-central1.

• SERVICE_AGENT_EMAIL: The email address of the service account.

Important: Some service agents, such as the Cloud Storage service agent (including its email address), are not initially available when you create a project. Instead, they are activated the first time you access them. For example, to activate the Cloud Storage service agent, you can retrieve its email address. The service agent must be activated prior to assigning permissions to it.

Enabling CMEK for a function

After setting up an Artifact Registry repository with CMEK enabled and granting Cloud Run functions access to your key, you're ready to enable CMEK for your function.

To enable CMEK for a function:

Console

1. Go to the Cloud Run functions page in the Google Cloud console:
   Go to the Cloud Run functions page

2. Click the name of the function you want to enable CMEK on.

3. Click Edit.

4. Click Runtime, build... to expand the advanced configuration options.

5. Select the Security and image repo tab.

6. In the Encryption section, select Customer-managed encryption key (CMEK).

7. Select your chosen key from the drop-down.

8. Under Container location, select Customer-managed Artifact Registry.

9. In the Artifact registry drop-down, select the CMEK-protected repository.

10. Click Next.

11. Click Deploy.

gcloud

Run the following command.

gcloud functions deploy FUNCTION \
[--gen2] \
--kms-key=KEY \
--docker-repository=REPOSITORY \
--source=YOUR_SOURCE_LOCATION
FLAGS...

Replace the following:

• FUNCTION: The name of the function to enable CMEK on. For example, cmek-function.

• KEY: The fully qualified key name, in the following format: projects/PROJECT_NAME/locations/LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME.

• REPOSITORY: The fully qualified Artifact Registry repository name, in the following format: projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY.

• YOUR_SOURCE_LOCATION: When enabling CMEK for a pre-existing function, make sure that the intended source code is being re-deployed by specifying this parameter explicitly.

• FLAGS...: Additional flags that may be required to deploy your function, particularly for create deployments. For details, see Deploy a Cloud Run function.

CMEK is enabled for the function.

Note: First-time function deployments with CMEK enabled might fail due to IAM propagation delays. If you encounter an error upon deployment, ensure the permissions are set correctly and try again after a short period.

Note that Cloud Run functions always uses the primary version of a key for CMEK protection. You cannot specify a particular key version to use when enabling CMEK for your functions.

If a key is destroyed or disabled, or the requisite permissions on it are revoked, active instances of functions protected by that key are not shut down. Function executions already in progress will continue to run, but new executions will fail as long as Cloud Run functions does not have access to the key.

Testing CMEK protection

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

1. Disable the key used to protect your function.

   Note: It may take up to three hours for the changes to propagate.

2. Attempt to view the source code associated with this function. The attempt should fail.

3. Attempt to trigger the CMEK-protected function. The attempt should fail.

4. After you have verified that CMEK protection is working, enable the key.

The function's CMEK protection is now confirmed.

What's next

• Learn how to rotate your keys.
• Learn more about Google default encryption.
• Learn more about CMEK.
• Learn more about CMEK organization policies.