Add Azure CMEK support and improve documentation structure #20022

mikeCRL · 2025-07-30T03:34:20Z

Summary:

This PR documents the new Customer-Managed Encryption Keys (CMEK) support for CockroachDB Cloud Advanced clusters on Microsoft Azure, enabling customers to use their own encryption keys stored in Azure Key Vault.

To preview the updated pages:

Changes:

managing-cmek.md
- Added Azure filter tab to existing AWS/GCP cloud provider options
- Added full Azure workflow documentation with OAuth consent flow, cluster identity retrieval, and Key Vault setup
- Added Azure configuration manifest with AZURE_KEY_VAULT type and tenant ID authentication
- Renamed "Before you begin" to "Prerequisites" for better clarity
- Restructured prerequisites section to separate actual requirements from items created during setup
- Removed "CMEK not available on Azure" restriction from prerequisites
cmek.md
- Added Azure Key Vault to supported services list alongside AWS KMS and GCP KMS
- Updated HashiCorp Vault compatibility statement to include Azure Key Vault support
- Updated infrastructure flexibility section to include Azure alongside AWS and GCP
- Removed "CMEK not available on Azure" limitation from limitations section
cockroachdb-advanced-on-azure.md - Removed CMEK from list of features "not yet available on Azure"
releases/cloud.md - Added release note announcing Azure CMEK availability

netlify · 2025-07-30T03:34:39Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`04bdb3c`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/6890db72307fa70008b03200

netlify · 2025-07-30T03:34:40Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`04bdb3c`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/6890db72c6a4960009dbe7d0

github-actions · 2025-07-30T03:34:51Z

Files changed:

netlify · 2025-07-30T03:42:25Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`04bdb3c`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/6890db724ad9180008abeebf
😎 Deploy Preview	https://deploy-preview-20022--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

sanchit-CRL · 2025-07-30T05:17:17Z

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 %})


Egress Perimeter control and CMEK both will be supported for Azure post the release to make Azure PCI compliant.

Reworking the broader bullet to mention that both features are in Preview. We can further refine this Azure page in line with the GA release of these features. CC @biplav-crl

src/current/cockroachcloud/managing-cmek.md

sanchit-CRL · 2025-07-30T05:36:26Z

src/current/cockroachcloud/managing-cmek.md

+<section class="filter-content" markdown="1" data-scope="azure">
+
+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.


In case of Azure the cluster id is the entire uuid and not just the last 12 digits.

sanchit-CRL · 2025-07-30T05:40:38Z

src/current/cockroachcloud/managing-cmek.md

+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-<azure_cluster_identity_client_id>


This has been renamed to CockroachDB Cloud - <CLUSTER_ID> also azure_cluster_identity_client_id is not the place holder here, rather the cluster id is the place holder

sanchit-CRL · 2025-07-30T05:41:06Z

src/current/cockroachcloud/managing-cmek.md

+
+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-<azure_cluster_identity_client_id>`


Suggested change

1. Click **Select members**, then search for the enterprise application created above: `ClusterIdentity-<azure_cluster_identity_client_id>`

1. Click **Select members**, then search for the enterprise application created above: `CockroachDB Cloud - <CLUSTER_ID>`

sanchit-CRL · 2025-07-30T08:10:18Z

src/current/cockroachcloud/managing-cmek.md

@@ -332,6 +382,23 @@ Make a note of the key ring name.

    Click **SAVE**. Make a note of the key ring name.

+</section>
+
+<section class="filter-content" markdown="1" data-scope="azure">


This section doesn't appear in the Step 2. Create the CMEK key in the Azure tab, in the documentation link specified in the PR

Also I feel the IAM permission In the Azure portal, navigate to your Key Vault > Access control (IAM) > Add role assignment. must be given post the key creation step.

Fixed both. (Edited your comment accidentally, then reverted it.)

mikeCRL

@sanchit-CRL Thanks for the thorough review. I believe everything is resolved in my latest commit. Please take a look.

mikeCRL · 2025-08-04T01:52:05Z

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 %})


Reworking the broader bullet to mention that both features are in Preview. We can further refine this Azure page in line with the GA release of these features. CC @biplav-crl

src/current/cockroachcloud/managing-cmek.md

mikeCRL · 2025-08-04T03:08:06Z

src/current/cockroachcloud/managing-cmek.md

+<section class="filter-content" markdown="1" data-scope="azure">
+
+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.


mikeCRL · 2025-08-04T03:09:22Z

src/current/cockroachcloud/managing-cmek.md

+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-<azure_cluster_identity_client_id>


mikeCRL · 2025-08-04T03:09:33Z

src/current/cockroachcloud/managing-cmek.md

+
+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-<azure_cluster_identity_client_id>`


sanchit-CRL

LGTM, thanks for the changes

src/current/cockroachcloud/cockroachdb-advanced-on-azure.md

Add Azure CMEK support and improve documentation structure

cd1ba56

mikeCRL added 3 commits July 29, 2025 23:50

Update main CMEK page

a7ddc46

Remove temporary limitation about CMEK on Azure

9869816

Add release note

7494629

mikeCRL requested a review from sanchit-CRL July 30, 2025 04:11

sanchit-CRL reviewed Jul 30, 2025

View reviewed changes

mikeCRL and others added 2 commits August 3, 2025 21:44

Merge branch 'main' into cmek-azure

57f5b73

Updates from techncial review

f2ea229

mikeCRL commented Aug 4, 2025

View reviewed changes

sanchit-CRL approved these changes Aug 4, 2025

View reviewed changes

mikeCRL commented Aug 4, 2025

View reviewed changes

src/current/cockroachcloud/cockroachdb-advanced-on-azure.md Outdated Show resolved Hide resolved

mikeCRL added 2 commits August 4, 2025 03:56

Improved wording per review suggestion

246f89d

Merge branch 'main' into cmek-azure

04bdb3c

mikeCRL enabled auto-merge (squash) August 4, 2025 16:09

mikeCRL merged commit e3338f8 into main Aug 4, 2025
6 checks passed

mikeCRL deleted the cmek-azure branch August 4, 2025 16:18

	1. Click Select members, then search for the enterprise application created above: `ClusterIdentity-<azure_cluster_identity_client_id>`
	1. Click Select members, then search for the enterprise application created above: `CockroachDB Cloud - <CLUSTER_ID>`

Add Azure CMEK support and improve documentation structure #20022

Add Azure CMEK support and improve documentation structure #20022

Conversation

mikeCRL commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

netlify bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

github-actions bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files changed:

Uh oh!

netlify bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sanchit-CRL Jul 30, 2025 • edited by mikeCRL Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikeCRL Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikeCRL left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sanchit-CRL left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mikeCRL commented Jul 30, 2025 •

edited

Loading

netlify bot commented Jul 30, 2025 •

edited

Loading

netlify bot commented Jul 30, 2025 •

edited

Loading

github-actions bot commented Jul 30, 2025 •

edited

Loading

netlify bot commented Jul 30, 2025 •

edited

Loading

sanchit-CRL Jul 30, 2025 •

edited by mikeCRL

Loading

mikeCRL Aug 4, 2025 •

edited

Loading