> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prepare a Continuum Cloud BYOC Deployment in Azure

This page describes how to prepare a Microsoft Azure account to host a [BYOC deployment](https://docs.cockroachlabs.com/docs/continuum/byoc-overview.md) of a Continuum Cloud Mission Critical cluster.

## Prerequisites

* Review the [shared responsibility model for BYOC](https://docs.cockroachlabs.com/docs/continuum/byoc-overview.md#shared-responsibility-model-for-byoc). Make sure you understand and acknowledge the responsibilities you hold for management of your cloud infrastructure and the necessary permissions you must grant to Cockroach Labs.

* [Create a Continuum Cloud organization](https://docs.cockroachlabs.com/docs/continuum/create-a-continuum-organization.md) if you do not already have one.

* More than one BYOC cluster can run in a single Azure subscription.

* BYOC is not enabled by default. To enable BYOC for your organization, contact your Cockroach Labs account team.

* BYOC clusters use the [Mission Critical edition](https://docs.cockroachlabs.com/docs/continuum/editions-and-add-ons.md#editions) with provisioned storage. The Standard edition and usage-based storage are not available on BYOC.

* Once you have prepared your cloud account for a BYOC deployment, cluster configuration and management is identical to a Mission Critical cluster in a Cockroach Labs account. Review [Create a Cluster](https://docs.cockroachlabs.com/docs/continuum/create-a-cluster.md) and the [Plan a CockroachDB Advanced Cluster](https://docs.cockroachlabs.com/docs/cockroachcloud/plan-your-cluster-advanced.md) documentation to plan your cluster sizing and resource allocation.

  > [!NOTE]
  >
  > BYOC on Azure supports a restricted set of VM series. Before sizing a deployment, confirm the supported VM series with your Cockroach Labs account team.

* Review the cloud service regions supported by the Mission Critical edition in [Which cloud providers and regions does each edition support?](https://docs.cockroachlabs.com/docs/continuum/faq.md#which-cloud-providers-and-regions-does-each-edition-support)

* The Azure subscription must not contain resources that can affect the control plane's ability to operate on CockroachDB clusters.

* (Optional) Create an [API service account](https://docs.cockroachlabs.com/docs/cockroachcloud/managing-access.md#create-api-keys) to use the [Cloud API](https://docs.cockroachlabs.com/docs/continuum/cloud-api.md) with your Continuum Cloud organization.

## Step 1. Create a new Azure subscription

Provision a new Azure subscription dedicated to CockroachDB infrastructure. BYOC requires you to grant Cockroach Labs permission to access and modify resources in this subscription. A dedicated subscription keeps these permissions separate from your other resources and allows Cockroach Labs to meet cluster uptime SLAs. You can reuse this subscription for multiple CockroachDB clusters.

> [!CAUTION]
>
> After you create and configure this Azure subscription to host Continuum Cloud clusters, do not modify it. Changes to the subscription can cause unexpected problems with cluster operations.

## Step 2. Set up the admin App Registration

After Cockroach Labs enables BYOC for your Continuum Cloud organization, Cockroach Labs creates an admin **App Registration** for your organization and gives you a URL for granting tenant-wide admin consent to it. Granting consent creates an admin **Service Principal** in your Microsoft Entra tenant. Cockroach Labs support uses this Service Principal to run the automation that sets up support infrastructure on the Kubernetes cluster.

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). After you grant admin consent, grant the following roles to the admin Service Principal:

* `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`

Cockroach Labs uses the custom `Resource Group Manager` role to create and manage resource groups in the subscription, instead of the broader `Contributor` role.

## Step 3. Set up the reader App Registration

In addition to the admin application, Cockroach Labs provisions the **CockroachDB Cloud BYOC Reader** App Registration. Cockroach Labs support uses this App Registration for read access to Kubernetes infrastructure.

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:

   ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   https://login.microsoftonline.com/adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028
   ```

   If your organization has multiple Microsoft Entra tenants, use the following URL instead, and replace `{customer-tenant-id}` with the ID of the tenant that contains your new Azure subscription:

   ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   https://login.microsoftonline.com/{customer-tenant-id}/adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028
   ```
3. Review the requested permissions and click **Accept**.
4. After you grant admin consent to the **CockroachDB Cloud BYOC Reader** App Registration, grant the following roles to the reader Service Principal:
   * `Reader`
   * `Azure Kubernetes Service Cluster User`
   * `Azure Kubernetes Service RBAC Reader`

## Step 4. Grant permissions to Entra groups with Azure Lighthouse

Use [Azure Lighthouse](https://learn.microsoft.com/azure/lighthouse/overview) to give Cockroach Labs scoped, cross-tenant access to your subscription for support escalations. Access granted during an escalation is least-privilege and visible to you, and you can review and remove it at any time in the Azure portal.

> [!CAUTION]
>
> The permission policy described in this step is the minimum required for Cockroach Labs to provision, operate, patch, back up, and heal your cluster over its full lifecycle. This is not a temporary permission set used only at time of creation.
>
> Do **not** remove, narrow, or add conditions to these permissions after setup. Many of these permissions are used only during a specific lifecycle event, such as replacing a failed node, applying a patch, rotating an encryption key, or running a managed backup. Removing a permission might not cause an immediate error. A later operation that requires it, such as replacing a failed node or running a backup, can fail. Reducing the permission set voids the availability commitment for the cluster.
>
> Guardrails that restrict the account to particular regions or services, without touching the permissions the deployment requires, are compatible. Azure policies that restrict this permission set are not supported.

This Azure Lighthouse deployment grants permissions to Cockroach Labs' 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:
  * `Reader`
  * `Azure Kubernetes Service Contributor Role`
  * `Azure Kubernetes Service Cluster Admin`
  * `Managed Identity Contributor`
  * `Network Contributor`
  * `Storage Account Contributor`
  * `Virtual Machine Contributor`

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`:

   ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   {
     "$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 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": "acdd72a7-3385-48ef-bd42-f606fba81ae7",
           "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group"
         }
       ],
       "eligibleAuthorizations": [
         {
           "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a",
           "roleDefinitionId": "ed7f3fbd-7b88-4dd4-9017-9adb7ce333f8",
           "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group",
           "justInTimeAccessPolicy": {
             "multiFactorAuthProvider": "Azure",
             "maximumActivationDuration": "PT8H"
           }
         },
         {
           "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a",
           "roleDefinitionId": "0ab0b1a8-8aac-4efd-b8c2-3ee1fb270be8",
           "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group",
           "justInTimeAccessPolicy": {
             "multiFactorAuthProvider": "Azure",
             "maximumActivationDuration": "PT8H"
           }
         },
         {
           "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a",
           "roleDefinitionId": "e40ec5ca-96e0-45a2-b4ff-59039f2c2b59",
           "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group",
           "justInTimeAccessPolicy": {
             "multiFactorAuthProvider": "Azure",
             "maximumActivationDuration": "PT8H"
           }
         },
         {
           "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a",
           "roleDefinitionId": "4d97b98b-1d4f-4787-a291-c67834d212e7",
           "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group",
           "justInTimeAccessPolicy": {
             "multiFactorAuthProvider": "Azure",
             "maximumActivationDuration": "PT8H"
           }
         },
         {
           "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a",
           "roleDefinitionId": "17d1049b-9a84-46fb-8f53-869881c3d3ab",
           "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group",
           "justInTimeAccessPolicy": {
             "multiFactorAuthProvider": "Azure",
             "maximumActivationDuration": "PT8H"
           }
         },
         {
           "principalId": "6532a4f2-3fa1-4b10-a4c2-05368c87c89a",
           "roleDefinitionId": "9980e02c-c2be-4d73-94e8-173b1dc7cf3c",
           "principalIdDisplayName": "CockroachDB Cloud BYOC Admin Entra Group",
           "justInTimeAccessPolicy": {
             "multiFactorAuthProvider": "Azure",
             "maximumActivationDuration": "PT8H"
           }
         }
       ]
     },
     "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')]",
           "eligibleAuthorizations": "[variables('eligibleAuthorizations')]"
         }
       },
       {
         "type": "Microsoft.ManagedServices/registrationAssignments",
         "apiVersion": "2022-10-01",
         "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')]"
       },
       "eligibleAuthorizations": {
         "type": "array",
         "value": "[variables('eligibleAuthorizations')]"
       }
     }
   }
   ```
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:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   az deployment sub create \
     --name cockroach-byoc-lighthouse \
     --location {region} \
     --template-file byoc-lighthouse.json
   ```

## 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:

* `Microsoft.ContainerService`
* `Microsoft.ManagedIdentity`
* `Microsoft.Network`
* `Microsoft.Quota`
* `Microsoft.Storage`

## Step 6. Create the Continuum Cloud cluster

In BYOC deployments, you can deploy CockroachDB clusters in the Cloud Console or with the [Cloud API](https://docs.cockroachlabs.com/docs/continuum/cloud-api.md).

### Create a cluster with the Cloud Console

Follow these steps to create a Mission Critical cluster in the Cloud Console:

1. Open the Cloud Console and select the organization where BYOC is enabled.
2. Click **New cluster**.
3. For the edition, choose **Mission Critical**. BYOC is available only for the Mission Critical edition.
4. For the deployment, choose **Bring Your Own Cloud**, then select Azure as the cloud provider.
5. Under **Cloud account**, select the cloud account you prepared, or add a new cloud account. Enter the tenant ID and subscription ID associated with your Azure subscription.
6. Configure the cluster's regions, capacity, and add-ons as desired, then create the cluster. Refer to [Create a Cluster](https://docs.cockroachlabs.com/docs/continuum/create-a-cluster.md) and [Plan a CockroachDB Advanced Cluster](https://docs.cockroachlabs.com/docs/cockroachcloud/plan-your-cluster-advanced.md) for more details.

### Create a cluster with the Cloud API

Send a `POST` request to the `/v1/clusters` endpoint of the [Cloud API](https://docs.cockroachlabs.com/docs/continuum/cloud-api.md) to create a Mission Critical cluster, specifying the appropriate `edition`.

The following example request creates a 3-node Mission Critical cluster in the `centralus` region, specifying the `subscription-id` and `customer-tenant-id` associated with your Azure subscription:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{
    "name":"byoc-azure-cluster-1",
    "provider": "AZURE",
    "spec": {
      "edition": "MISSION_CRITICAL",
      "customer_cloud_account": {
        "azure": {
          "subscription_id": "{subscription-id}",
          "tenant_id": "{customer-tenant-id}"
        }
      },
      "dedicated": {
        "hardware": {
          "machine_spec": {
            "num_virtual_cpus": 4
          },
          "storage_gib": 16
        },
        "region_nodes": {
          "centralus": 3
        }
      }
    }
  }'
```

## Create additional BYOC clusters

An Azure subscription prepared for BYOC can support multiple Continuum Cloud clusters. To create an additional BYOC cluster in the same subscription, follow the [Create the Continuum Cloud cluster](#step-6-create-the-continuum-cloud-cluster) steps again.

## Delete a BYOC cluster

To delete a BYOC cluster, delete the cluster from the Cloud Console or with the [Cloud API](https://docs.cockroachlabs.com/docs/api/cloud/v1/clusters/delete-a-cluster-and-all-of-its-data.md). The Console steps are the same as for any Mission Critical cluster; refer to [Delete cluster](https://docs.cockroachlabs.com/docs/cockroachcloud/advanced-cluster-management.md#delete-cluster). Deleting the cluster is permanent and cannot be undone.

When you delete a BYOC cluster, Cockroach Labs removes the managed resources that it provisioned in your Azure subscription for the cluster.

The admin and reader Service Principals created when you granted admin consent during setup and the Azure Lighthouse registration you deployed are not removed automatically and remain under your control. You can remove them once deletion is complete.

> [!CAUTION]
>
> Do not remove the Service Principals, the Azure Lighthouse registration, or their role assignments before deletion has finished. Cockroach Labs needs them to remove the managed resources from your Azure subscription. Removing access early can leave resources behind that you will need to clean up manually, and that will continue to incur charges from your cloud provider.

### Verify that deletion is complete

After the cluster reports as deleted in the Cloud Console, verify that no managed resources remain in your Azure subscription. Review the resource groups in the subscription for resources associated with the cluster. If resources remain, contact your Cockroach Labs account team before removing them manually.

### Reuse the Azure subscription

Before you reuse the Azure subscription for a subsequent BYOC deployment, verify that deletion of the previous cluster is complete and contact your Cockroach Labs account team to confirm that the subscription is ready for reuse.

## Next steps

* [Connect to your cluster](https://docs.cockroachlabs.com/docs/continuum/connect-to-a-cluster.md)
* [Manage your cluster using the Cloud API](https://docs.cockroachlabs.com/docs/continuum/cloud-api.md)
* [Prepare your deployment for production](https://docs.cockroachlabs.com/docs/cockroachcloud/production-checklist.md)
