Use customer-managed encryption keys

By default, Workflows encrypts your data stored at rest. Google Cloud handles and manages this default encryption for you without any additional actions on your part.

If you have specific compliance or regulatory requirements related to the keys that protect your data, you can use customer-managed encryption keys (CMEK) for Workflows. Your workflow and associated data at rest are protected using an encryption key that only you can access, and that you can control and manage using Cloud Key Management Service (Cloud KMS).

What is protected with CMEK

When deploying a workflow, you can specify a Cloud KMS key. This key is used to encrypt the workflow and its executions:

A workflow requires a source file that contains a valid workflow definition. This source file is encrypted using the key.
A workflow execution runs the current workflow definition (a specific workflow revision). Using the key associated with the workflow revision at the time of its deployment, the compiled workflow, as well as any stored execution input, output, and runtime data is encrypted. This includes execution arguments, results, errors, and exceptions; delivered Eventarc events; and callback and HTTP requests and responses.

Before you begin

Before using CMEK in Workflows, complete the following steps:

Enable the APIs.
Console
1. Enable the Cloud KMS and Workflows APIs.
  Enable the APIs
gcloud
1. In the Google Cloud console, activate Cloud Shell.
  
  Activate Cloud Shell
  
  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
2. Update gcloud components.
```
gcloud components update
```
3. Enable the Cloud KMS and Workflows APIs for the project that will store your encryption keys.
```
gcloud services enable cloudkms.googleapis.com workflows.googleapis.com
```
Cloud KMS produces Cloud Audit Logs when keys are enabled, disabled, or used by Workflows resources to encrypt and decrypt data. Make sure that logging is enabled for the Cloud KMS API in your project, and that you have decided which logging-specific permissions and roles apply to your use case. For more information, see Cloud KMS audit logging information.

Create a Cloud KMS key ring and key

You can create a new key ring or use an existing one. Within the key ring, you can add a new key or use an existing key.

Retrieve the resource ID for a Cloud KMS key

The resource ID for a Cloud KMS key is required when you enable CMEK for a workflow. In this document, see Enable CMEK for a workflow.

Console

In the Google Cloud console, go to the Key management page.
Go to Key management
Click the key ring that contains the key.
For the key whose resource ID you are retrieving, click More.
Click Copy resource name.

The resource ID for the key is copied to your clipboard. Its format is similar to the following:
```
projects/PROJECT_NAME/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME
```
A key contains zero or more key versions. The resource ID for a key version is the key ID, plus a slash (/), plus the version ID. To list all versions for a key:
1. Click the key's name.
2. For a specific version, click More.
3. Click Copy resource name.

gcloud

List all keys on a given key ring:
```
gcloud kms keys list --keyring RING_NAME --location LOCATION
```
Replace the following:
- RING_NAME: the name of the key ring
- LOCATION: the region of the key ring
The output includes the resource ID for each key. For example:
```
NAME: projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
```
A key has zero or more key versions. The resource ID for a key version is the key ID, plus a slash (/), plus the version ID. List all versions for a key:
```
gcloud kms keys versions list --location LOCATION --keyring RING_NAME --key KEY_NAME
```
The output includes the resource ID for each key version. For example:
```
NAME: projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME/2
```

Grant the Workflows service agent access to the key

You must grant the Workflows service agent the Cloud KMS CryptoKey Encrypter/Decrypter Identity and Access Management (IAM) role so that it can access the Cloud KMS key:

Console

When you enable CMEK for a workflow through the 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 workflow.

gcloud

gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring RING_NAME \
    --location LOCATION \
    --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-workflows.iam.gserviceaccount.com \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter

Replace the following:

KEY_NAME: the name of the key. For example, my-key.
RING_NAME: the name of the key ring. For example, my-keyring.
LOCATION: the location of the key. For example, us-central1.
PROJECT_NUMBER: your Google Cloud project number. You can find your project number on the Welcome page of the Google Cloud console or by running the following command:
```
export PROJECT=$(gcloud info --format='value(config.project)')
gcloud projects describe ${PROJECT} --format="value(projectNumber)"
```

As long as the service agent has the roles/cloudkms.cryptoKeyEncrypterDecrypter role, a workflow in your project can encrypt and decrypt its data using the CMEK key. If you revoke this role, or if you disable or destroy the CMEK key, that data can't be accessed. In this document, see Disable Cloud KMS.

Enable CMEK for a workflow

When creating a workflow or updating it afterwards, you can specify the Cloud KMS key the workflow should use for data encryption.

Console

In the Google Cloud console, go to the Workflows page.
Go to Workflows
Click the name of the workflow you want to update.

The Workflows details page appears.
Click Edit.
Select Customer-managed encryption key (CMEK).
In the Select a customer-managed key list, select or filter for a Cloud KMS 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 resource name in the specified format.
If prompted, grant the cloudkms.cyptoKeyEncrypterDecrypter role to the Workflows service account with the workflows.serviceAgent role.
Click Next.
To save your changes and deploy the updated workflow, click Deploy.

gcloud

gcloud workflows deploy WORKFLOW_NAME \
    --source=SOURCE_FILE \
    --kms-key=KEY \
    --location LOCATION \
    --service-account=SERVICE_ACCOUNT

Replace the following:

WORKFLOW_NAME: the name of your workflow
SOURCE_FILE: your workflow source file with a yaml file extension for a YAML file, or with a json file extension for a JSON file; for example, myWorkflow.yaml.
KEY: the key's resource ID in the format projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME. You can retrieve the key ID.

Important: Even if you omit the --kms-key flag for subsequent deployments of the workflow, any previously deployed Cloud KMS key is applied until the key is disabled. In this document, see Disable CMEK for a workflow.
LOCATION: the location of the workflow
SERVICE_ACCOUNT: the service account your workflow will use to access other Google Cloud services; for example, SERVICE_ACCOUNT_NAME@PROJECT_NAME.iam.gserviceaccount.com. We strongly recommend using a service account with the least privileges necessary to access the required resources. If left blank, the default service account is used. For more information, see Grant a workflow permission to access Google Cloud resources.

Note the following:

Workflow revisions and executions are encrypted with the key specified at the time of deployment; resources previously encrypted with an earlier key remain encrypted with that earlier key. If a workflow is subsequently edited and a new key is specified, that revision of the workflow is encrypted with the new key, and any subsequent executions will use the new key.
Previously non-CMEK encrypted workflow revisions and executions remain not encrypted.
If you disable CMEK for a workflow revision, any subsequent executions are created without CMEK encryption. In this document, see Disable CMEK for a workflow. Existing workflow revisions and executions remain encrypted with the keys with which they were previously encrypted.

Verify the Cloud KMS integration

You can verify the CMEK integration by displaying the metadata for a workflow.

Console

In the Google Cloud console, go to the Workflows page.
Go to Workflows
Click the name of the workflow you want to verify.

The Workflows details page appears.
Click the Details tab.

The Encryption value displays the resource ID of the Cloud KMS key used to secure the workflow and its execution.

gcloud

gcloud workflows describe WORKFLOW_NAME \
    --location=LOCATION

The output should be similar to the following:

createTime: '2022-08-10T19:57:58.233177709Z'
cryptoKeyName: projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
name: projects/PROJECT_NAME/locations/LOCATION/workflows/WORKFLOW_NAME
revisionCreateTime: '2022-11-18T19:44:04.933633237Z'
revisionId: 000009-8be
serviceAccount: projects/PROJECT_NAME/serviceAccounts/SA_NAME@PROJECT_NAME.iam.gserviceaccount.com
sourceContents:
[...]
state: ACTIVE
updateTime: '2022-11-18T19:44:05.171793128Z'

The cryptokeyName value is the resource ID of the Cloud KMS key used to secure the workflow and its execution.

Disable CMEK for a workflow

You can disable CMEK for a workflow so that it no longer uses the associated Cloud KMS key.

Console

In the Google Cloud console, go to the Workflows page.
Go to Workflows
Click the name of the workflow you want to update.

The Workflows details page appears.
Click Edit.
To clear the Customer-managed encryption key (CMEK) radio button, select Google-managed encryption key.
Click Next.
To save your changes and deploy the updated workflow, click Deploy.

gcloud

gcloud workflows deploy WORKFLOW_NAME \
    --source=SOURCE_FILE \
    --clear-kms-key \
    --service-account=SERVICE_ACCOUNT

This disables CMEK for the current workflow revision and any subsequent executions are created without CMEK encryption. Existing workflow revisions and executions remain encrypted with the keys with which they were previously encrypted.

Disable Cloud KMS

If you wish to revoke data access to your workflow or workflow executions, you can do either of the following to disable Cloud KMS:

Disable or destroy the primary key version of your customer-managed encryption key. Disabling a CMEK key version suspends access to all data protected by that key version. Destroying a key version is the permanent counterpart of this action. Both affect only the workflows and workflow executions that are associated with the specific key. You can't create new executions or view the resources associated with the disabled or destroyed key. Any active executions will fail with a corresponding error message.
Revoke the cloudkms.cryptoKeyEncrypterDecrypterIAM role from the Workflows service agent. This affects all workflows in the Google Cloud project that support encryption using CMEK. You can't create new CMEK-integrated workflows and executions, or view any CMEK-encrypted resources. Any active executions will fail with a corresponding error message.

Although neither operation guarantees instantaneous access revocation, IAM changes generally propagate faster. For more information, see Cloud KMS resource consistency and Access change propagation.

Troubleshooting

You might encounter errors when using Cloud KMS with Workflows. The following table describes different issues and how to resolve them.

Issue	Description
Permission `cloudkms.cryptoKeyVersions.useToEncrypt` is denied	Either the provided Cloud KMS key does not exist or the permission is not properly configured. Solution: Check that the Cloud KMS key exists. List the keys for a specified key ring and verify its usage. Ensure that the Workflows service agent has access to the key and has been granted the `cloudkms.cryptoKeyEncrypterDecrypter` role.
Key version is not enabled	The provided Cloud KMS key version has been disabled. Solution: Re-enable the Cloud KMS key version.
Key ring region does not match the resource to be protected	The provided KMS key ring region is different from the region of the workflow. Solution: Use a Cloud KMS key ring and protected workflow from the same region. (Note that they can be in different projects.) For more information, see Cloud KMS locations and Workflows locations.
Cloud KMS quota limit is exceeded	Your quota limit for Cloud KMS requests has been reached. Solution: Limit the number of Cloud KMS calls or increase the quota limit. For more information, see Cloud KMS quotas.

How an unavailable key status is handled

If for some reason Cloud KMS is unavailable, Workflows might be unable to retrieve the status of your key from Cloud KMS.

If the key status is unavailable, the workflow or its execution will return a state: UNAVAILABLE value and related details in the stateError field.

If the key status becomes unavailable in the course of a workflow execution (for example, a permission is revoked during a callback), a runtime error occurs, returning a state: FAILED value, and related details in the error field.

Pricing

This integration does not incur additional costs beyond the key operations, which are billed to your Google Cloud project. For current pricing information, see Cloud KMS pricing.