From cd1ba5671e0b75427fabb1a61e64f41a60bb6af7 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Tue, 29 Jul 2025 23:33:21 -0400 Subject: [PATCH 1/4] Add Azure CMEK support and improve documentation structure --- src/current/cockroachcloud/managing-cmek.md | 108 ++++++++++++++++++-- 1 file changed, 101 insertions(+), 7 deletions(-) diff --git a/src/current/cockroachcloud/managing-cmek.md b/src/current/cockroachcloud/managing-cmek.md index bda1a00ffbc..71f0c81fb54 100644 --- a/src/current/cockroachcloud/managing-cmek.md +++ b/src/current/cockroachcloud/managing-cmek.md @@ -7,16 +7,19 @@ docs_area: manage.security [Customer-Managed Encryption Keys (CMEK)]({% link cockroachcloud/cmek.md %}) for CockroachDB {{ site.data.products.cloud }} advanced allows the customer to delegate responsibility for the work of encrypting their cluster data to CockroachDB {{ site.data.products.cloud }}, while maintaining the ability to completely revoke CockroachDB {{ site.data.products.cloud }}'s access. -This page shows how to enable [Customer-Managed Encryption Keys (CMEK)]({% link cockroachcloud/cmek.md %}) for CockroachDB {{ site.data.products.advanced }} advanced. +This page shows how to enable [Customer-Managed Encryption Keys (CMEK)]({% link cockroachcloud/cmek.md %}) for CockroachDB {{ site.data.products.advanced }}. -## Before you begin +## Prerequisites To enable CMEK for a cluster, you need: -- An IAM role in your AWS account or a cross-tenant service account in your GCP project. CockroachDB Cloud will use this identity to encrypt and decrypt using the CMEK. This page shows how to provision a new identity, but you can use an existing identity instead. CMEK is not yet available for [CockroachDB {{ site.data.products.advanced }} on Azure]({% link cockroachcloud/cockroachdb-advanced-on-azure.md %}). -- A CMEK key for your cluster stored in AWS KMS or GCP KMS. CockroachDB Cloud never has access to the CMEK itself. This page shows how to provision a new CMEK directly in your KMS or using Hashicorp Vault, but you can use an existing key instead. -- A new CockroachDB {{ site.data.products.advanced }} [private cluster]({% link cockroachcloud/private-clusters.md %}) with [advanced security features]({% link cockroachcloud/create-an-advanced-cluster.md %}#step-6-configure-advanced-security-features) enabled. A private cluster's nodes communicate only over private Cloud infrastructure, avoiding public networks.

Advanced security features can be enabled only during cluster creation. If necessary, create a new CockroachDB {{ site.data.products.advanced }} private cluster and enable advanced security features. Complete the steps in this page before inserting data into the cluster. -- A [ CockroachDB {{ site.data.products.cloud }} service account]({% link cockroachcloud/managing-access.md %}#manage-service-accounts) and a [CockroachDB Cloud API key]({% link cockroachcloud/managing-access.md %}#create-api-keys) for the service account. You will use the service account to authenticate to the CockroachDB Cloud API and configure CMEK on your cluster. +- A CockroachDB {{ site.data.products.advanced }} [private cluster]({% link cockroachcloud/private-clusters.md %}) with [advanced security features]({% link cockroachcloud/create-an-advanced-cluster.md %}#step-6-configure-advanced-security-features) enabled. Advanced security features can be enabled only during cluster creation. Complete the steps in this guide before inserting data into the cluster. +- A [CockroachDB {{ site.data.products.cloud }} service account]({% link cockroachcloud/managing-access.md %}#manage-service-accounts) and a [CockroachDB Cloud API key]({% link cockroachcloud/managing-access.md %}#create-api-keys) for the service account to authenticate to the CockroachDB Cloud API. + +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 @@ -25,6 +28,7 @@ This section shows how to enable CMEK on a CockroachDB {{ site.data.products.adv
+
### Before you begin @@ -106,6 +110,14 @@ This section shows how to enable CMEK on a CockroachDB {{ site.data.products.adv ~~~ +
+ +1. Make a note of your {{ site.data.products.cloud }} organization ID in the [Organization settings page](https://cockroachlabs.cloud/settings). +1. Find your {{ site.data.products.advanced }} cluster's ID. From the CockroachDB {{ site.data.products.cloud }} console [Clusters list](https://cockroachlabs.cloud/clusters), 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. +1. 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. Provision the cross-account IAM role @@ -148,6 +160,44 @@ Follow these steps to create a cross-account IAM role and give it permission to
+
+ +### Step 1. Set up Azure identity and permissions + +1. Use the CockroachDB Cloud API to get your cluster's identity ID: + + {% include_cached copy-clipboard.html %} + ~~~shell + CLUSTER_ID= #{ your cluster ID } + API_KEY= #{ your API key } + curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID} \ + --header "Authorization: Bearer ${API_KEY}" + ~~~ + +1. In the response, find the `azure_cluster_identity_client_id` field and store its value for a future step. + +1. Navigate to the following URL in your browser, replacing the placeholders with your values: + + ~~~text + https://login.microsoftonline.com/{YOUR_TENANT_ID}/adminconsent?client_id={CLUSTER_IDENTITY_ID} + ~~~ + +1. Sign in with your Azure administrator credentials. +1. Review the requested permissions ("Sign in and read user profile") and click **Accept**. + +This creates an enterprise application in your Azure tenant that CockroachDB Cloud can use to access your Key Vault. It is named using the following format: + +~~~ +ClusterIdentity- +~~~ + +1. In the Azure portal, navigate to your Key Vault > **Access control (IAM)** > **Add role assignment**. +1. Select the **Key Vault Crypto Officer** role, and select the option to assign access to **User, group, or service principal**. +1. Click **Select members**, then search for the enterprise application created above: `ClusterIdentity-` + +
+ ### Step 2. Create the CMEK key If you intend to use an existing key as the CMEK, skip this step. @@ -332,6 +382,23 @@ Make a note of the key ring name. Click **SAVE**. Make a note of the key ring name. + + +
+ +For these instructions, you can use an existing Azure Key Vault, or create a new key vault using the [Azure portal](https://learn.microsoft.com/en-us/azure/key-vault/general/quick-create-portal) or [CLI](https://learn.microsoft.com/en-us/azure/key-vault/general/quick-create-cli). + +1. In the Azure portal, navigate to your Key Vault. +1. On the Key Vault left-hand sidebar, select **Objects** then select **Keys**. +1. **Select + Generate/Import**. +1. Enter a **Name** for the key, and click **Create**. +1. Click the key name, and under Current Version, click the key. +1. In the **Key Identifier** field, click the copy button. The URL will use the following format. Store it for a future step. + + ~~~text + https://.vault.azure.net/keys// + ~~~ +
@@ -408,6 +475,33 @@ Compile the information about the service account and key we've just created int +
+ +1. Create a new file named `cmek_config.json` with the following contents. Replace the placeholder values, being careful to include one `region_spec` object per cluster region. When enabling CMEK, you must include a `region_spec` for each region in the cluster. + + {% include_cached copy-clipboard.html %} + ~~~ json + { + "region_specs": [ + { + "region": "{COCKROACHDB_CLOUD_REGION}", + "key_spec": { + "type": "AZURE_KEY_VAULT", + "uri": "{YOUR_KEY_IDENTIFIER_URL}", + "auth_principal": "{YOUR_TENANT_ID}" + } + } + ] + } + ~~~ + + Replace the placeholder values: + - `{COCKROACHDB_CLOUD_REGION}`: Your cluster's region (e.g., "centralindia") + - `{YOUR_KEY_IDENTIFIER_URL}`: The Key Identifier URL you copied in Step 2 + - `{YOUR_TENANT_ID}`: Your Azure tenant ID + +
+ 1. Use the shell utility JQ to inspect JSON payload: {{site.data.alerts.callout_info}} @@ -419,7 +513,7 @@ Compile the information about the service account and key we've just created int cat cmek_config.json | jq ~~~ -After you have built your CMEK configuration manifest with the details of your cluster and provisioned the service account and KMS key in GCP, return to [Enabling CMEK for a CockroachDB {{ site.data.products.advanced }} cluster]({% link cockroachcloud/managing-cmek.md %}#step-4-activate-cmek). +After 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 From a7ddc46a59c16552a9ae8ec0ea7dc0b2ba958a57 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Tue, 29 Jul 2025 23:50:37 -0400 Subject: [PATCH 2/4] Update main CMEK page --- src/current/cockroachcloud/cmek.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/current/cockroachcloud/cmek.md b/src/current/cockroachcloud/cmek.md index 32991cb630d..d96118be03a 100644 --- a/src/current/cockroachcloud/cmek.md +++ b/src/current/cockroachcloud/cmek.md @@ -12,10 +12,11 @@ You can manage your CMEK keys using one or more of the following services: - Amazon Web Services (AWS) KMS - Google Cloud Platform (GCP) KMS +- Microsoft Azure Key Vault To learn more, visit [Managing Customer-Managed Encryption Keys (CMEK) for CockroachDB {{ site.data.products.advanced }}]({% link cockroachcloud/managing-cmek.md %}). -CockroachDB {{ site.data.products.advanced }} includes support for referring to CMEK keys in [HashiCorp Vault Secrets Manager](https://www.vaultproject.io/docs/secrets/key-management), which can distribute keys stored in multiple KMS systems, as long as the actual keys are stored in AWS KMS or GCP KMS. +CockroachDB {{ site.data.products.advanced }} includes support for referring to CMEK keys in [HashiCorp Vault Secrets Manager](https://www.vaultproject.io/docs/secrets/key-management), which can distribute keys stored in multiple KMS systems, as long as the actual keys are stored in AWS KMS, GCP KMS, or Azure Key Vault. {{site.data.alerts.callout_success}} You can learn more about the [supported integrations between CockroachDB and HashiCorp Vault]({% link {{site.current_cloud_version}}/hashicorp-integration.md %}). @@ -40,7 +41,7 @@ This section describes some of the ways that CMEK can help you protect your data You can use your KMS platform's controls to configure the regions where the CMEK key is available, enable automatic rotation schedules for CMEK keys, and view audit logs that show each time the CMEK key is used by CockroachDB {{ site.data.products.cloud }}. CockroachDB {{ site.data.products.cloud }} does not need any visibility into these details. - **Separation of concerns**: With CMEK, you give CockroachDB {{ site.data.products.cloud }} permission to encrypt and decrypt using the CMEK, but Cockroach Labs has no access to the CMEK's key material. The ability to create keys and manage IAM access to them can be delegated to a limited group of trusted individuals, who may be distinct from the organization's cluster admins. -- **Infrastructure flexibility**: If your CMEK keys are stored in multiple KMS systems or tenants, you can use HashiCorp Vault Key Management Secrets Engine to give your cluster access to your CMEK keys, as long as the cluster and keys are stored in the same deployment environment (GCP or AWS). +- **Infrastructure flexibility**: If your CMEK keys are stored in multiple KMS systems or tenants, you can use HashiCorp Vault Key Management Secrets Engine to give your cluster access to your CMEK keys, as long as the cluster and keys are stored in the same deployment environment (AWS, GCP, or Azure). The following example shows some of the ways that CMEK can help you meet business and regulatory requirements. @@ -166,7 +167,6 @@ Not yet. To restore a failed CMEK-enabled cluster, please create a support ticke CMEK has the following limitations: -- CMEK is not yet available for [CockroachDB {{ site.data.products.advanced }} on Azure]({% link cockroachcloud/cockroachdb-advanced-on-azure.md %}). To express interest, contact your Cockroach Labs account team. - To enable or revoke a CMEK on a cluster, you must use the [Cloud API]({% link cockroachcloud/cloud-api.md %}) or the [CockroachDB Terraform provider](https://registry.terraform.io/providers/cockroachdb/cockroach/latest). It's not possible to enable a CMEK using the CockroachDB {{ site.data.products.cloud }} Console. - If you add a new region to a cluster with CMEK enabled, you must configure a CMEK for the new region to protect its data. - If the CMEK is not available due to a misconfiguration or a KMS outage, a cluster's managed backups will begin to fail, but no customer notification is sent from CockroachDB {{ site.data.products.cloud }} via email. However, Cockroach Labs support is notified if such a failure occurs. From 9869816aa88d931964cccc874922797479f7dd9c Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Tue, 29 Jul 2025 23:55:40 -0400 Subject: [PATCH 3/4] Remove temporary limitation about CMEK on Azure --- src/current/cockroachcloud/cockroachdb-advanced-on-azure.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/current/cockroachcloud/cockroachdb-advanced-on-azure.md b/src/current/cockroachcloud/cockroachdb-advanced-on-azure.md index d3b8a2246c6..ed0f1783f82 100644 --- a/src/current/cockroachcloud/cockroachdb-advanced-on-azure.md +++ b/src/current/cockroachcloud/cockroachdb-advanced-on-azure.md @@ -14,7 +14,6 @@ CockroachDB {{ site.data.products.advanced }} clusters on Azure have the followi - A cluster must have at minimum three nodes. A multi-region cluster must have at minimum three nodes per region. Single-node clusters are not supported on Azure. - The following [PCI-Ready]({% link cockroachcloud/pci-dss.md %}) and HIPAA features are not yet available on Azure. However, CockroachDB {{ site.data.products.advanced }} on Azure meets or exceeds the requirements of SOC 2 Type 2. Refer to [Regulatory Compliance in CockroachDB {{ site.data.products.advanced }}]({% link cockroachcloud/compliance.md %}). - - [Customer Managed Encryption Keys (CMEK)]({% link cockroachcloud/cmek.md %}) - [Egress Perimeter Controls]({% link cockroachcloud/egress-perimeter-controls.md %}) You can configure IP allowlisting to limit the IP addresses or CIDR ranges that can access a CockroachDB {{ site.data.products.dedicated }} cluster on Azure, and you can use [Azure Private Link](https://learn.microsoft.com/azure/private-link/private-link-overview) to connect your applications in Azure to your cluster and avoid exposing your cluster or applications to the public internet. Refer to [Connect to your cluster]({% link cockroachcloud/connect-to-your-cluster.md %}#azure-private-link). From 7494629a5f1033a5cfdc50683902dacd7222c725 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Wed, 30 Jul 2025 00:01:05 -0400 Subject: [PATCH 4/4] Add release note --- src/current/releases/cloud.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/current/releases/cloud.md b/src/current/releases/cloud.md index 11843a2ec89..3a3f6a1052d 100644 --- a/src/current/releases/cloud.md +++ b/src/current/releases/cloud.md @@ -14,6 +14,25 @@ Get future release notes emailed to you: {% include marketo.html formId=1083 %} +## July 31, 2025 + +### Customer-Managed Encryption Keys (CMEK) for CockroachDB Advanced for Azure + +This release introduces Customer-Managed Encryption Keys (CMEK) for CockroachDB Cloud Advanced clusters on Microsoft Azure. This feature provides enhanced data security and supports PCI DSS compliance. + +CMEK enables customers to control the encryption keys used to protect their data at rest within CockroachDB Cloud on Azure. Keys are managed via the customer's Azure Key Vault. + +Key benefits: + +- **Enhanced Data Security**: Customers control key lifecycle (creation, rotation, revocation), improving data protection. +- **PCI DSS Compliance**: Addresses PCI DSS Requirement 3 for protecting stored cardholder data. +- **Operational Control**: Provides greater control and visibility over data encryption strategy. +- **Data Revocation Capability**: Enables immediate data access revocation by disabling the encryption key in Azure Key Vault. + +This functionality is critical for organizations handling sensitive data and seeking PCI DSS compliance on the Azure Advanced Tier of CockroachDB Cloud. + +For more information, refer to [Customer-Managed Encryption Keys (CMEK) Overview]({% link cockroachcloud/cmek.md %}) and [Manage CMEK for CockroachDB Advanced]({% link cockroachcloud/managing-cmek.md %}). + ## May 12, 2025 CockroachDB v25.2 is now generally available (GA) for CockroachDB Cloud {{ site.data.products.advanced }} clusters. CockroachDB v25.2 is a [Regular release]({% link releases/index.md %}#release-types).