Prepare a CockroachDB Cloud BYOC Deployment

On this page

CockroachDB Cloud supports a "bring your own cloud" (BYOC) deployment model, where a CockroachDB Cloud Advanced deployment is hosted in your own account. This model allows you to take more control of security and take advantage of existing cloud service credits or discounts.

This page describes how to prepare a cloud service account to host a BYOC CockroachDB Cloud Advanced deployment in Microsoft Azure.

Shared responsibility model for BYOC

In any CockroachDB Cloud deployment, responsibility for a successful and healthy deployment is split between you and Cockroach Labs. In a BYOC deployment, all of the CockroachDB Cloud infrastructure except the control plane lives in an account under your control which involves additional responsibilities under the shared model.

The following table describes the split of responsibilities between you and Cockroach Labs in the shared responsibility model for BYOC:

Prerequisites

• Create a CockroachDB Cloud organization if you do not already have one.

• The BYOC deployment option is not available by default and must be requested. Reach out to your account team to have BYOC enabled for your Cloud organization.

• Cluster creation and management for BYOC deployments is handled using the Cloud API. Create a service account and API key if you do not have one.

• Review the Plan a CockroachDB Advanced Cluster documentation to plan your cluster sizing and resource allocation.

Step 1. Create a new Azure subscription

Provision a new Azure subscription with no existing infrastructure, dedicated to your CockroachDB Cloud deployment. This subscription can be reused for multiple CockroachDB clusters.

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 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 content on behalf of your organization.

Once the Cockroach Labs App Registration has been granted admin content 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

Register the following resource providers in the Azure subscription:

• Microsoft.ContainerService
• Microsoft.ManagedIdentity
• Microsoft.Network
• Microsoft.Quota
• Microsoft.Storage

Step 4. Create the CockroachDB Cloud cluster

In BYOC deployments, CockroachDB clusters are deployed with the Cloud API and must use the Advanced plan. Follow the API documentation to create a CockroachDB Cloud Advanced cluster.

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

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{
    "name":"byoc-azure-cluster-1",
    "provider": "AZURE",
    "plan": "ADVANCED",
    "spec": {
      "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
        }
      }
    }
  }'

Next steps

• Connect to your cluster
• Manage your cluster using the Cloud API
• Prepare your deployment for production