By default, Eventarc encrypts customer content at rest. Eventarc 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 Eventarc. 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 Eventarc resources is similar to using Google default encryption. For more information about your encryption options, see Customer-managed encryption keys (CMEK).
Customer-managed encryption keys are stored as software keys, in a Cloud HSM cluster, or externally using Cloud External Key Manager.
What is protected with CMEK
You can configure CMEK to encrypt the event messages that pass through the following resources:
MessageBus
—An Eventarc Advanced busPipeline
—An Eventarc Advanced pipelineGoogleApiSource
—A resource which represents a subscription to Google API events for a particular bus
For more information, see the Eventarc Advanced overview.
When you enable CMEK for a resource, it protects the data associated with the resource in that region by using an encryption key that only you can access.
Cloud KMS and Eventarc are regionalized services. The region for the Cloud KMS key and the protected Eventarc Advanced resource must be the same.
Before you begin
Before using this feature in Eventarc, you must perform the following actions:
Console
-
Enable the Cloud KMS and Eventarc APIs.
- Create a key ring.
- Create a key for a specified key ring.
gcloud
- Update
gcloud
components.gcloud components update
- Enable the Cloud KMS and Eventarc APIs for
the project that will store your
encryption keys.
gcloud services enable cloudkms.googleapis.com eventarc.googleapis.com
- Create a key ring.
- Create a key for a specified key ring.
For information on all flags and possible values, run the command with the
--help
flag.
Grant the Eventarc service account access to a key
To grant the Eventarc service account access to the Cloud KMS key, add the service account as a principal of the key, and grant the service account the Cloud KMS CryptoKey Encrypter/Decrypter role:
Console
When you enable CMEK for a bus or pipeline using the Google Cloud console, you are prompted to grant the Cloud KMS CryptoKey Encrypter/Decrypter role to the service account. For more information, in this document, see Enable CMEK for a bus or Enable CMEK for a pipeline.
gcloud
gcloud kms keys add-iam-policy-binding KEY_NAME \ --keyring KEY_RING \ --location REGION \ --member serviceAccount:SERVICE_AGENT_EMAIL \ --role roles/cloudkms.cryptoKeyEncrypterDecrypter
Replace the following:
KEY_NAME
: the name of the key—for example,my-key
KEY_RING
: the name of the key ring—for example,my-keyring
REGION
: the location of the key—for example,us-central1
SERVICE_AGENT_EMAIL
: the email address of the service account with theeventarc.serviceAgent
roleFor example,
service-PROJECT_NUMBER@gcp-sa-eventarc.iam.gserviceaccount.com
. For more information, see Service agents.
Enable CMEK for a bus
When you enable CMEK for an Eventarc Advanced bus, all messages that pass through the bus are fully encrypted with that CMEK key.
Console
In the Google Cloud console, go to the Eventarc > Bus page.
You can create a bus or, if you are updating a bus, click the name of the bus.
In the Bus details page, click
Edit.In the Edit bus page, for Encryption, select Cloud KMS key.
In the Key type list, select a method to manage your keys.
You can manage your keys manually or you can use Autokey which lets you generate key rings and keys on-demand. If the Autokey option is disabled, it isn't yet integrated with the current resource type.
Select a customer-managed key.
Optional: To manually enter the resource name of the key, in the Select a customer-managed key list, click Enter key manually, and enter the key name in the specified format.
If prompted, grant the
cloudkms.cryptoKeyEncrypterDecrypter
role to the Eventarc Service Agent.Click Save.
gcloud
Use the
gcloud beta eventarc message-buses update
command to enable CMEK for your bus:
gcloud beta eventarc message-buses update BUS_NAME \ --location=REGION \ --crypto-key=KEY
Replace the following:
BUS_NAME
: the ID or fully qualified identifier of your busREGION
: a supported Eventarc Advanced locationKEY
: the fully qualified Cloud KMS key name in the formatprojects/PROJECT_NAME/locations/REGION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
The
REGION
of the key must match the location of the bus to be protected.
Verify Cloud KMS usage
Verify that the bus is now CMEK-compliant.
Console
In the Google Cloud console, go to the Eventarc > Bus page.
Click the name of the bus that you have protected using CMEK.
On the Bus details page, the Encryption status displays the message,
Event messages encrypted using customer-managed encryption keys
.
gcloud
Use the
gcloud beta eventarc message-buses describe
command to describe your bus:
gcloud beta eventarc message-buses describe BUS_NAME \ --location=REGION
The output should be similar to the following:
cryptoKeyName: projects/PROJECT_ID/locations/REGION/keyRings/RING_NAME/cryptoKeys/KEY_NAME name: projects/PROJECT_ID/locations/REGION/messageBuses/BUS_NAME updateTime: '2022-06-28T17:24:56.365866104Z'
The cryptokeyName
value shows the Cloud KMS key used for the
bus.
Disable CMEK for a bus
You can disable the CMEK protection associated with a bus. The events that are delivered through the bus are still protected by Google-owned and Google-managed keys.
Console
In the Google Cloud console, go to the Eventarc > Bus page.
Click the name of the bus.
In the Bus details page, click
Edit.On the Edit bus page, clear the Use a customer-managed encryption key (CMEK) checkbox.
Click Save.
gcloud
Use the
gcloud beta eventarc message-buses update
command to disable CMEK for your bus:
gcloud beta eventarc message-buses update BUS_NAME \ --location=REGION \ --clear-crypto-key
Enable CMEK for a pipeline
When you enable CMEK for an Eventarc Advanced pipeline, all messages that pass through the pipeline are fully encrypted with that CMEK key.
Console
In the Google Cloud console, go to the Eventarc > Pipelines page.
You can create a pipeline or, if you are updating a pipeline, click the name of the pipeline.
In the Pipeline details page, click
Edit.In the Edit pipeline page, for Encryption, select Cloud KMS key.
In the Key type list, select a method to manage your keys.
You can manage your keys manually or you can use Autokey which lets you generate key rings and keys on-demand. If the Autokey option is disabled, it isn't yet integrated with the current resource type.
Select a customer-managed key.
Optional: To manually enter the resource name of the key, in the Select a customer-managed key list, click Enter key manually, and enter the key name in the specified format.
If prompted, grant the
cloudkms.cryptoKeyEncrypterDecrypter
role to the Eventarc Service Agent.Click Save.
gcloud
Use the
gcloud beta eventarc pipelines update
command to enable CMEK for a pipeline:
gcloud beta eventarc pipelines update PIPELINE_NAME \ --location=REGION \ --crypto-key=KEY
Replace the following:
PIPELINE_NAME
: the ID or fully qualified identifier of your pipelineREGION
: a supported Eventarc Advanced locationKEY
: the fully qualified Cloud KMS key name in the formatprojects/PROJECT_NAME/locations/REGION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
The
REGION
of the key must match the location of the pipeline to be protected.
Verify Cloud KMS usage
Verify that the pipeline is now CMEK-compliant.
Console
In the Google Cloud console, go to the Eventarc > Pipelines page.
Click the name of the pipeline that you have protected using CMEK.
On the Pipeline details page, the Encryption status displays the message,
Event messages encrypted using customer-managed encryption keys
.
gcloud
Use the
gcloud beta eventarc pipelines describe
command to verify CMEK for your pipeline:
gcloud beta eventarc pipelines describe PIPELINE_NAME \ --location=REGION
The output should be similar to the following:
createTime: '2022-06-28T18:05:52.403999904Z' cryptoKeyName: projects/PROJECT_ID/locations/REGION/keyRings/RING_NAME/cryptoKeys/KEY_NAME destinations: ... name: projects/PROJECT_ID/locations/REGION/pipelines/PIPELINE_NAME uid: 5ea277f9-b4b7-4e7f-a8e0-6ca9d7204fa3 updateTime: '2022-06-28T18:09:18.650727516Z'
The cryptokeyName
value shows the Cloud KMS key used for the
pipeline.
Disable CMEK for a pipeline
You can disable the CMEK protection associated with a pipeline. The events that are delivered through the pipeline are still protected by Google-owned and Google-managed keys.
Console
In the Google Cloud console, go to the Eventarc > Pipelines page.
Click the name of the pipeline.
In the Pipeline details page, click
Edit.On the Edit pipeline page, clear the Use a customer-managed encryption key (CMEK) checkbox.
Click Save.
gcloud
Use the
gcloud beta eventarc pipelines update
command to disable CMEK for your pipeline:
gcloud beta eventarc pipelines update PIPELINE_NAME \ --location=REGION \ --clear-crypto-key
Enable CMEK for Google API sources
When you enable CMEK for a GoogleApiSource
resource, all messages that are
collected for that resource are fully encrypted with the CMEK key.
Console
In the Google Cloud console, go to the Eventarc > Bus page.
You can create a bus or, if you are updating a bus, click the name of the bus.
In the Bus details page, click
Edit.To add a message source, click
Add source.If a message source already exists, you must first delete it and then add a new message source.
In the Add message source pane, for the Google API message provider, accept the default of
google-api-source
.For Encryption, select Cloud KMS key and do the following:
In the Key type list, select a method to manage your keys.
You can manage your keys manually or you can use Autokey which lets you generate key rings and keys on-demand. If the Autokey option is disabled, it isn't yet integrated with the current resource type.
In the Select a customer-managed key, select a key.
You must select a region before you can view your customer-managed keys.
Optional: To manually enter the resource name of the key, in the Select a customer-managed key list, click Enter key manually, and enter the key name in the specified format.
If prompted, grant the
cloudkms.cryptoKeyEncrypterDecrypter
role to the Eventarc Service Agent.
Click Create.
This enables the automatic collection of events coming directly from Google sources, and all event messages are fully encrypted with the CMEK key.
Only events from resources in the same Google Cloud project as the
GoogleApiSource
are published. For more information, see Publish events from Google sources.Click Save.
gcloud
Use the
gcloud beta eventarc google-api-sources update
command to enable CMEK for your GoogleApiSource
resource:
gcloud beta eventarc google-api-sources update GOOGLE_API_SOURCE_NAME \ --location=REGION \ --crypto-key=KEY
Replace the following:
GOOGLE_API_SOURCE_NAME
: the ID or fully qualified identifier of yourGoogleApiSource
resourceREGION
: a supported Eventarc Advanced locationKEY
: the fully qualified Cloud KMS key name in the formatprojects/PROJECT_NAME/locations/REGION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
The
REGION
of the key must match the location of the resource to be protected.
Verify Cloud KMS usage
Verify that the resource is now CMEK-compliant.
Console
In the Google Cloud console, go to the Eventarc > Bus page.
Click the name of the bus whose message source you have protected using a Cloud KMS key.
In the Bus details page, click
Edit.The key that is encrypting your message source should be listed.
gcloud
Use the
gcloud beta eventarc google-api-sources describe
command to verify CMEK for your GoogleApiSource
resource:
gcloud beta eventarc google-api-sources describe GOOGLE_API_SOURCE_NAME \ --location=REGION
The output should be similar to the following:
createTime: '2022-06-28T18:05:52.403999904Z' cryptoKeyName: projects/PROJECT_ID/locations/REGION/keyRings/RING_NAME/cryptoKeys/KEY_NAME destination: projects/PROJECT_ID/locations/REGION/messageBuses/BUS_NAME name: projects/PROJECT_ID/locations/REGION/googleApiSources/GOOGLE_API_SOURCE_NAME uid: 5ea277f9-b4b7-4e7f-a8e0-6ca9d7204fa3 updateTime: '2022-06-28T18:09:18.650727516Z'
The cryptokeyName
value shows the Cloud KMS key used for the
pipeline.
Disable CMEK for Google API sources
You can disable the CMEK protection associated with Google API sources. The
events that are collected through the GoogleApiSource
resource are still
protected by Google-owned and Google-managed keys.
Console
In the Google Cloud console, go to the Eventarc > Bus page.
Click the name of the bus whose message source you have protected using CMEK.
In the Bus details page, click
Edit.To delete the message source that is encrypted by a Cloud KMS key, click
Delete resource.If necessary, re-add the message source.
gcloud
Use the
gcloud beta eventarc google-api-sources update
command to disable CMEK for your GoogleApiSource
resource:
gcloud beta eventarc google-api-sources update GOOGLE_API_SOURCE_NAME \ --location=REGION \ --clear-crypto-key
Disabling and enabling Cloud KMS keys
A key version stores the cryptographic key material that you use to encrypt, decrypt, sign, and verify data. You can disable this key version so that data that was encrypted with the key can't be accessed.
When Eventarc cannot access Cloud KMS keys,
event routing fails with FAILED_PRECONDITION
errors and event
delivery stops. You can enable a key in the Disabled state so that the
encrypted data can be accessed again.
Disable Cloud KMS keys
To prevent Eventarc from using the key to encrypt or decrypt your event data, do any of the following:
- We recommend disabling the key version you have configured for the bus or pipeline. This affects only the Eventarc Advanced bus or pipeline that is associated with the specific key.
- Optional: Revoke the
cloudkms.cryptoKeyEncrypterDecrypter
role from the Eventarc service account. This affects all the project's Eventarc resources that support events encrypted using CMEK.
Although neither operation guarantees instantaneous access revocation, Identity and Access Management (IAM) changes generally propagate faster. For more information, see Cloud KMS resource consistency and Access change propagation.
Re-enable Cloud KMS keys
To resume event delivery and routing, restore access to Cloud KMS.
Audit logging and troubleshooting
Cloud KMS produces audit logs when keys are enabled, disabled, or used by Eventarc Advanced resources to encrypt and decrypt messages. For more information, see the Cloud KMS audit logging information.
To resolve issues that you might encounter when using externally managed keys through Cloud External Key Manager (Cloud EKM), see Cloud EKM error reference.
Pricing
The bus integration does not incur additional costs beyond the key operations, which are billed to your Google Cloud project. The use of CMEK for a pipeline incurs charges for access to the Cloud KMS service based on Pub/Sub pricing.
For more information on the most current pricing information, see Cloud KMS Pricing.