From b362e6fad08271291469b3806b621aaa0a222116 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 16 Mar 2026 14:56:05 -0400 Subject: [PATCH 1/6] Add warning to dissuade account modifications on BYOC deployments --- src/current/cockroachcloud/byoc-deployment.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/current/cockroachcloud/byoc-deployment.md b/src/current/cockroachcloud/byoc-deployment.md index 42ed987ba8a..933de69cd0e 100644 --- a/src/current/cockroachcloud/byoc-deployment.md +++ b/src/current/cockroachcloud/byoc-deployment.md @@ -43,6 +43,12 @@ Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockro Provision a new Azure subscription with no existing infrastructure, dedicated to your Cockroach {{ site.data.products.cloud }} deployment. The account configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this subscription, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This subscription can be reused for multiple CockroachDB clusters. +{{ site.data.alerts.callout_danger }} + +Once this Azure subscription has been created and configured to host CockroachDB {{ site.data.products.cloud }} clusters, do not make additional modifications to the account. Changes to the cloud account can cause unexpected problems with cluster operations. + +{{ site.data.alerts.end }} + ## Step 2. Grant IAM permissions to Cockroach Labs When BYOC is enabled for your account, Cockroach Labs provisions a multi-tenant App Registration associated with your CockroachDB {{ site.data.products.cloud }} organization and provides you with a URL to grant tenant-wide admin consent to the application. Visit this URL with a user account that is [authorized to consent on behalf of your organization](https://learn.microsoft.com/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal#prerequisites). From f2314a44aa8ce0ae8b56c21f6df372461e90e080 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 6 Apr 2026 12:40:14 -0400 Subject: [PATCH 2/6] Add missing onboarding steps for Azure BYOC --- src/current/cockroachcloud/byoc-deployment.md | 183 +++++++++++++++--- 1 file changed, 152 insertions(+), 31 deletions(-) diff --git a/src/current/cockroachcloud/byoc-deployment.md b/src/current/cockroachcloud/byoc-deployment.md index 933de69cd0e..2c29ca61404 100644 --- a/src/current/cockroachcloud/byoc-deployment.md +++ b/src/current/cockroachcloud/byoc-deployment.md @@ -49,36 +49,157 @@ Once this Azure subscription has been created and configured to host CockroachDB {{ site.data.alerts.end }} -## Step 2. Grant IAM permissions to Cockroach Labs - -When BYOC is enabled for your account, Cockroach Labs provisions a multi-tenant App Registration associated with your CockroachDB {{ site.data.products.cloud }} organization and provides you with a URL to grant tenant-wide admin consent to the application. Visit this URL with a user account that is [authorized to consent on behalf of your organization](https://learn.microsoft.com/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal#prerequisites). - -Once the Cockroach Labs App Registration has been granted admin consent in the tenant, grant the following set of roles to the app: - -- `Role Based Access Control Administrator` -- `Azure Kubernetes Service Cluster User Role` -- `Azure Kubernetes Service Contributor Role` -- `Azure Kubernetes Service RBAC Cluster Admin` -- `Managed Identity Contributor` -- `Network Contributor` -- `Storage Account Contributor` -- `Storage Blob Data Contributor` -- `Virtual Machine Contributor` -- A custom role, `Resource Group Manager`, with the following permissions: - - `Microsoft.Resources/subscriptions/resourceGroups/read` - - `Microsoft.Resources/subscriptions/resourceGroups/write` - - `Microsoft.Resources/subscriptions/resourceGroups/delete` - - `Microsoft.Resources/subscriptions/resourceGroups/moveResources/action` - - `Microsoft.Resources/subscriptions/resourceGroups/validateMoveResources/action` - - `Microsoft.Resources/subscriptions/resourcegroups/deployments/read` - - `Microsoft.Resources/subscriptions/resourcegroups/deployments/write` - - `Microsoft.Resources/subscriptions/resourcegroups/resources/read` - - `Microsoft.Resources/subscriptions/resourcegroups/deployments/operations/read` - - `Microsoft.Resources/subscriptions/resourcegroups/deployments/operationstatuses/read` - -The custom `Resource Group Manager` role is required to create and manage resource groups in the subscription. This role is used instead of requesting the more broad `Contributor` role. - -## Step 3. Register resource providers +## Step 2. Grant admin consent to Cockroach Labs support + +The CockroachDB {{ site.data.products.cloud }} BYOC Reader is an enterprise application in Azure that is used +by Cockroach Labs support. Granting admin consent to this application gives **read-only** permissions to allow +Cockroach Labs support engineers to securely view your Azure resources if needed. + +Follow these steps to grant admin consent to the reader application and assign the necessary permissions: + +1. Log in to the Azure portal as a user with Global Administrator or Privileged Role Administrator permissions. +2. Open the following URL in your browser: + {% include_cached copy-clipboard.html %} + ~~~ text + https://login.microsoftonline.com/adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028 + ~~~ + + If you have multiple tenants, replace `customer-tenant-id` in the following URL with the tenant containing your newly-created Azure subscription: + + {% include_cached copy-clipboard.html %} + ~~~ text + https://login.microsoftonline.com//adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028 + ~~~ +3. Review the requested permissions and click **Accept**. +4. A service principal for the CockroachDB {{ site.data.products.cloud }} BYOC reader is created. Grant the following set of roles to the app: + - `Role Based Access Control Administrator` + - `Azure Kubernetes Service Cluster User Role` + - `Azure Kubernetes Service Contributor Role` + - `Azure Kubernetes Service RBAC Cluster Admin` + - `Managed Identity Contributor` + - `Network Contributor` + - `Storage Account Contributor` + - `Storage Blob Data Contributor` + - `Virtual Machine Contributor` + - A custom role, `Resource Group Manager`, with the following permissions: + + - `Microsoft.Resources/subscriptions/resourceGroups/read` + - `Microsoft.Resources/subscriptions/resourceGroups/write` + - `Microsoft.Resources/subscriptions/resourceGroups/delete` + - `Microsoft.Resources/subscriptions/resourceGroups/moveResources/action` + - `Microsoft.Resources/subscriptions/resourceGroups/validateMoveResources/action` + - `Microsoft.Resources/subscriptions/resourcegroups/deployments/read` + - `Microsoft.Resources/subscriptions/resourcegroups/deployments/write` + - `Microsoft.Resources/subscriptions/resourcegroups/resources/read` + - `Microsoft.Resources/subscriptions/resourcegroups/deployments/operations/read` + - `Microsoft.Resources/subscriptions/resourcegroups/deployments/operationstatuses/read` + + The custom `Resource Group Manager` role is required to create and manage resource groups in the subscription. This role is used instead of requesting the more broad `Contributor` role. + +## Step 3. Configure Azure Lighthouse + +[Azure Lighthouse](https://learn.microsoft.com/azure/lighthouse/overview) enables cross-tenant management to Cockroach Labs with least-privilege access and full customer visibility. You can review or remove this access at any time from the Azure portal. + +This Azure Lighthouse deployment grants the following permissions to Cockroach Labs: + +- Access to the CockroachDB {{ site.data.products.cloud }} BYOC reader application for observability. +- Kubernetes read access for cluster inspection. +- Administrative access for managed operations. + +These permissions are granted to Cockroach Labs's managed tenant, which has a tenant ID of `a4611215-941c-4f86-b53b-348514e57b45` + +Follow these steps to enable secure, scoped access for Cockroach Labs to your subscription using Azure Lighthouse: + +1. Save the following ARM template to a file named `byoc-lighthouse.json`: + {% include_cached copy-clipboard.html %} + ~~~ json + { + "$schema": "https://schema.management.azure.com/schemas/2019-08-01/subscriptionDeploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "mspOfferName": { + "type": "string", + "metadata": { + "description": "Specify a unique name for your offer" + }, + "defaultValue": "CockroachDB Cloud BYOC" + }, + "mspOfferDescription": { + "type": "string", + "metadata": { + "description": "Name of the Managed Service Provider offering" + }, + "defaultValue": "Template to onboard to CockroachDB Cloud BYOC via Lighthouse" + } + }, + "variables": { + "mspRegistrationName": "[guid(parameters('mspOfferName'))]", + "mspAssignmentName": "[guid(parameters('mspOfferName'))]", + "managedByTenantId": "a4611215-941c-4f86-b53b-348514e57b45", + "authorizations": [ + { + "principalId": "c4139366-960c-431d-afad-29c65fd68087", + "roleDefinitionId": "acdd72a7-3385-48ef-bd42-f606fba81ae7", + "principalIdDisplayName": "CockroachDB Cloud BYOC Reader Entra Group" + }, + { + "principalId": "c4139366-960c-431d-afad-29c65fd68087", + "roleDefinitionId": "4abbcc35-e782-43d8-92c5-2d3f1bd2253f", + "principalIdDisplayName": "CockroachDB Cloud BYOC Reader Entra Group" + }, + { + "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a", + "roleDefinitionId": "b24988ac-6180-42a0-ab88-20f7382dd24c", + "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group" + } + ] + }, + "resources": [ + { + "type": "Microsoft.ManagedServices/registrationDefinitions", + "apiVersion": "2020-02-01-preview", + "name": "[variables('mspRegistrationName')]", + "properties": { + "registrationDefinitionName": "[parameters('mspOfferName')]", + "description": "[parameters('mspOfferDescription')]", + "managedByTenantId": "[variables('managedByTenantId')]", + "authorizations": "[variables('authorizations')]" + } + }, + { + "type": "Microsoft.ManagedServices/registrationAssignments", + "apiVersion": "2020-02-01-preview", + "name": "[variables('mspAssignmentName')]", + "dependsOn": [ + "[resourceId('Microsoft.ManagedServices/registrationDefinitions/', variables('mspRegistrationName'))]" + ], + "properties": { + "registrationDefinitionId": "[resourceId('Microsoft.ManagedServices/registrationDefinitions/', variables('mspRegistrationName'))]" + } + } + ], + "outputs": { + "mspOfferName": { + "type": "string", + "value": "[concat('Managed by', ' ', parameters('mspOfferName'))]" + }, + "authorizations": { + "type": "array", + "value": "[variables('authorizations')]" + } + } + } + ~~~ +2. Deploy the template at the subscription scope using Azure CLI, Azure PowerShell, or Azure Portal. The following example command uses the Azure CLI: + {% include_cached copy-clipboard.html %} + ~~~ shell + az deployment sub create \ + --name cockroach-byoc-lighthouse \ + --location \ + --template-file byoc-lighthouse.json + ~~~ + +## Step 4. Register resource providers Register the following [resource providers](https://learn.microsoft.com/azure/azure-resource-manager/management/resource-providers-and-types) in the Azure subscription: @@ -88,7 +209,7 @@ Register the following [resource providers](https://learn.microsoft.com/azure/az - `Microsoft.Quota` - `Microsoft.Storage` -## Step 4. Create the CockroachDB {{ site.data.products.cloud }} cluster +## Step 5. Create the CockroachDB {{ site.data.products.cloud }} cluster In BYOC deployments, CockroachDB clusters are deployed with the {{ site.data.products.cloud }} API and must use the {{ site.data.products.advanced }} plan. Follow the API documentation to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). From 91b0b4b7419a140b1944c8b548e6e53343e3f7bc Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Thu, 9 Apr 2026 22:42:27 -0400 Subject: [PATCH 3/6] Clarify admin vs reader application steps --- src/current/cockroachcloud/byoc-deployment.md | 32 ++++++++++++------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/src/current/cockroachcloud/byoc-deployment.md b/src/current/cockroachcloud/byoc-deployment.md index 2c29ca61404..ceea1a32826 100644 --- a/src/current/cockroachcloud/byoc-deployment.md +++ b/src/current/cockroachcloud/byoc-deployment.md @@ -49,13 +49,9 @@ Once this Azure subscription has been created and configured to host CockroachDB {{ site.data.alerts.end }} -## Step 2. Grant admin consent to Cockroach Labs support +## Step 2. Grant admin consent to the BYOC enterprise application -The CockroachDB {{ site.data.products.cloud }} BYOC Reader is an enterprise application in Azure that is used -by Cockroach Labs support. Granting admin consent to this application gives **read-only** permissions to allow -Cockroach Labs support engineers to securely view your Azure resources if needed. - -Follow these steps to grant admin consent to the reader application and assign the necessary permissions: +When BYOC is enabled for your account, Cockroach Labs provisions the CockroachDB {{ site.data.products.cloud }} BYOC Reader enterprise application. This application requires admin consent to deploy the read-only infrastructure that is then used by Cockroach Labs support as needed. 1. Log in to the Azure portal as a user with Global Administrator or Privileged Role Administrator permissions. 2. Open the following URL in your browser: @@ -70,8 +66,7 @@ Follow these steps to grant admin consent to the reader application and assign t ~~~ text https://login.microsoftonline.com//adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028 ~~~ -3. Review the requested permissions and click **Accept**. -4. A service principal for the CockroachDB {{ site.data.products.cloud }} BYOC reader is created. Grant the following set of roles to the app: +3. Review the requested permissions and click **Accept**. The following permissions are requested: - `Role Based Access Control Administrator` - `Azure Kubernetes Service Cluster User Role` - `Azure Kubernetes Service Contributor Role` @@ -82,7 +77,6 @@ Follow these steps to grant admin consent to the reader application and assign t - `Storage Blob Data Contributor` - `Virtual Machine Contributor` - A custom role, `Resource Group Manager`, with the following permissions: - - `Microsoft.Resources/subscriptions/resourceGroups/read` - `Microsoft.Resources/subscriptions/resourceGroups/write` - `Microsoft.Resources/subscriptions/resourceGroups/delete` @@ -96,7 +90,17 @@ Follow these steps to grant admin consent to the reader application and assign t The custom `Resource Group Manager` role is required to create and manage resource groups in the subscription. This role is used instead of requesting the more broad `Contributor` role. -## Step 3. Configure Azure Lighthouse +## Step 3. Grant permissions to the service principle + +The CockroachDB {{ site.data.products.cloud }} BYOC Reader application creates a read-only service principle. This service principle is only used for read-only access and Kubernetes cluster visibility by Cockroach Labs support. + +Assign the following Azure RBAC roles to the service principle at the subscription scope: + +- `Reader` +- `Azure Kubernetes Service Cluster User Role` +- `Azure Kubernetes Service RBAC Reader` + +## Step 4. Configure Azure Lighthouse [Azure Lighthouse](https://learn.microsoft.com/azure/lighthouse/overview) enables cross-tenant management to Cockroach Labs with least-privilege access and full customer visibility. You can review or remove this access at any time from the Azure portal. @@ -106,7 +110,13 @@ This Azure Lighthouse deployment grants the following permissions to Cockroach L - Kubernetes read access for cluster inspection. - Administrative access for managed operations. -These permissions are granted to Cockroach Labs's managed tenant, which has a tenant ID of `a4611215-941c-4f86-b53b-348514e57b45` +These permissions are granted to Cockroach Labs's managed tenant, which has a tenant ID of `a4611215-941c-4f86-b53b-348514e57b45`, by assigning the following roles to the reader and admin Entra groups within the tenant: + +- Reader Entra group: + - `Reader` + - `Azure Kubernetes Service Cluster User Role` +- Admin Entra group: + - `Contributor` Follow these steps to enable secure, scoped access for Cockroach Labs to your subscription using Azure Lighthouse: From 4d692dd1ae77aa7284a7f1a0da5a36c3eb934a8d Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Fri, 10 Apr 2026 15:53:25 -0400 Subject: [PATCH 4/6] Vishal comments --- src/current/cockroachcloud/byoc-deployment.md | 85 +++++++++---------- 1 file changed, 38 insertions(+), 47 deletions(-) diff --git a/src/current/cockroachcloud/byoc-deployment.md b/src/current/cockroachcloud/byoc-deployment.md index ceea1a32826..45c56cc909f 100644 --- a/src/current/cockroachcloud/byoc-deployment.md +++ b/src/current/cockroachcloud/byoc-deployment.md @@ -49,9 +49,38 @@ Once this Azure subscription has been created and configured to host CockroachDB {{ site.data.alerts.end }} -## Step 2. Grant admin consent to the BYOC enterprise application +## Step 2. Set up the admin enterprise application -When BYOC is enabled for your account, Cockroach Labs provisions the CockroachDB {{ site.data.products.cloud }} BYOC Reader enterprise application. This application requires admin consent to deploy the read-only infrastructure that is then used by Cockroach Labs support as needed. +When BYOC is enabled for your account, Cockroach Labs dynamically provisions a multi-tenant admin App Registration associated with your CockroachDB {{ site.data.products.cloud }} organization and provides you with a URL to grant tenant-wide admin consent to the application. Visit this URL with a user account that is [authorized to consent on behalf of your organization](https://learn.microsoft.com/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal#prerequisites). + +Once the Cockroach Labs App Registration has been granted admin consent in the tenant, grant the following set of roles to the app: + +- `Role Based Access Control Administrator` +- `Azure Kubernetes Service Cluster User Role` +- `Azure Kubernetes Service Contributor Role` +- `Azure Kubernetes Service RBAC Cluster Admin` +- `Managed Identity Contributor` +- `Network Contributor` +- `Storage Account Contributor` +- `Storage Blob Data Contributor` +- `Virtual Machine Contributor` +- A custom role, `Resource Group Manager`, with the following permissions: + - `Microsoft.Resources/subscriptions/resourceGroups/read` + - `Microsoft.Resources/subscriptions/resourceGroups/write` + - `Microsoft.Resources/subscriptions/resourceGroups/delete` + - `Microsoft.Resources/subscriptions/resourceGroups/moveResources/action` + - `Microsoft.Resources/subscriptions/resourceGroups/validateMoveResources/action` + - `Microsoft.Resources/subscriptions/resourcegroups/deployments/read` + - `Microsoft.Resources/subscriptions/resourcegroups/deployments/write` + - `Microsoft.Resources/subscriptions/resourcegroups/resources/read` + - `Microsoft.Resources/subscriptions/resourcegroups/deployments/operations/read` + - `Microsoft.Resources/subscriptions/resourcegroups/deployments/operationstatuses/read` + +The custom `Resource Group Manager` role is required to create and manage resource groups in the subscription. This role is used instead of requesting the more broad `Contributor` role. + +## Step 3. Set up the reader enterprise application + +In addition to the admin application, Cockroach Labs provisions the CockroachDB {{ site.data.products.cloud }} BYOC Reader enterprise application. This application also requires admin consent to deploy the read-only infrastructure that is then used by Cockroach Labs support as needed. 1. Log in to the Azure portal as a user with Global Administrator or Privileged Role Administrator permissions. 2. Open the following URL in your browser: @@ -66,51 +95,13 @@ When BYOC is enabled for your account, Cockroach Labs provisions the CockroachDB ~~~ text https://login.microsoftonline.com//adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028 ~~~ -3. Review the requested permissions and click **Accept**. The following permissions are requested: - - `Role Based Access Control Administrator` - - `Azure Kubernetes Service Cluster User Role` - - `Azure Kubernetes Service Contributor Role` - - `Azure Kubernetes Service RBAC Cluster Admin` - - `Managed Identity Contributor` - - `Network Contributor` - - `Storage Account Contributor` - - `Storage Blob Data Contributor` - - `Virtual Machine Contributor` - - A custom role, `Resource Group Manager`, with the following permissions: - - `Microsoft.Resources/subscriptions/resourceGroups/read` - - `Microsoft.Resources/subscriptions/resourceGroups/write` - - `Microsoft.Resources/subscriptions/resourceGroups/delete` - - `Microsoft.Resources/subscriptions/resourceGroups/moveResources/action` - - `Microsoft.Resources/subscriptions/resourceGroups/validateMoveResources/action` - - `Microsoft.Resources/subscriptions/resourcegroups/deployments/read` - - `Microsoft.Resources/subscriptions/resourcegroups/deployments/write` - - `Microsoft.Resources/subscriptions/resourcegroups/resources/read` - - `Microsoft.Resources/subscriptions/resourcegroups/deployments/operations/read` - - `Microsoft.Resources/subscriptions/resourcegroups/deployments/operationstatuses/read` - - The custom `Resource Group Manager` role is required to create and manage resource groups in the subscription. This role is used instead of requesting the more broad `Contributor` role. - -## Step 3. Grant permissions to the service principle - -The CockroachDB {{ site.data.products.cloud }} BYOC Reader application creates a read-only service principle. This service principle is only used for read-only access and Kubernetes cluster visibility by Cockroach Labs support. - -Assign the following Azure RBAC roles to the service principle at the subscription scope: - -- `Reader` -- `Azure Kubernetes Service Cluster User Role` -- `Azure Kubernetes Service RBAC Reader` - -## Step 4. Configure Azure Lighthouse - -[Azure Lighthouse](https://learn.microsoft.com/azure/lighthouse/overview) enables cross-tenant management to Cockroach Labs with least-privilege access and full customer visibility. You can review or remove this access at any time from the Azure portal. +3. Review the requested permissions and click **Accept**. -This Azure Lighthouse deployment grants the following permissions to Cockroach Labs: +## Step 4. Grant permissions to the reader service principle with Azure Lighthouse -- Access to the CockroachDB {{ site.data.products.cloud }} BYOC reader application for observability. -- Kubernetes read access for cluster inspection. -- Administrative access for managed operations. +The CockroachDB {{ site.data.products.cloud }} BYOC Reader application creates a read-only service principle. Use [Azure Lighthouse](https://learn.microsoft.com/azure/lighthouse/overview) to enable cross-tenant management to the service principle with least-privilege access and full customer visibility. You can review or remove this access at any time from the Azure portal. -These permissions are granted to Cockroach Labs's managed tenant, which has a tenant ID of `a4611215-941c-4f86-b53b-348514e57b45`, by assigning the following roles to the reader and admin Entra groups within the tenant: +This Azure Lighthouse deployment grants permissions to Cockroach Labs's managed tenant, which has a tenant ID of `a4611215-941c-4f86-b53b-348514e57b45`, by assigning the following roles to the reader and admin Entra groups within the tenant: - Reader Entra group: - `Reader` @@ -200,7 +191,7 @@ Follow these steps to enable secure, scoped access for Cockroach Labs to your su } } ~~~ -2. Deploy the template at the subscription scope using Azure CLI, Azure PowerShell, or Azure Portal. The following example command uses the Azure CLI: +2. Deploy the template at the subscription scope using [Azure CLI, Azure PowerShell, or Azure Portal](https://learn.microsoft.com/azure/lighthouse/how-to/onboard-customer?tabs=azure-portal#deploy-the-azure-resource-manager-template). The following example command uses the Azure CLI: {% include_cached copy-clipboard.html %} ~~~ shell az deployment sub create \ @@ -209,7 +200,7 @@ Follow these steps to enable secure, scoped access for Cockroach Labs to your su --template-file byoc-lighthouse.json ~~~ -## Step 4. Register resource providers +## Step 5. Register resource providers Register the following [resource providers](https://learn.microsoft.com/azure/azure-resource-manager/management/resource-providers-and-types) in the Azure subscription: @@ -219,7 +210,7 @@ Register the following [resource providers](https://learn.microsoft.com/azure/az - `Microsoft.Quota` - `Microsoft.Storage` -## Step 5. Create the CockroachDB {{ site.data.products.cloud }} cluster +## Step 6. Create the CockroachDB {{ site.data.products.cloud }} cluster In BYOC deployments, CockroachDB clusters are deployed with the {{ site.data.products.cloud }} API and must use the {{ site.data.products.advanced }} plan. Follow the API documentation to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). From 1bbdd0d5f8233ec343f69013abbfd2c7ea695256 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 13 Apr 2026 14:46:14 -0400 Subject: [PATCH 5/6] Correct entity naming --- src/current/cockroachcloud/byoc-deployment.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/current/cockroachcloud/byoc-deployment.md b/src/current/cockroachcloud/byoc-deployment.md index 45c56cc909f..6c6bbdd0369 100644 --- a/src/current/cockroachcloud/byoc-deployment.md +++ b/src/current/cockroachcloud/byoc-deployment.md @@ -49,11 +49,11 @@ Once this Azure subscription has been created and configured to host CockroachDB {{ site.data.alerts.end }} -## Step 2. Set up the admin enterprise application +## Step 2. Set up the admin App Registration -When BYOC is enabled for your account, Cockroach Labs dynamically provisions a multi-tenant admin App Registration associated with your CockroachDB {{ site.data.products.cloud }} organization and provides you with a URL to grant tenant-wide admin consent to the application. Visit this URL with a user account that is [authorized to consent on behalf of your organization](https://learn.microsoft.com/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal#prerequisites). +When BYOC is enabled for your account, Cockroach Labs dynamically provisions a multi-tenant admin App Registration associated with your CockroachDB {{ site.data.products.cloud }} organization and provides you with a URL to grant tenant-wide admin consent to the application. Granting admin consent creates an admin Service Principal in your tenant, which is used to grant Cockroach Labs engineers admin access to the Kubernetes cluster to assist in the event of an escalation. -Once the Cockroach Labs App Registration has been granted admin consent in the tenant, grant the following set of roles to the app: +Visit this URL with a user account that is [authorized to consent on behalf of your organization](https://learn.microsoft.com/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal#prerequisites). Once the Cockroach Labs App Registration has been granted admin consent in the tenant, grant the following set of roles to the admin Service Principal: - `Role Based Access Control Administrator` - `Azure Kubernetes Service Cluster User Role` @@ -78,9 +78,11 @@ Once the Cockroach Labs App Registration has been granted admin consent in the t The custom `Resource Group Manager` role is required to create and manage resource groups in the subscription. This role is used instead of requesting the more broad `Contributor` role. -## Step 3. Set up the reader enterprise application +## Step 3. Set up the reader App Registration -In addition to the admin application, Cockroach Labs provisions the CockroachDB {{ site.data.products.cloud }} BYOC Reader enterprise application. This application also requires admin consent to deploy the read-only infrastructure that is then used by Cockroach Labs support as needed. +In addition to the admin application, Cockroach Labs provisions the CockroachDB {{ site.data.products.cloud }} BYOC Reader App Registration. This App Registration is used to grant Cockroach Labs engineers the default read-only access to Azure cloud resources. + +This reader application also requires admin consent to deploy the reader Service Principal: 1. Log in to the Azure portal as a user with Global Administrator or Privileged Role Administrator permissions. 2. Open the following URL in your browser: From 3e67108cdc256f6f6ed03c622d965108d50b803a Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Tue, 14 Apr 2026 13:23:21 -0400 Subject: [PATCH 6/6] Update template and some wording --- src/current/cockroachcloud/byoc-deployment.md | 173 ++++++++++-------- 1 file changed, 99 insertions(+), 74 deletions(-) diff --git a/src/current/cockroachcloud/byoc-deployment.md b/src/current/cockroachcloud/byoc-deployment.md index 6c6bbdd0369..eb776f6e53c 100644 --- a/src/current/cockroachcloud/byoc-deployment.md +++ b/src/current/cockroachcloud/byoc-deployment.md @@ -51,7 +51,7 @@ Once this Azure subscription has been created and configured to host CockroachDB ## Step 2. Set up the admin App Registration -When BYOC is enabled for your account, Cockroach Labs dynamically provisions a multi-tenant admin App Registration associated with your CockroachDB {{ site.data.products.cloud }} organization and provides you with a URL to grant tenant-wide admin consent to the application. Granting admin consent creates an admin Service Principal in your tenant, which is used to grant Cockroach Labs engineers admin access to the Kubernetes cluster to assist in the event of an escalation. +When BYOC is enabled for your account, Cockroach Labs dynamically provisions a multi-tenant admin App Registration associated with your CockroachDB {{ site.data.products.cloud }} organization and provides you with a URL to grant tenant-wide admin consent to the application. Granting admin consent creates an admin Service Principal in your tenant, which is used by Cockroach Labs support to act on the Kubernetes cluster in the event of an escalation. Visit this URL with a user account that is [authorized to consent on behalf of your organization](https://learn.microsoft.com/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal#prerequisites). Once the Cockroach Labs App Registration has been granted admin consent in the tenant, grant the following set of roles to the admin Service Principal: @@ -80,7 +80,7 @@ The custom `Resource Group Manager` role is required to create and manage resour ## Step 3. Set up the reader App Registration -In addition to the admin application, Cockroach Labs provisions the CockroachDB {{ site.data.products.cloud }} BYOC Reader App Registration. This App Registration is used to grant Cockroach Labs engineers the default read-only access to Azure cloud resources. +In addition to the admin application, Cockroach Labs provisions the CockroachDB {{ site.data.products.cloud }} BYOC Reader App Registration. This App Registration is used to grant reader permissions to Cockroach {{ site.data.products.cloud }} automation. This reader application also requires admin consent to deploy the reader Service Principal: @@ -99,9 +99,9 @@ This reader application also requires admin consent to deploy the reader Service ~~~ 3. Review the requested permissions and click **Accept**. -## Step 4. Grant permissions to the reader service principle with Azure Lighthouse +## Step 4. Grant persmissions to auth principals with Azure Lighthouse -The CockroachDB {{ site.data.products.cloud }} BYOC Reader application creates a read-only service principle. Use [Azure Lighthouse](https://learn.microsoft.com/azure/lighthouse/overview) to enable cross-tenant management to the service principle with least-privilege access and full customer visibility. You can review or remove this access at any time from the Azure portal. +Use [Azure Lighthouse](https://learn.microsoft.com/azure/lighthouse/overview) to enable cross-tenant management that grants individual Cockroach Labs engineers persmissions on the service principle as needed for support purposes. Permissions are applied to the service principle with least-privilege access and full visibility, allowing you to review or remove this access at any time from the Azure portal. This Azure Lighthouse deployment grants permissions to Cockroach Labs's managed tenant, which has a tenant ID of `a4611215-941c-4f86-b53b-348514e57b45`, by assigning the following roles to the reader and admin Entra groups within the tenant: @@ -117,81 +117,106 @@ Follow these steps to enable secure, scoped access for Cockroach Labs to your su {% include_cached copy-clipboard.html %} ~~~ json { - "$schema": "https://schema.management.azure.com/schemas/2019-08-01/subscriptionDeploymentTemplate.json#", - "contentVersion": "1.0.0.0", - "parameters": { - "mspOfferName": { - "type": "string", - "metadata": { - "description": "Specify a unique name for your offer" - }, - "defaultValue": "CockroachDB Cloud BYOC" - }, - "mspOfferDescription": { - "type": "string", - "metadata": { - "description": "Name of the Managed Service Provider offering" - }, - "defaultValue": "Template to onboard to CockroachDB Cloud BYOC via Lighthouse" - } + "$schema": "https://schema.management.azure.com/schemas/2019-08-01/subscriptionDeploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "mspOfferName": { + "type": "string", + "metadata": { + "description": "Specify a unique name for your offer" }, - "variables": { - "mspRegistrationName": "[guid(parameters('mspOfferName'))]", - "mspAssignmentName": "[guid(parameters('mspOfferName'))]", - "managedByTenantId": "a4611215-941c-4f86-b53b-348514e57b45", - "authorizations": [ - { - "principalId": "c4139366-960c-431d-afad-29c65fd68087", - "roleDefinitionId": "acdd72a7-3385-48ef-bd42-f606fba81ae7", - "principalIdDisplayName": "CockroachDB Cloud BYOC Reader Entra Group" - }, - { - "principalId": "c4139366-960c-431d-afad-29c65fd68087", - "roleDefinitionId": "4abbcc35-e782-43d8-92c5-2d3f1bd2253f", - "principalIdDisplayName": "CockroachDB Cloud BYOC Reader Entra Group" - }, - { - "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a", - "roleDefinitionId": "b24988ac-6180-42a0-ab88-20f7382dd24c", - "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group" - } - ] + "defaultValue": "CockroachDB Cloud BYOC" }, - "resources": [ - { - "type": "Microsoft.ManagedServices/registrationDefinitions", - "apiVersion": "2020-02-01-preview", - "name": "[variables('mspRegistrationName')]", - "properties": { - "registrationDefinitionName": "[parameters('mspOfferName')]", - "description": "[parameters('mspOfferDescription')]", - "managedByTenantId": "[variables('managedByTenantId')]", - "authorizations": "[variables('authorizations')]" - } - }, - { - "type": "Microsoft.ManagedServices/registrationAssignments", - "apiVersion": "2020-02-01-preview", - "name": "[variables('mspAssignmentName')]", - "dependsOn": [ - "[resourceId('Microsoft.ManagedServices/registrationDefinitions/', variables('mspRegistrationName'))]" - ], - "properties": { - "registrationDefinitionId": "[resourceId('Microsoft.ManagedServices/registrationDefinitions/', variables('mspRegistrationName'))]" - } - } + "mspOfferDescription": { + "type": "string", + "metadata": { + "description": "Name of the Managed Service Provider offering" + }, + "defaultValue": "Template for secure access to customer clusters in CockroachDB Cloud BYOC" + } + }, + "variables": { + "mspRegistrationName": "[guid(parameters('mspOfferName'))]", + "mspAssignmentName": "[guid(parameters('mspOfferName'))]", + "managedByTenantId": "a4611215-941c-4f86-b53b-348514e57b45", + "authorizations": [ + { + "principalId": "c4139366-960c-431d-afad-29c65fd68087", + "roleDefinitionId": "acdd72a7-3385-48ef-bd42-f606fba81ae7", + "principalIdDisplayName": "CockroachDB Cloud BYOC Reader Entra Group" + }, + { + "principalId": "c4139366-960c-431d-afad-29c65fd68087", + "roleDefinitionId": "4abbcc35-e782-43d8-92c5-2d3f1bd2253f", + "principalIdDisplayName": "CockroachDB Cloud BYOC Reader Entra Group" + }, + { + "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a", + "roleDefinitionId": "ed7f3fbd-7b88-4dd4-9017-9adb7ce333f8", + "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group" + }, + { + "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a", + "roleDefinitionId": "0ab0b1a8-8aac-4efd-b8c2-3ee1fb270be8", + "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group" + }, + { + "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a", + "roleDefinitionId": "e40ec5ca-96e0-45a2-b4ff-59039f2c2b59", + "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group" + }, + { + "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a", + "roleDefinitionId": "4d97b98b-1d4f-4787-a291-c67834d212e7", + "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group" + }, + { + "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a", + "roleDefinitionId": "17d1049b-9a84-46fb-8f53-869881c3d3ab", + "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group" + }, + { + "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a", + "roleDefinitionId": "9980e02c-c2be-4d73-94e8-173b1dc7cf3c", + "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group" + } + ] + }, + "resources": [ + { + "type": "Microsoft.ManagedServices/registrationDefinitions", + "apiVersion": "2022-10-01", + "name": "[variables('mspRegistrationName')]", + "properties": { + "registrationDefinitionName": "[parameters('mspOfferName')]", + "description": "[parameters('mspOfferDescription')]", + "managedByTenantId": "[variables('managedByTenantId')]", + "authorizations": "[variables('authorizations')]" + } + }, + { + "type": "Microsoft.ManagedServices/registrationAssignments", + "apiVersion": "2022-10-01", + "name": "[variables('mspAssignmentName')]", + "dependsOn": [ + "[resourceId('Microsoft.ManagedServices/registrationDefinitions/', variables('mspRegistrationName'))]" ], - "outputs": { - "mspOfferName": { - "type": "string", - "value": "[concat('Managed by', ' ', parameters('mspOfferName'))]" - }, - "authorizations": { - "type": "array", - "value": "[variables('authorizations')]" - } + "properties": { + "registrationDefinitionId": "[resourceId('Microsoft.ManagedServices/registrationDefinitions/', variables('mspRegistrationName'))]" } } + ], + "outputs": { + "mspOfferName": { + "type": "string", + "value": "[concat('Managed by', ' ', parameters('mspOfferName'))]" + }, + "authorizations": { + "type": "array", + "value": "[variables('authorizations')]" + } + } + } ~~~ 2. Deploy the template at the subscription scope using [Azure CLI, Azure PowerShell, or Azure Portal](https://learn.microsoft.com/azure/lighthouse/how-to/onboard-customer?tabs=azure-portal#deploy-the-azure-resource-manager-template). The following example command uses the Azure CLI: {% include_cached copy-clipboard.html %}