Configure CMEK for Cloud Logging

This document describes how to configure and manage customer-managed encryption keys (CMEK) for Cloud Logging to meet your organization's compliance needs. CMEK for the Logging is configured at the Google Cloud organization level. It applies to all Google Cloud projects and folders contained by the Google Cloud organization.

Overview

By default, Cloud Logging encrypts customer content stored at rest. Data ingested by Logging is encrypted using key-encryption keys, a process known as envelope encryption. Access to your logging data requires access to those key-encryption keys, which Google manages for you without any actions on your part.

Your organization might have regulatory, compliance-related, or advanced encryption requirements that our default encryption at rest doesn't provide. To meet your organization's requirements, instead of Google managing the encryption keys that protect your data, you can configure CMEK to control and manage your own encryption.

For specific information about CMEK, including its advantages, and limitations, see Customer-managed encryption keys.

When you configure CMEK as a default resource setting for Logging, new log buckets in the organization are automatically encrypted with the configured key. However, you can change that key or create log buckets and specify a different key. For more information, see Configure CMEK for log buckets.

Prerequisites

To get started, complete the following steps:

There are some limitations when using CMEK. Before you create a log bucket with CMEK enabled, review the Limitations.
Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

This guide provides instructions using the Google Cloud CLI.
Identify the organization for which you want to enable CMEK.
To get the permissions that you need to create keys, ask your administrator to grant you the Cloud KMS Admin (roles/cloudkms.admin) IAM role on the project or a parent resource. For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.
Ensure that you have the following Cloud Logging permissions for the organization:
- logging.settings.get
- logging.settings.update
Enable the Cloud KMS API for the Google Cloud project that runs Cloud KMS.
Create a key ring and keys for the Google Cloud project that runs Cloud KMS.

Cloud Logging lets you use a key from any region as a single organization may have data routed to multiple regions. However, when you create a log bucket, the location of the log bucket must match the location of the key. For information about supported regions, see the following:
- Cloud KMS locations
- Logging Supported regions
If you configure CMEK as a default resource setting for Logging by using the steps in this document, then new log buckets created in the organization are automatically configured for CMEK. Also, because the location of a log bucket must match the location of the key, after you configure CMEK as a default resource setting, you can't create log buckets in the global region.
Identify values for the following parameters:
- ORGANIZATION_ID is the unique numeric identifier of the Google Cloud organization for which you are enabling CMEK.
- KMS_PROJECT_ID is the unique alphanumeric identifier, composed of your Google Cloud project name and a randomly assigned number, of the Google Cloud project running Cloud KMS.
- KMS_KEY_LOCATION is the Cloud KMS key's region.
- KMS_KEY_RING is the Cloud KMS key ring's name.
- KMS_KEY_NAME with the Cloud KMS key's name. It is formatted like this: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEYRING/cryptoKeys/KEY
For information about locating resource identifiers, see Identifying projects and Getting your organization ID.

Enable CMEK for an organization

After you've completed the prerequisite steps, follow these instructions to enable CMEK for your Google Cloud organization.

Determine the service account ID

To determine the service-account ID associated with the organization for which CMEK will apply, run the following gcloud logging settings describe command:

gcloud logging settings describe --organization=ORGANIZATION_ID

Running the previous command generates a service account for the organization, when one doesn't exist already, and returns the ID in the kmsServiceAccountId field:

kmsServiceAccountId: cmek-p12345@gcp-sa-logging.iam.gserviceaccount.com
name: organizations/ORGANIZATION_ID/settings

In this example, the value of CMEK_SERVICE_ACCOUNT_ID is cmek-p12345.

Run the provisioning process only once per resource. Running the describe command multiple times returns the same value for the kmsServiceAccountId field.

If your organization doesn't support the Google Cloud CLI, then run the Cloud Logging API method getSettings.

Assign the Encrypter/Decrypter role

To use CMEK, give the service account permission to use your Cloud KMS by assigning the Cloud KMS CryptoKey Encrypter/Decrypter role to the service account:

gcloud

gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member serviceAccount:CMEK_SERVICE_ACCOUNT_ID@gcp-sa-logging.iam.gserviceaccount.com \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME

Set the variables in the command as follows:

Replace SERVICE_ACCOUNT_ID with the serviceAccountId value that you determined in the previous step.
Replace the other variables with the values you determined in the prerequisite steps.

Console

Open the Cloud Key Management Service Keys browser in the Google Cloud console.
Open the Cloud KMS Keys browser
Click on the name of the key ring that contains the desired key.
Select the checkbox for the desired key.

The Permissions tab becomes available.
In the Add members dialog, specify the email address of the Logging service account you are granting access.
In the Select a role drop down, select Cloud KMS CryptoKey Encrypter/Decrypter.
Click Add.

Configure the organization policies

Logging supports organization policies that can require CMEK protection and can limit which Cloud KMS CryptoKeys can be used for CMEK protection:

When logging.googleapis.com is in the Deny policy list of services for the constraint constraints/gcp.restrictNonCmekServices, Logging refuses to create new user-defined buckets that aren't CMEK-protected. However, this constraint doesn't prevent Cloud Logging from creating the _Required and _Default log buckets which are created when a Google Cloud project is created.
When constraints/gcp.restrictCmekCryptoKeyProjects is enforced, Logging creates CMEK-protected resources that are protected by a CryptoKey from an allowed project, folder, or organization.

For more information about CMEK and organization policies, see CMEK organization policies.

When an organization policy that specifies a CMEK constraint exists, ensure that those constraints are consistent with the default resource settings for Cloud Logging. Further, if you plan to modify your default resource settings, before you update the default resource settings, review and, if necessary, update the organization policies.

To view or configure organization policies, do the following:

Go to the Organization Policies page in the Google Cloud console and select your organization:

Go to the Organization Policies page
Verify, and if necessary, update the constraints specific to CMEK.

For information about how to modify an organization policy, see Creating and editing policies.

Configure Cloud Logging with the Cloud KMS key

To configure CMEK as a default resource setting for Logging, run the following gcloud logging settings update command:

gcloud logging settings update \
    --organization=ORGANIZATION_ID \
    --kms-location=KMS_KEY_LOCATION \
    --kms-key-name=KMS_KEY_NAME \
    --kms-keyring=KMS_KEY_RING \
    --kms-project=KMS_PROJECT_ID

The previous command updates the default resource settings to store information about the Cloud KMS key. If you have set a default storage location for your organization, then the value of the KMS_KEY_LOCATION field must agree with the default storage location. To set the key and the default storage location, append the following to the previous command:

--storage-location = KMS_KEY_LOCATION

After the key is applied, new log buckets in the organization are configured to encrypt their data at rest using this key. You can also change keys for individual log buckets. You can't create log buckets in the global region because you must use a key whose region matches the regional scope of your data.

If your organization doesn't support the Google Cloud CLI, then run the Cloud Logging API method updateSettings.

Verify key enablement

To verify that you've successfully enabled CMEK for your organization, run the following gcloud logging settings describe command:

gcloud logging settings describe --organization=ORGANIZATION_ID

The previous command returns the Cloud KMS key name:

kmsKeyName: KMS_KEY_NAME
kmsServiceAccountId: CMEK_SERVICE_ACCOUNT_ID@gcp-sa-logging.iam.gserviceaccount.com

If the kmsKeyName field is populated, then CMEK is enabled for your organization.

Route logs to supported destinations

Cloud Logging log buckets can be configured to encrypt data with CMEK. When you configure CMEK as a default resource setting for Logging for an organization, new log buckets in the organization automatically use CMEK. You can change the key of these log buckets and you can create log buckets that use a different KMS key than the one specified by the organization policy.

For information about CMEK as applied to log buckets, including how to change keys and limitations when you enable CMEK on a log bucket, see Configure CMEK for log buckets.
Cloud Storage supports CMEK for routing logs. For instructions about how to configure CMEK for Cloud Storage, see Using customer-managed encryption keys.

If data is lost due to key unavailability when routing logs data to Cloud Storage, then you can retroactively copy logs in bulk to Cloud Storage when those logs are also stored in a log bucket. For details, see Copy log entries.
BigQuery, by default, encrypts customer content stored at rest. For details, see Protecting data with Cloud Key Management Service keys.
Pub/Sub, by default, encrypts customer content stored at rest. For details, see Configuring message encryption.

Manage your Cloud KMS key

The following sections explain how to change, revoke access for, or disable your Cloud KMS key.

Change your Cloud KMS key

To change the Cloud KMS key associated with your organization, create a key and update the CMEK settings for the organization with the new Cloud KMS key name.

Run the following Google Cloud CLI command:

gcloud logging settings update \
    --organization=ORGANIZATION_ID
    --kms-key-name=NEW_KMS_KEY_NAME
    --kms-location=NEW_KMS_KEY_LOCATION \
    --kms-keyring=NEW_KMS_KEY_RING \
    --kms-project=NEW_KMS_PROJECT_ID

If you have set a default storage location for your organization, then the value of the NEW_KMS_KEY_LOCATION field must agree with the default storage location. To update the key and the default storage location, append the following to the previous command:

--storage-location = NEW_KMS_KEY_LOCATION

Revoke access to the Cloud KMS key

To revoke Logging's access to the Cloud KMS key at any time, remove the configured service account's IAM permission for that key.

If you remove Logging's access to a key, then it can take up to one hour for the change to take effect.

Run the following Google Cloud CLI command:

gcloud kms keys remove-iam-policy-binding \
    --project=KMS_PROJECT_ID \
    --member serviceAccount:CMEK_SERVICE_ACCOUNT_ID@gcp-sa-logging.iam.gserviceaccount.com \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
    --location=KMS_KEY_LOCATION \
    --keyring=KMS_KEY_RING \
    KMS_KEY_NAME

Disable CMEK for your organization

Disabling CMEK for your organization removes CMEK policy enforcement for future operations only; any previously applied configurations remain intact.

To disable CMEK for your organization, run the following Google Cloud CLI command:

gcloud logging settings update --organization=ORGANIZATION_ID --clear-kms-key

If you want to destroy your key, see Destroying and restoring key versions.

Cloud KMS key rotation considerations

Cloud Logging doesn't automatically rotate the encryption key for temporary disaster recovery files when the Cloud KMS key associated with the Google Cloud organization rotates. Existing recovery files continue to use the key version with which they were created. New recovery files use the current primary key version.

Limitations

The following are known limitations when you configure CMEK as a default resource setting for Logging.

Organization-level configuration only

You can only configure CMEK as a default resource setting for Logging for Google Cloud organizations. Once configured, CMEK propagates to all Google Cloud projects and folders in the Google Cloud organization.

Disaster recovery file unavailability

A Cloud KMS key is considered available and accessible by Logging when both of the following are true:

The key is enabled.
The Logging service account has encrypt and decrypt permissions on the key.

If Logging loses access to the Cloud KMS key, then Logging is unable to write temporary disaster-recovery files and, for users, queries stop functioning. Query performance may remain degraded even after key access is restored.

Routing logs to Cloud Storage might also be affected because the Logging is unable to write temporary files required to facilitate the routing. If an error is encountered while encrypting or decrypting data, then a notification is sent to the Google Cloud project that contains the Cloud KMS key.

Client library availability

Logging client libraries don't provide methods for configuring CMEK.

Degradation due to Cloud EKM key unavailability

When you use a Cloud EKM key, Google has no control over the availability of your externally managed key in the external key-management partner system.

For organization-level CMEK, if an externally managed key is unavailable, Cloud Logging continually retries accessing the key. Cloud Logging also buffers the incoming log data for up to one hour. After an hour, if Cloud Logging is still unable to access the externally managed key, Cloud Logging begins dropping the data.

For bucket-level CMEK, if an externally managed key is unavailable, Cloud Logging continues ingesting data but users won't be able to access that data.

See the Cloud External Key Manager documentation for more considerations, and potential alternatives, when using external keys.

Limitations on log buckets

For limitations when you use CMEK with log buckets, see Limitations.

Quotas

For details on Logging usage limits, see Quotas and limits.

Troubleshoot configuration errors

For information about troubleshooting CMEK configuration errors, see Troubleshoot CMEK and organization setting errors.