Prerequisites
To enable CMEK for a cluster, you need a CockroachDB Advanced with enabled. Advanced security features can be enabled only during cluster creation. Complete the steps in this guide before inserting data into the cluster. This guide will walk you through creating the necessary cloud identities and encryption keys:- An IAM role in your AWS account, a cross-tenant service account in your GCP project, or admin consent for CockroachDB Cloud to access your Azure Key Vault. CockroachDB Cloud will use this identity to encrypt and decrypt using the CMEK.
- A CMEK key for your cluster stored in AWS KMS, GCP KMS, or Azure Key Vault. CockroachDB Cloud never has access to the CMEK itself. You can use an existing key or create a new one following the instructions in this guide.
Enable CMEK
This section shows how to enable CMEK on a CockroachDB Advanced cluster. Select your cluster’s cloud provider to continue.AWS
AWS
Before you begin
- Make a note of your Cloud organization ID in the Organization settings page.
-
Find your CockroachDB Advanced cluster’s ID. From the CockroachDB Cloud console Clusters list, click the name of a cluster to open its Cluster Overview page. From the page’s URL make a note of the last 12 digits of the portion of the URL before
/overview/. This is the cluster ID. -
Use the cluster ID to find the cluster’s associated cross-account IAM role, which is managed by CockroachDB Cloud.
In the response, verify that the
idfield matches the cluster ID you specified, then make a note of theaccount_id, which is the ID for the cross-account IAM role.
Step 1. Provision the cross-account IAM role
Follow these steps to create a cross-account IAM role and give it permission to access the CMEK in AWS KMS. CockroachDB Cloud will assume this role to encrypt and decrypt using the CMEK.-
Use the CockroachDB Cloud API to find the ID of the AWS account managed by CockroachDB Cloud that is associated with your cluster (not your own AWS account):
In the response, the ID is stored in the
account_idfield. -
In the AWS console, visit the IAM page and select Roles and click Create role.
- For Trusted entity type, select AWS account.
- Select Another AWS account and set Account ID, provide the AWS account ID that you found in Before you begin.
- Select Require external ID and set External ID to your CockroachDB Cloud organization ID, which you found in Before you begin.
- Provide a name for the role. Do not enable any permissions.
- Make a note of the Amazon Resource Name (ARN) for the new IAM role.
Step 2. Create the CMEK key
If you intend to use an existing key as the CMEK, skip this step.You can create the CMEK directly in the AWS Console or using .- AWS Console
- Hashicorp Vault
- In the AWS console, visit AWS KMS.
-
To create the key, select Customer managed keys and click Create Key.
- Set Key type to Symmetric Key.
- Set Key usage to Encrypt and decrypt.
- Under Advanced options, set Key material to KMS, then choose whether to create a single-region or multi-region key. For optimal performance, we recommend serving the key in each of your cluster’s regions.
- Set Alias to a name for the key.
-
Configure the permissions for your key using the following IAM policy:
- Finish creating the key.
Step 3. Build your CMEK configuration manifest
Compile the information about the service account and key we’ve just created into a manifest, which you will use to activate CMEK on your cluster with the CockroachDB Cloud API.-
Create a new file named
cmek_config.jsonwith the following contents. This file will contain a JSON array ofregion_specobjects, each of which includes the name of a CockroachDB Cloud region and akey_specthat specifies the URI of the CMEK key and the principal that is authorized to encrypt and decrypt using the key. Replace the placeholder values, being careful to include oneregion_specobject per cluster region. When enabling CMEK, you must include aregion_specfor each region in the cluster. - Use the shell utility JQ to inspect JSON payload:
On a Mac, install JQ with
brew install jqStep 4. Activate CMEK
Using the CockroachDB Cloud API, send aPOST request with the contents of cmek_config.json to the cluster’s cmek endpoint.GCP
GCP
Before you begin
- Make a note of your Cloud organization ID in the Organization settings page.
-
Find your CockroachDB Advanced cluster’s ID. From the CockroachDB Cloud console Clusters list, click the name of a cluster to open its Cluster Overview page. From the page’s URL make a note of the last 12 digits of the portion of the URL before
/overview/. This is the cluster ID. -
Use the cluster ID to find the cluster’s associated GCP Project ID, which is managed by CockroachDB Cloud. Query the
clusters/endpoint of the CockroachDB Cloud API:In the response, verify that theidfield matches the cluster ID you specified, then make a note of the following:-
account_id: the GCP project ID. -
regions/name: one entry for each of the cluster’s regions. CMEK must be configured in each of a cluster’s regions.
-
-
Formulate the service account’s email address, which is in the following format. Replace with the cluster ID, and replace with the GCP project ID.
Step 1. Provision the cross-tenant service account
- In the GCP Console, visit the IAM service accounts page for your project and click + Create service account. Select Cross-tenant.
- Click the new service account to open its details.
- In PERMISSIONS, click GRANT ACCESS.
- For New principals, enter the service account ID for your cluster, which you found in Before you begin,
- For Role, enter Service Account Token Creator. Click SAVE.
- Make a note of the email address for the new service account.
Step 2. Create the CMEK key
If you intend to use an existing key as the CMEK, skip this step.You can create the CMEK directly in the GCP Console or using .- GCP Console
- Hashicorp Vault
- In the GCP console, visit the KMS page.
- Click + CREATE KEY RING and fill in the details to complete the key ring.
- In the next screen, configure your encryption key as desired. Set the following:
- Type: Generated key.
- Protection level: Software
- Purpose: Symmetric encrypt/decrypt Click Create.
Step 3. Build your CMEK configuration manifest
Compile the information about the service account and key we’ve just created into a manifest, which you will use to activate CMEK on your cluster with the CockroachDB Cloud API.-
Set the required information as environment variables:
-
Then copy paste the following heredoc command to generate the YAML file, populating the values from your shell environment. (Alternatively, you can manually create the YAML file).
-
Use Ruby or another tool to compile human-editable YAML into API-parsable JSON:
-
Use the shell utility JQ to inspect JSON payload:
On a Mac, install JQ with
brew install jqAfter you have built your CMEK configuration manifest with the details of your cluster and provisioned the necessary cloud identity and encryption key, proceed to Step 4.
Step 4. Activate CMEK
Using the CockroachDB Cloud API, send aPOST request with the contents of cmek_config.json to the cluster’s cmek endpoint.Azure
Azure
Before you begin
- Find your CockroachDB Advanced cluster’s ID. From the CockroachDB Cloud console Clusters list, click the name of a cluster to open its Cluster Overview page. From the page’s URL make a note of the part of the URL between
cluster/and/overview. This is the cluster ID. - Make a note of your Azure tenant ID. You can find this in the Azure portal under Azure Active Directory > Overview > Tenant information.
Step 1. Set up Azure identity and permissions
-
Use the CockroachDB Cloud API to get your cluster’s identity ID:
-
In the response, find the
azure_cluster_identity_client_idfield and store its value for a future step. -
Navigate to the following URL in your browser, replacing the placeholders with your values:
- Sign in with your Azure administrator credentials.
- Review the requested permissions (“Sign in and read user profile”) and click Accept.
Step 2. Create the CMEK key
If you intend to use an existing key as the CMEK, skip this step.For these instructions, you can use an existing Azure Key Vault, or create a new key vault using the Azure portal or CLI.- In the Azure portal, navigate to your Key Vault.
- On the Key Vault left-hand sidebar, select Objects then select Keys.
- Select + Generate/Import.
- Enter a Name for the key, and click Create.
- Click the key name, and under Current Version, click the key.
-
In the Key Identifier field, click the copy button. The URL will use the following format. Store it for a future step.
- Navigate to your Key Vault > Access control (IAM) > Add role assignment.
- Select the Key Vault Crypto Officer role, and select the option to assign access to User, group, or service principal.
-
Click Select members, then search for the enterprise application created above:
CockroachDB Cloud - <CLUSTER_ID>.
Step 3. Build your CMEK configuration manifest
Compile the information about the service account and key we’ve just created into a manifest, which you will use to activate CMEK on your cluster with the CockroachDB Cloud API.-
Create a new file named
cmek_config.jsonwith the following contents. Replace the placeholder values, being careful to include oneregion_specobject per cluster region. When enabling CMEK, you must include aregion_specfor each region in the cluster.Replace the placeholder values:- : Your cluster’s region (e.g., “centralindia”)
- : The Key Identifier URL you copied in Step 2
- : Your Azure tenant ID
-
Use the shell utility JQ to inspect JSON payload:
On a Mac, install JQ with
brew install jqAfter you have built your CMEK configuration manifest with the details of your cluster and provisioned the necessary cloud identity and encryption key, proceed to Step 4.
Step 4. Activate CMEK
Using the CockroachDB Cloud API, send aPOST request with the contents of cmek_config.json to the cluster’s cmek endpoint.Check CMEK status
To view your cluster’s CMEK status, send aGET request:
Rotate a CMEK key
You can rotate a CMEK key for a CockroachDB Advanced cluster either by creating a new version of the existing CMEK key or by creating a new CMEK key. At a high level: To begin using a new version of an existing CMEK key:- In your KMS platform, either configure automatic rotation for the CMEK key or perform a manual rotation.
- CockroachDB Cloud does not automatically re-encrypt the store key using the new CMEK key version. For each region you want to update, perform a rotation without modifying the CMEK key URI. CockroachDB Cloud re-encrypts the store key using the new CMEK key version.
- Within your KMS platform, create a new CMEK key.
- Next, perform a rotation in CockroachDB Cloud and provide the new CMEK key URI.
-
Edit or recreate the cluster’s
cmek_config.jsonto update theregion_specobjects, each of which includes the name of a CockroachDB Cloud region and akey_specthat specifies the URI of the CMEK key and the principal that is authorized to encrypt and decrypt using the key. -
Using the CockroachDB Cloud API, send a
PUTrequest with the contents ofcmek_config.jsonto the cluster’scmekendpoint:
Add a region to a CMEK-enabled cluster
To add a region to a cluster that already has CMEK enabled:-
Edit or recreate the cluster’s
cmek_config.jsonto update theregion_specobjects, each of which includes the name of a CockroachDB Cloud region and akey_specthat specifies the URI of the CMEK key and the principal that is authorized to encrypt and decrypt using the key. -
Send the payload as a
PATCHrequest to the cluster endpoint:
Revoke CMEK for a cluster
When you revoke access to the CMEK in your KMS, CockroachDB Cloud can no longer encrypt or decrypt your cluster’s data. All access to the cluster’s data will be prevented until you you restore access. In general, revoke access to the CMEK only when you are permanently decommissioning the cluster or to mitigate a critical security breach or at the request of Cockroach Labs support. Within your KMS platform, you can revoke access to the CMEK temporarily or permanently. Within your KMS, do not revoke access to a CMEK that is in use by one or more clusters. The CMEK is an external resource and is never stored in CockroachDB Cloud.- In your cloud provider’s KMS platform, revoke CockroachDB Cloud’s access to your CMEK key at the IAM level, either by removing the authorization the cross-account IAM role or by removing the cross-account IAM role’s permission to access the key.
-
Your cluster will continue to operate with the CMEK until you update it to revoke CMEK. To revoke access:
- Check your CMEK status to confirm the revocation has taken effect.
- Once you have resolved the security incident, re-authorize CMEK for your cluster to return to normal operations. Contact your account team, or create a support ticket.

