From 0a59856bde1deef4ef2eae3faa54a6c3c4c4ba37 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Tue, 14 Apr 2026 17:09:48 -0400 Subject: [PATCH 01/12] BYOC public preview docs set --- src/current/_data/redirects.yml | 3 + .../byoc/byoc-common-prerequisites.md | 7 + .../byoc/byoc-responsibility-model.md | 13 + .../v26.1/sidebar-data/cloud-deployments.json | 29 +- .../cockroachcloud/byoc-aws-deployment.md | 255 +++++++++++++++++ ...deployment.md => byoc-azure-deployment.md} | 26 +- .../cockroachcloud/byoc-gcp-deployment.md | 262 ++++++++++++++++++ src/current/cockroachcloud/byoc-overview.md | 8 + 8 files changed, 578 insertions(+), 25 deletions(-) create mode 100644 src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md create mode 100644 src/current/_includes/cockroachcloud/byoc/byoc-responsibility-model.md create mode 100644 src/current/cockroachcloud/byoc-aws-deployment.md rename src/current/cockroachcloud/{byoc-deployment.md => byoc-azure-deployment.md} (79%) create mode 100644 src/current/cockroachcloud/byoc-gcp-deployment.md create mode 100644 src/current/cockroachcloud/byoc-overview.md diff --git a/src/current/_data/redirects.yml b/src/current/_data/redirects.yml index 28c4f96b318..9b664212ea2 100644 --- a/src/current/_data/redirects.yml +++ b/src/current/_data/redirects.yml @@ -1158,3 +1158,6 @@ - destination: update.md sources: ['update-data.md'] versions: ['v26.1', 'v26.2'] + +- destination: cockroachcloud/byoc-azure-deployment.md + sources: ['cockroachcloud/byoc-deployment.md'] diff --git a/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md b/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md new file mode 100644 index 00000000000..d2ba4dec370 --- /dev/null +++ b/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md @@ -0,0 +1,7 @@ +- [Create a CockroachDB {{ site.data.products.cloud }} organization]({% link cockroachcloud/create-an-account.md %}) 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 express interest in BYOC. + +- Review the [Plan a CockroachDB {{ site.data.products.advanced }} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation to plan your cluster sizing and resource allocation. + +- Review cloud service regions supported by [CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }}]({% link cockroachcloud/regions.md %}?filters=advanced). \ No newline at end of file diff --git a/src/current/_includes/cockroachcloud/byoc/byoc-responsibility-model.md b/src/current/_includes/cockroachcloud/byoc/byoc-responsibility-model.md new file mode 100644 index 00000000000..7f591781753 --- /dev/null +++ b/src/current/_includes/cockroachcloud/byoc/byoc-responsibility-model.md @@ -0,0 +1,13 @@ +In any CockroachDB {{ site.data.products.cloud }} deployment, responsibility for a successful and healthy deployment is [split between you and Cockroach Labs]({% link cockroachcloud/production-checklist.md %}). In a BYOC deployment, all of the [CockroachDB {{ site.data.products.cloud }} infrastructure]({% link cockroachcloud/plan-your-cluster-advanced.md %}#advanced-cluster-architecture) except the control plane lives in an account under your control, which means that you incur 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: + +Area | Cockroach Labs responsibility | Customer responsibility +:----------:|:-----------------------------:|:----------------------: +Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible +Deployments | Automate cluster provisioning and scaling, provide hardware best practices | Provision new cloud service accounts and grant IAM permissions for Cockroach Labs to create and manage clusters +Upgrades | Provide automatic minor/patch upgrades and major upgrade automation via Terraform, APIs, or the {{ site.data.products.cloud }} Console | Initiate [major version upgrades]({% link cockroachcloud/upgrade-cockroach-version.md %}), [set maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) if applicable +Workload | Troubleshoot problems as they pertain to cluster availability | [Size clusters]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) to manage workload requirements, [tune performance]({% link {{ site.versions["stable"] }}/performance-recipes.md %}), and adjust schema designs with support from Cockroach Labs +Backups | Initialize a default backup schedule and write to customer-owned Cloud storage, ensure backup jobs run successfully | Configure a backup schedule as needed to meet RPO/RTO requirements +Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available and appropriate IAM permissions are maintained at all times +Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockroachcloud/costs.md %}) at the per-minute level | Negotiate with cloud service provider, manage infrastructure spend and discounts \ No newline at end of file diff --git a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json index 3114b07c714..49c0923e4fe 100644 --- a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json @@ -21,9 +21,32 @@ ] }, { - "title": "BYOC Deployments (Preview)", - "urls": [ - "/cockroachcloud/byoc-deployment.html" + "title": "Bring-Your-Own-Cloud (BYOC)", + "items": [ + { + "title": "BYOC Overview", + "urls": [ + "/cockroachcloud/byoc-overview.html" + ] + }, + { + "title": "Deploy BYOC in AWS", + "urls": [ + "/cockroachcloud/byoc-aws-deployment.html" + ] + }, + { + "title": "Deploy BYOC in Azure", + "urls": [ + "/cockroachcloud/byoc-azure-deployment.html" + ] + }, + { + "title": "Deploy BYOC in GCP", + "urls": [ + "/cockroachcloud/byoc-gcp-deployment.html" + ] + } ] }, { diff --git a/src/current/cockroachcloud/byoc-aws-deployment.md b/src/current/cockroachcloud/byoc-aws-deployment.md new file mode 100644 index 00000000000..07ead8f84b1 --- /dev/null +++ b/src/current/cockroachcloud/byoc-aws-deployment.md @@ -0,0 +1,255 @@ +--- +title: Prepare a CockroachDB Cloud BYOC Deployment in AWS +summary: Prepare a cloud service account to self-host a CockroachDB Cloud deployment with the BYOC model +toc: true +keywords: deployment, byoc +--- + +CockroachDB {{ site.data.products.cloud }} supports a "bring your own cloud" (BYOC) deployment model, where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own account rather than in an account managed by Cockroach Labs. This model allows you to take more control of security and take advantage of existing cloud service credits or discounts. + +{{site.data.alerts.callout_info}} +The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). +{{site.data.alerts.end}} + +This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Microsoft Azure. + +## Shared responsibility model for BYOC + +{% include cockroachcloud/byoc/byoc-responsibility-model.md %} + +## Prerequisites + +{% include cockroachcloud/byoc/byoc-common-prerequisites.md %} + +## Step 1. Create a new AWS account + +Provision a new AWS account 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 account, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This account can be reused for multiple CockroachDB clusters. + +## Step 2. Configure intermediate IAM role for Cockroach Labs + +Cockroach Labs uses an intermediate IAM role to provision and manage resources in your AWS account. In this step, you will use your CockroachDB {{ site.data.products.cloud }} organization label to determine what the ARN will be for later use. + +You can collect the org label for your CockroachDB {{ site.data.products.cloud }} organization in the Console or by using the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) with a `GET` request similar to the following example: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/organization \ + --header 'Authorization: Bearer {secret_key}' +~~~ + +The ARN of this dedicated intermediate service account follows the following schema: + +~~~ text +arn:aws:iam::721449411130:user/byoc/CockroachDB-Cloud-managed-BYOC_ +~~~ + +For example, if your organization’s org label is `org-32222` then record your ARN as follows: +~~~ +arn:aws:iam::721449411130:user/byoc/CockroachDB-Cloud-managed-BYOC_org-32222 +~~~ + +## Step 3. Create IAM role for Cockroach Labs access + +Follow these steps to create the IAM role and grant the necessary permissions: + +1. In the AWS IAM console, do the following: + 1. Create a new role. This name is arbitrary, in these instructions the role is named `CRLBYOCAdmin`. + 2. Use the following trust relationship policy for the new role, using the ARN collected in the previous step: + {% include_cached copy-clipboard.html %} + ~~~ json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": + }, + "Action": "sts:AssumeRole" + } + ] + } + ~~~ + 3. Apply an IAM policy to the intermediate role granting the following list of permissions: + {% include_cached copy-clipboard.html %} + ~~~ text + // Auto Scaling permissions + "autoscaling:CreateAutoScalingGroup", + "autoscaling:DeleteAutoScalingGroup", + "autoscaling:Describe*", + "autoscaling:Get*", + "autoscaling:SetInstanceProtection", + "autoscaling:TerminateInstanceInAutoScalingGroup", + "autoscaling:UpdateAutoScalingGroup", + + // EC2 permissions + "ec2:AcceptVpcEndpointConnections", + "ec2:AcceptVpcPeeringConnection", + "ec2:AssociateRouteTable", + "ec2:AssociateVpcCidrBlock", + "ec2:AttachInternetGateway", + "ec2:AuthorizeSecurityGroupEgress", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:CreateFlowLogs", + "ec2:CreateInternetGateway", + "ec2:CreateLaunchTemplate", + "ec2:CreateLaunchTemplateVersion", + "ec2:CreateNatGateway", + "ec2:CreateRoute", + "ec2:CreateRouteTable", + "ec2:CreateSecurityGroup", + "ec2:CreateSubnet", + "ec2:CreateTags", + "ec2:CreateVpc", + "ec2:CreateVpcEndpoint", + "ec2:CreateVpcPeeringConnection", + "ec2:DeleteFlowLogs", + "ec2:DeleteInternetGateway", + "ec2:DeleteLaunchTemplate", + "ec2:DeleteLaunchTemplateVersions", + "ec2:DeleteNatGateway", + "ec2:DeleteRoute", + "ec2:DeleteRouteTable", + "ec2:DeleteSecurityGroup", + "ec2:DeleteSubnet", + "ec2:DeleteVpc", + "ec2:DeleteVpcEndpoints", + "ec2:DeleteVpcEndpointServiceConfigurations", + "ec2:DeleteVpcPeeringConnection", + "ec2:Describe*", + "ec2:DetachInternetGateway", + "ec2:DisableEbsEncryptionByDefault", + "ec2:DisassociateRouteTable", + "ec2:DisassociateVpcCidrBlock", + "ec2:EnableEbsEncryptionByDefault", + "ec2:Get*", + "ec2:List*", + "ec2:ModifySubnetAttribute", + "ec2:ModifyVolume", + "ec2:ModifyVpcAttribute", + "ec2:ModifyVpcEndpointServiceConfiguration", + "ec2:ModifyVpcEndpointServicePermissions", + "ec2:RejectVpcEndpointConnections", + "ec2:RevokeSecurityGroupEgress", + "ec2:RevokeSecurityGroupIngress", + "ec2:RunInstances", + "ec2:StartVpcEndpointServicePrivateDnsVerification", + + // EKS permissions + "eks:AssociateAccessPolicy", + "eks:CreateAccessEntry", + "eks:CreateCluster", + "eks:DeleteAccessEntry", + "eks:DeleteCluster", + "eks:Describe*", + "eks:DisassociateAccessPolicy", + "eks:List*", + "eks:UpdateAccessEntry", + "eks:UpdateClusterConfig", + "eks:UpdateClusterVersion", + + // Elastic Load Balancing permissions + "elasticloadbalancing:Describe*", + + // IAM permissions + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:AttachUserPolicy", + "iam:CreateAccessKey", + "iam:CreateAccountAlias", + "iam:CreateInstanceProfile", + "iam:CreateOpenIDConnectProvider", + "iam:CreatePolicy", + "iam:CreateRole", + "iam:CreateServiceLinkedRole", + "iam:CreateUser", + "iam:DeleteAccessKey", + "iam:DeleteInstanceProfile", + "iam:DeleteLoginProfile", + "iam:DeleteOpenIDConnectProvider", + "iam:DeletePolicy", + "iam:DeletePolicyVersion", + "iam:DeleteRole", + "iam:DeleteRolePolicy", + "iam:DeleteUser", + "iam:DeleteUserPolicy", + "iam:DetachRolePolicy", + "iam:DetachUserPolicy", + "iam:Get*", + "iam:List*", + "iam:PassRole", + "iam:PutRolePolicy", + "iam:PutUserPolicy", + "iam:RemoveRoleFromInstanceProfile", + "iam:TagPolicy", + + // Kafka permissions + "kafka:List*", + + // CloudWatch Logs permissions + "logs:CreateLogGroup", + "logs:DeleteLogGroup", + "logs:Describe*", + "logs:Get*", + "logs:List*", + "logs:PutRetentionPolicy", + "logs:PutSubscriptionFilter", + + // S3 permissions + "s3:CreateBucket", + "s3:DeleteBucketPolicy", + "s3:Describe*", + "s3:Get*", + "s3:List*", + "s3:PutBucketTagging", + "s3:PutEncryptionConfiguration", + "s3:PutLifecycleConfiguration", + + // Service Quotas permissions + "servicequotas:GetServiceQuota", + ~~~ + +## Step 4. (Optional) Enable additional regions + +If you plan to use non-default AWS regions, you must manually enable them in the AWS Management Console. You must also activate [global STS tokens](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_region-endpoints.html) for these regions to work with CockroachDB. + +You may also need to adjust quotas for vCPU and EBS disk storage for the regions that you plan to create your cluster in. + +## 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). + +The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `centralus` region, specifying the `subscription-id` and `customer-tenant-id` associated with your Azure subscription: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request POST \ + --url https://cockroachlabs.cloud/api/v1/clusters \ + --header 'Authorization: Bearer {secret_key}' \ + --json '{ + "name": "byoc-aws-cluster-1", + "provider": "AWS", + "spec": { + "dedicated": { + "hardware": { + "machine_spec": {"num_virtual_cpus": 4}, + "storage_gib": 16 + }, + "region_nodes": {"us-east-2": 3} + }, + "plan": "ADVANCED", + "customer_cloud_account": { + "aws": { + "arn": "arn:aws:iam:::role/CRLBYOCAdmin" + } + } + } + }' +~~~ + +## Next steps + +- [Connect to your cluster]({% link cockroachcloud/connect-to-an-advanced-cluster.md %}) +- [Manage your cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) +- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) \ No newline at end of file diff --git a/src/current/cockroachcloud/byoc-deployment.md b/src/current/cockroachcloud/byoc-azure-deployment.md similarity index 79% rename from src/current/cockroachcloud/byoc-deployment.md rename to src/current/cockroachcloud/byoc-azure-deployment.md index b5843056e16..1a8be547442 100644 --- a/src/current/cockroachcloud/byoc-deployment.md +++ b/src/current/cockroachcloud/byoc-azure-deployment.md @@ -1,5 +1,5 @@ --- -title: Prepare a CockroachDB Cloud BYOC Deployment +title: Prepare a CockroachDB Cloud BYOC Deployment in Azure summary: Prepare a cloud service account to self-host a CockroachDB Cloud deployment with the BYOC model toc: true keywords: deployment, byoc @@ -8,36 +8,18 @@ keywords: deployment, byoc CockroachDB {{ site.data.products.cloud }} supports a "bring your own cloud" (BYOC) deployment model, where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own account rather than in an account managed by Cockroach Labs. This model allows you to take more control of security and take advantage of existing cloud service credits or discounts. {{site.data.alerts.callout_info}} -The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). BYOC deployments are only supported in Microsoft Azure. +The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). {{site.data.alerts.end}} This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Microsoft Azure. ## Shared responsibility model for BYOC -In any CockroachDB {{ site.data.products.cloud }} deployment, responsibility for a successful and healthy deployment is [split between you and Cockroach Labs]({% link cockroachcloud/production-checklist.md %}). In a BYOC deployment, all of the [CockroachDB {{ site.data.products.cloud }} infrastructure]({% link cockroachcloud/plan-your-cluster-advanced.md %}#advanced-cluster-architecture) except the control plane lives in an account under your control, which means that you incur 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: - -Area | Cockroach Labs responsibility | Customer responsibility -:----------:|:-----------------------------:|:----------------------: -Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible -Deployments | Automate cluster provisioning and scaling, provide hardware best practices | Provision new cloud service accounts and grant IAM permissions for Cockroach Labs to create and manage clusters -Upgrades | Provide automatic minor/patch upgrades and major upgrade automation via Terraform, APIs, or the {{ site.data.products.cloud }} Console | Initiate [major version upgrades]({% link cockroachcloud/upgrade-cockroach-version.md %}), [set maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) if applicable -Workload | Troubleshoot problems as they pertain to cluster availability | [Size clusters]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) to manage workload requirements, [tune performance]({% link {{ site.versions["stable"] }}/performance-recipes.md %}), and adjust schema designs with support from Cockroach Labs -Backups | Initialize a default backup schedule and write to customer-owned Cloud storage, ensure backup jobs run successfully | Configure a backup schedule as needed to meet RPO/RTO requirements -Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available and appropriate IAM permissions are maintained at all times -Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockroachcloud/costs.md %}) at the per-minute level | Negotiate with cloud service provider, manage infrastructure spend and discounts +{% include cockroachcloud/byoc/byoc-responsibility-model.md %} ## Prerequisites -- [Create a CockroachDB {{ site.data.products.cloud }} organization]({% link cockroachcloud/create-an-account.md %}) 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 express interest in BYOC. - -- Cluster creation and management for BYOC deployments is handled using the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}). Create a service account and [API key]({% link cockroachcloud/managing-access.md %}#api-access) if you do not have one. - -- Review the [Plan a CockroachDB {{ site.data.products.advanced }} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation to plan your cluster sizing and resource allocation. +{% include cockroachcloud/byoc/byoc-common-prerequisites.md %} ## Step 1. Create a new Azure subscription diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md new file mode 100644 index 00000000000..1e052a445a5 --- /dev/null +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -0,0 +1,262 @@ +--- +title: Prepare a CockroachDB Cloud BYOC Deployment in GCP +summary: Prepare a cloud service account to self-host a CockroachDB Cloud deployment with the BYOC model +toc: true +keywords: deployment, byoc +--- + +CockroachDB {{ site.data.products.cloud }} supports a "bring your own cloud" (BYOC) deployment model, where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own account rather than in an account managed by Cockroach Labs. This model allows you to take more control of security and take advantage of existing cloud service credits or discounts. + +{{site.data.alerts.callout_info}} +The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). +{{site.data.alerts.end}} + +This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in GCP. + +## Shared responsibility model for BYOC + +{% include cockroachcloud/byoc/byoc-responsibility-model.md %} + +## Prerequisites + +{% include cockroachcloud/byoc/byoc-common-prerequisites.md %} + +## Step 1. Create a new GCP project + +Provision a fresh GCP project with no existing infrastructure, dedicated to your Cockroach {{ site.data.products.cloud }} deployment. The project configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this project, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This project can be reused for multiple CockroachDB clusters. + +The following requirements apply to the GCP project used for your BYOC deployment: +- The project ID **must not** begin with the reserved prefix `crl-`. +- [Enable](https://docs.cloud.google.com/endpoints/docs/openapi/enable-api) the Service Usage API and the Cloud Resource Manager APIs for this project. Cockroach Labs will enable additional APIs as needed, but these two must be initialized first. + +## Step 2. Configure an intermediary service account for Cockroach Labs + +Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. + + +Cockroach Labs uses an intermediate IAM role to provision and manage resources in your AWS account. In this step, you will use your CockroachDB {{ site.data.products.cloud }} organization label to determine what the ARN will be for later use. + +You can collect the org label for your CockroachDB {{ site.data.products.cloud }} organization in the Console or by using the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) with a `GET` request similar to the following example: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/organization \ + --header 'Authorization: Bearer {secret_key}' +~~~ + +The ARN of this dedicated intermediate service account follows the following schema: + +~~~ text +arn:aws:iam::721449411130:user/byoc/CockroachDB-Cloud-managed-BYOC_ +~~~ + +For example, if your organization’s org label is `org-32222` then record your ARN as follows: +~~~ +arn:aws:iam::721449411130:user/byoc/CockroachDB-Cloud-managed-BYOC_org-32222 +~~~ + +## Step 3. Create IAM role for Cockroach Labs access + +Follow these steps to create the IAM role and grant the necessary permissions: + +1. In the AWS IAM console, do the following: + 1. Create a new role. This name is arbitrary, in these instructions the role is named `CRLBYOCAdmin`. + 2. Use the following trust relationship policy for the new role, using the ARN collected in the previous step: + {% include_cached copy-clipboard.html %} + ~~~ json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": + }, + "Action": "sts:AssumeRole" + } + ] + } + ~~~ + 3. Apply an IAM policy to the intermediate role granting the following list of permissions: + {% include_cached copy-clipboard.html %} + ~~~ text + // Auto Scaling permissions + "autoscaling:CreateAutoScalingGroup", + "autoscaling:DeleteAutoScalingGroup", + "autoscaling:Describe*", + "autoscaling:Get*", + "autoscaling:SetInstanceProtection", + "autoscaling:TerminateInstanceInAutoScalingGroup", + "autoscaling:UpdateAutoScalingGroup", + + // EC2 permissions + "ec2:AcceptVpcEndpointConnections", + "ec2:AcceptVpcPeeringConnection", + "ec2:AssociateRouteTable", + "ec2:AssociateVpcCidrBlock", + "ec2:AttachInternetGateway", + "ec2:AuthorizeSecurityGroupEgress", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:CreateFlowLogs", + "ec2:CreateInternetGateway", + "ec2:CreateLaunchTemplate", + "ec2:CreateLaunchTemplateVersion", + "ec2:CreateNatGateway", + "ec2:CreateRoute", + "ec2:CreateRouteTable", + "ec2:CreateSecurityGroup", + "ec2:CreateSubnet", + "ec2:CreateTags", + "ec2:CreateVpc", + "ec2:CreateVpcEndpoint", + "ec2:CreateVpcPeeringConnection", + "ec2:DeleteFlowLogs", + "ec2:DeleteInternetGateway", + "ec2:DeleteLaunchTemplate", + "ec2:DeleteLaunchTemplateVersions", + "ec2:DeleteNatGateway", + "ec2:DeleteRoute", + "ec2:DeleteRouteTable", + "ec2:DeleteSecurityGroup", + "ec2:DeleteSubnet", + "ec2:DeleteVpc", + "ec2:DeleteVpcEndpoints", + "ec2:DeleteVpcEndpointServiceConfigurations", + "ec2:DeleteVpcPeeringConnection", + "ec2:Describe*", + "ec2:DetachInternetGateway", + "ec2:DisableEbsEncryptionByDefault", + "ec2:DisassociateRouteTable", + "ec2:DisassociateVpcCidrBlock", + "ec2:EnableEbsEncryptionByDefault", + "ec2:Get*", + "ec2:List*", + "ec2:ModifySubnetAttribute", + "ec2:ModifyVolume", + "ec2:ModifyVpcAttribute", + "ec2:ModifyVpcEndpointServiceConfiguration", + "ec2:ModifyVpcEndpointServicePermissions", + "ec2:RejectVpcEndpointConnections", + "ec2:RevokeSecurityGroupEgress", + "ec2:RevokeSecurityGroupIngress", + "ec2:RunInstances", + "ec2:StartVpcEndpointServicePrivateDnsVerification", + + // EKS permissions + "eks:AssociateAccessPolicy", + "eks:CreateAccessEntry", + "eks:CreateCluster", + "eks:DeleteAccessEntry", + "eks:DeleteCluster", + "eks:Describe*", + "eks:DisassociateAccessPolicy", + "eks:List*", + "eks:UpdateAccessEntry", + "eks:UpdateClusterConfig", + "eks:UpdateClusterVersion", + + // Elastic Load Balancing permissions + "elasticloadbalancing:Describe*", + + // IAM permissions + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:AttachUserPolicy", + "iam:CreateAccessKey", + "iam:CreateAccountAlias", + "iam:CreateInstanceProfile", + "iam:CreateOpenIDConnectProvider", + "iam:CreatePolicy", + "iam:CreateRole", + "iam:CreateServiceLinkedRole", + "iam:CreateUser", + "iam:DeleteAccessKey", + "iam:DeleteInstanceProfile", + "iam:DeleteLoginProfile", + "iam:DeleteOpenIDConnectProvider", + "iam:DeletePolicy", + "iam:DeletePolicyVersion", + "iam:DeleteRole", + "iam:DeleteRolePolicy", + "iam:DeleteUser", + "iam:DeleteUserPolicy", + "iam:DetachRolePolicy", + "iam:DetachUserPolicy", + "iam:Get*", + "iam:List*", + "iam:PassRole", + "iam:PutRolePolicy", + "iam:PutUserPolicy", + "iam:RemoveRoleFromInstanceProfile", + "iam:TagPolicy", + + // Kafka permissions + "kafka:List*", + + // CloudWatch Logs permissions + "logs:CreateLogGroup", + "logs:DeleteLogGroup", + "logs:Describe*", + "logs:Get*", + "logs:List*", + "logs:PutRetentionPolicy", + "logs:PutSubscriptionFilter", + + // S3 permissions + "s3:CreateBucket", + "s3:DeleteBucketPolicy", + "s3:Describe*", + "s3:Get*", + "s3:List*", + "s3:PutBucketTagging", + "s3:PutEncryptionConfiguration", + "s3:PutLifecycleConfiguration", + + // Service Quotas permissions + "servicequotas:GetServiceQuota", + ~~~ + +## Step 4. (Optional) Enable additional regions + +If you plan to use non-default AWS regions, you must manually enable them in the AWS Management Console. You must also activate [global STS tokens](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_region-endpoints.html) for these regions to work with CockroachDB. + +You may also need to adjust quotas for vCPU and EBS disk storage for the regions that you plan to create your cluster in. + +## 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). + +The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `centralus` region, specifying the `subscription-id` and `customer-tenant-id` associated with your Azure subscription: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request POST \ + --url https://cockroachlabs.cloud/api/v1/clusters \ + --header 'Authorization: Bearer {secret_key}' \ + --json '{ + "name": "byoc-aws-cluster-1", + "provider": "AWS", + "spec": { + "dedicated": { + "hardware": { + "machine_spec": {"num_virtual_cpus": 4}, + "storage_gib": 16 + }, + "region_nodes": {"us-east-2": 3} + }, + "plan": "ADVANCED", + "customer_cloud_account": { + "aws": { + "arn": "arn:aws:iam:::role/CRLBYOCAdmin" + } + } + } + }' +~~~ + +## Next steps + +- [Connect to your cluster]({% link cockroachcloud/connect-to-an-advanced-cluster.md %}) +- [Manage your cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) +- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) \ No newline at end of file diff --git a/src/current/cockroachcloud/byoc-overview.md b/src/current/cockroachcloud/byoc-overview.md new file mode 100644 index 00000000000..f5ff2f98eae --- /dev/null +++ b/src/current/cockroachcloud/byoc-overview.md @@ -0,0 +1,8 @@ +--- +title: CockroachDB BYOC Overview +summary: Learn about the Bring-Your-Own-Cloud deployment option for CockroachDB +toc: true +keywords: deployment, byoc +--- + +TODO \ No newline at end of file From f978b9b247ee205f9ba7bba035c35500ac1b4017 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Thu, 16 Apr 2026 15:35:56 -0400 Subject: [PATCH 02/12] Finish instructions --- .../cockroachcloud/byoc-aws-deployment.md | 26 +- .../cockroachcloud/byoc-azure-deployment.md | 2 +- .../cockroachcloud/byoc-gcp-deployment.md | 251 +++--------------- 3 files changed, 57 insertions(+), 222 deletions(-) diff --git a/src/current/cockroachcloud/byoc-aws-deployment.md b/src/current/cockroachcloud/byoc-aws-deployment.md index 07ead8f84b1..6f323e9114d 100644 --- a/src/current/cockroachcloud/byoc-aws-deployment.md +++ b/src/current/cockroachcloud/byoc-aws-deployment.md @@ -25,11 +25,11 @@ This page describes how to prepare a cloud service account to host a BYOC deploy Provision a new AWS account 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 account, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This account can be reused for multiple CockroachDB clusters. -## Step 2. Configure intermediate IAM role for Cockroach Labs +## Step 2. Record your intermediate role's ARN -Cockroach Labs uses an intermediate IAM role to provision and manage resources in your AWS account. In this step, you will use your CockroachDB {{ site.data.products.cloud }} organization label to determine what the ARN will be for later use. +Cockroach Labs uses an intermediate **IAM role** to provision and manage resources in your AWS account. In this step, use your CockroachDB {{ site.data.products.cloud }} organization label to determine the **Amazon Resource Name (ARN)** of this IAM role. -You can collect the org label for your CockroachDB {{ site.data.products.cloud }} organization in the Console or by using the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) with a `GET` request similar to the following example: +Find your org label in the CockroachDB {{ site.data.products.cloud }} Console or by using the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) with a `GET` request similar to the following example: {% include_cached copy-clipboard.html %} ~~~ shell @@ -38,24 +38,24 @@ curl --request GET \ --header 'Authorization: Bearer {secret_key}' ~~~ -The ARN of this dedicated intermediate service account follows the following schema: +Record the ARN of your organization's intermediate IAM role using the following schema: ~~~ text -arn:aws:iam::721449411130:user/byoc/CockroachDB-Cloud-managed-BYOC_ +arn:aws:iam:::user/byoc/CockroachDB-Cloud-managed-BYOC_ ~~~ For example, if your organization’s org label is `org-32222` then record your ARN as follows: ~~~ -arn:aws:iam::721449411130:user/byoc/CockroachDB-Cloud-managed-BYOC_org-32222 +arn:aws:iam:::user/byoc/CockroachDB-Cloud-managed-BYOC_org-32222 ~~~ ## Step 3. Create IAM role for Cockroach Labs access -Follow these steps to create the IAM role and grant the necessary permissions: +Follow these steps to create the intermediate IAM role and grant the necessary permissions: -1. In the AWS IAM console, do the following: - 1. Create a new role. This name is arbitrary, in these instructions the role is named `CRLBYOCAdmin`. - 2. Use the following trust relationship policy for the new role, using the ARN collected in the previous step: +1. Open the AWS IAM console. +1. Create a new role. This name is arbitrary, in these instructions the role is named `CRLBYOCAdmin`. +1. Use the following trust relationship policy for the new role, using the ARN collected in the previous step: {% include_cached copy-clipboard.html %} ~~~ json { @@ -71,7 +71,7 @@ Follow these steps to create the IAM role and grant the necessary permissions: ] } ~~~ - 3. Apply an IAM policy to the intermediate role granting the following list of permissions: +1. Apply an IAM policy to the intermediate role granting the following list of permissions: {% include_cached copy-clipboard.html %} ~~~ text // Auto Scaling permissions @@ -220,7 +220,7 @@ You may also need to adjust quotas for vCPU and EBS disk storage for the regions 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). -The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `centralus` region, specifying the `subscription-id` and `customer-tenant-id` associated with your Azure subscription: +The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `us-east-2` region, specifying the ARN associated with your intermediate IAM role: {% include_cached copy-clipboard.html %} ~~~ shell @@ -241,7 +241,7 @@ curl --request POST \ "plan": "ADVANCED", "customer_cloud_account": { "aws": { - "arn": "arn:aws:iam:::role/CRLBYOCAdmin" + "arn": "arn:aws:iam:::user/byoc/CockroachDB-Cloud-managed-BYOC_" } } } diff --git a/src/current/cockroachcloud/byoc-azure-deployment.md b/src/current/cockroachcloud/byoc-azure-deployment.md index 1a8be547442..0c2a458fd90 100644 --- a/src/current/cockroachcloud/byoc-azure-deployment.md +++ b/src/current/cockroachcloud/byoc-azure-deployment.md @@ -23,7 +23,7 @@ This page describes how to prepare a cloud service account to host a BYOC deploy ## Step 1. Create a new Azure subscription -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. +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 }} diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md index 1e052a445a5..b97f2cd49f7 100644 --- a/src/current/cockroachcloud/byoc-gcp-deployment.md +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -23,236 +23,71 @@ This page describes how to prepare a cloud service account to host a BYOC deploy ## Step 1. Create a new GCP project -Provision a fresh GCP project with no existing infrastructure, dedicated to your Cockroach {{ site.data.products.cloud }} deployment. The project configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this project, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This project can be reused for multiple CockroachDB clusters. +Provision a fresh **GCP project** with no existing infrastructure, dedicated to your Cockroach {{ site.data.products.cloud }} deployment. The project configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this project, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This project can be reused for multiple CockroachDB clusters. The following requirements apply to the GCP project used for your BYOC deployment: - The project ID **must not** begin with the reserved prefix `crl-`. - [Enable](https://docs.cloud.google.com/endpoints/docs/openapi/enable-api) the Service Usage API and the Cloud Resource Manager APIs for this project. Cockroach Labs will enable additional APIs as needed, but these two must be initialized first. -## Step 2. Configure an intermediary service account for Cockroach Labs +## Step 2. Configure an intermediate service account for Cockroach Labs -Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. +Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. +Follow these steps to create the intermediate service account: -Cockroach Labs uses an intermediate IAM role to provision and manage resources in your AWS account. In this step, you will use your CockroachDB {{ site.data.products.cloud }} organization label to determine what the ARN will be for later use. +1. Open the GCP IAM Console. +2. Create a new service account. The name is arbitrary but be sure to note down the email address of the account. +3. Grant the following IAM roles to the service account: + - `Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)` + - `Compute Network Admin (roles/compute.networkAdmin)` + - `Compute Security Admin (roles/compute.securityAdmin)` + - `Kubernetes Engine Admin (roles/container.admin)` + - `Role Administrator (roles/iam.roleAdmin)` + - `Service Account Admin (roles/iam.serviceAccountAdmin)` + - `Service Account Key Admin (roles/iam.serviceAccountKeyAdmin)` + - `Service Account Token Creator (roles/iam.serviceAccountTokenCreator)` + - `Service Account User (roles/iam.serviceAccountUser)` + - `Logs Configuration Writer (roles/logging.configWriter)` + - `Project IAM Admin (roles/resourcemanager.projectIamAdmin)` + - `Project Mover (roles/resourcemanager.projectMover)` + - `Service Usage Admin (roles/serviceusage.serviceUsageAdmin)` + - `Storage Admin (roles/storage.admin)` -You can collect the org label for your CockroachDB {{ site.data.products.cloud }} organization in the Console or by using the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) with a `GET` request similar to the following example: -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request GET \ - --url https://cockroachlabs.cloud/api/v1/organization \ - --header 'Authorization: Bearer {secret_key}' -~~~ - -The ARN of this dedicated intermediate service account follows the following schema: - -~~~ text -arn:aws:iam::721449411130:user/byoc/CockroachDB-Cloud-managed-BYOC_ -~~~ - -For example, if your organization’s org label is `org-32222` then record your ARN as follows: -~~~ -arn:aws:iam::721449411130:user/byoc/CockroachDB-Cloud-managed-BYOC_org-32222 -~~~ - -## Step 3. Create IAM role for Cockroach Labs access - -Follow these steps to create the IAM role and grant the necessary permissions: - -1. In the AWS IAM console, do the following: - 1. Create a new role. This name is arbitrary, in these instructions the role is named `CRLBYOCAdmin`. - 2. Use the following trust relationship policy for the new role, using the ARN collected in the previous step: - {% include_cached copy-clipboard.html %} - ~~~ json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "AWS": - }, - "Action": "sts:AssumeRole" - } - ] - } - ~~~ - 3. Apply an IAM policy to the intermediate role granting the following list of permissions: - {% include_cached copy-clipboard.html %} - ~~~ text - // Auto Scaling permissions - "autoscaling:CreateAutoScalingGroup", - "autoscaling:DeleteAutoScalingGroup", - "autoscaling:Describe*", - "autoscaling:Get*", - "autoscaling:SetInstanceProtection", - "autoscaling:TerminateInstanceInAutoScalingGroup", - "autoscaling:UpdateAutoScalingGroup", - - // EC2 permissions - "ec2:AcceptVpcEndpointConnections", - "ec2:AcceptVpcPeeringConnection", - "ec2:AssociateRouteTable", - "ec2:AssociateVpcCidrBlock", - "ec2:AttachInternetGateway", - "ec2:AuthorizeSecurityGroupEgress", - "ec2:AuthorizeSecurityGroupIngress", - "ec2:CreateFlowLogs", - "ec2:CreateInternetGateway", - "ec2:CreateLaunchTemplate", - "ec2:CreateLaunchTemplateVersion", - "ec2:CreateNatGateway", - "ec2:CreateRoute", - "ec2:CreateRouteTable", - "ec2:CreateSecurityGroup", - "ec2:CreateSubnet", - "ec2:CreateTags", - "ec2:CreateVpc", - "ec2:CreateVpcEndpoint", - "ec2:CreateVpcPeeringConnection", - "ec2:DeleteFlowLogs", - "ec2:DeleteInternetGateway", - "ec2:DeleteLaunchTemplate", - "ec2:DeleteLaunchTemplateVersions", - "ec2:DeleteNatGateway", - "ec2:DeleteRoute", - "ec2:DeleteRouteTable", - "ec2:DeleteSecurityGroup", - "ec2:DeleteSubnet", - "ec2:DeleteVpc", - "ec2:DeleteVpcEndpoints", - "ec2:DeleteVpcEndpointServiceConfigurations", - "ec2:DeleteVpcPeeringConnection", - "ec2:Describe*", - "ec2:DetachInternetGateway", - "ec2:DisableEbsEncryptionByDefault", - "ec2:DisassociateRouteTable", - "ec2:DisassociateVpcCidrBlock", - "ec2:EnableEbsEncryptionByDefault", - "ec2:Get*", - "ec2:List*", - "ec2:ModifySubnetAttribute", - "ec2:ModifyVolume", - "ec2:ModifyVpcAttribute", - "ec2:ModifyVpcEndpointServiceConfiguration", - "ec2:ModifyVpcEndpointServicePermissions", - "ec2:RejectVpcEndpointConnections", - "ec2:RevokeSecurityGroupEgress", - "ec2:RevokeSecurityGroupIngress", - "ec2:RunInstances", - "ec2:StartVpcEndpointServicePrivateDnsVerification", - - // EKS permissions - "eks:AssociateAccessPolicy", - "eks:CreateAccessEntry", - "eks:CreateCluster", - "eks:DeleteAccessEntry", - "eks:DeleteCluster", - "eks:Describe*", - "eks:DisassociateAccessPolicy", - "eks:List*", - "eks:UpdateAccessEntry", - "eks:UpdateClusterConfig", - "eks:UpdateClusterVersion", - - // Elastic Load Balancing permissions - "elasticloadbalancing:Describe*", - - // IAM permissions - "iam:AddRoleToInstanceProfile", - "iam:AttachRolePolicy", - "iam:AttachUserPolicy", - "iam:CreateAccessKey", - "iam:CreateAccountAlias", - "iam:CreateInstanceProfile", - "iam:CreateOpenIDConnectProvider", - "iam:CreatePolicy", - "iam:CreateRole", - "iam:CreateServiceLinkedRole", - "iam:CreateUser", - "iam:DeleteAccessKey", - "iam:DeleteInstanceProfile", - "iam:DeleteLoginProfile", - "iam:DeleteOpenIDConnectProvider", - "iam:DeletePolicy", - "iam:DeletePolicyVersion", - "iam:DeleteRole", - "iam:DeleteRolePolicy", - "iam:DeleteUser", - "iam:DeleteUserPolicy", - "iam:DetachRolePolicy", - "iam:DetachUserPolicy", - "iam:Get*", - "iam:List*", - "iam:PassRole", - "iam:PutRolePolicy", - "iam:PutUserPolicy", - "iam:RemoveRoleFromInstanceProfile", - "iam:TagPolicy", - - // Kafka permissions - "kafka:List*", - - // CloudWatch Logs permissions - "logs:CreateLogGroup", - "logs:DeleteLogGroup", - "logs:Describe*", - "logs:Get*", - "logs:List*", - "logs:PutRetentionPolicy", - "logs:PutSubscriptionFilter", - - // S3 permissions - "s3:CreateBucket", - "s3:DeleteBucketPolicy", - "s3:Describe*", - "s3:Get*", - "s3:List*", - "s3:PutBucketTagging", - "s3:PutEncryptionConfiguration", - "s3:PutLifecycleConfiguration", - - // Service Quotas permissions - "servicequotas:GetServiceQuota", - ~~~ - -## Step 4. (Optional) Enable additional regions - -If you plan to use non-default AWS regions, you must manually enable them in the AWS Management Console. You must also activate [global STS tokens](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_region-endpoints.html) for these regions to work with CockroachDB. - -You may also need to adjust quotas for vCPU and EBS disk storage for the regions that you plan to create your cluster in. - -## Step 5. Create the CockroachDB {{ site.data.products.cloud }} cluster +## Step 3. 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). -The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `centralus` region, specifying the `subscription-id` and `customer-tenant-id` associated with your Azure subscription: +The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `us-east1` region, specifying the `service_account_email` associated with the intermediate service account you created: {% include_cached copy-clipboard.html %} ~~~ shell curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters \ - --header 'Authorization: Bearer {secret_key}' \ + --header "Authorization: Bearer {secret_key}" \ --json '{ - "name": "byoc-aws-cluster-1", - "provider": "AWS", - "spec": { - "dedicated": { - "hardware": { - "machine_spec": {"num_virtual_cpus": 4}, - "storage_gib": 16 - }, - "region_nodes": {"us-east-2": 3} - }, + "name": "byoc-gcp-cluster-1", "plan": "ADVANCED", - "customer_cloud_account": { - "aws": { - "arn": "arn:aws:iam:::role/CRLBYOCAdmin" + "provider": "GCP", + "spec": { + "customer_cloud_account": { + "gcp": { + "service_account_email": "{intermediate_service_account_email}" + } + }, + "dedicated": { + "hardware": { + "machine_spec": { + "num_virtual_cpus": 4 + }, + "storage_gib": 16 + }, + "region_nodes": { + "us-east1": 3 + } } } - } - }' + }' ~~~ ## Next steps From bfc592b517f8ea455681f8d35d85829966722d06 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Thu, 16 Apr 2026 17:34:13 -0400 Subject: [PATCH 03/12] Add UI instructions and overview --- .../byoc/byoc-common-prerequisites.md | 4 +++ .../byoc/byoc-responsibility-model.md | 13 -------- .../cockroachcloud/byoc-aws-deployment.md | 27 +++++++++++------ .../cockroachcloud/byoc-azure-deployment.md | 25 +++++++++++----- .../cockroachcloud/byoc-gcp-deployment.md | 27 +++++++++++------ src/current/cockroachcloud/byoc-overview.md | 30 ++++++++++++++++++- 6 files changed, 86 insertions(+), 40 deletions(-) delete mode 100644 src/current/_includes/cockroachcloud/byoc/byoc-responsibility-model.md diff --git a/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md b/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md index d2ba4dec370..524da04e2b2 100644 --- a/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md +++ b/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md @@ -1,5 +1,9 @@ +- Review the [shared responsibility model for BYOC]({% link cockroachcloud/byoc-overview.md %}#shared-responsibility-model-for-byoc). Make sure you understand and acknowledge the responsibilities you hold for management of your cloud infrastucture and the necessary permissions you must grant to Cockroach Labs. + - [Create a CockroachDB {{ site.data.products.cloud }} organization]({% link cockroachcloud/create-an-account.md %}) if you do not already have one. +- (Optional) Create an [API service account]({% link cockroachcloud/managing-access.md %}#create-api-keys) to use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) with your {{ site.data.products.cloud }} organization. + - The BYOC deployment option is not available by default and must be requested. Reach out to your account team to express interest in BYOC. - Review the [Plan a CockroachDB {{ site.data.products.advanced }} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation to plan your cluster sizing and resource allocation. diff --git a/src/current/_includes/cockroachcloud/byoc/byoc-responsibility-model.md b/src/current/_includes/cockroachcloud/byoc/byoc-responsibility-model.md deleted file mode 100644 index 7f591781753..00000000000 --- a/src/current/_includes/cockroachcloud/byoc/byoc-responsibility-model.md +++ /dev/null @@ -1,13 +0,0 @@ -In any CockroachDB {{ site.data.products.cloud }} deployment, responsibility for a successful and healthy deployment is [split between you and Cockroach Labs]({% link cockroachcloud/production-checklist.md %}). In a BYOC deployment, all of the [CockroachDB {{ site.data.products.cloud }} infrastructure]({% link cockroachcloud/plan-your-cluster-advanced.md %}#advanced-cluster-architecture) except the control plane lives in an account under your control, which means that you incur 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: - -Area | Cockroach Labs responsibility | Customer responsibility -:----------:|:-----------------------------:|:----------------------: -Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible -Deployments | Automate cluster provisioning and scaling, provide hardware best practices | Provision new cloud service accounts and grant IAM permissions for Cockroach Labs to create and manage clusters -Upgrades | Provide automatic minor/patch upgrades and major upgrade automation via Terraform, APIs, or the {{ site.data.products.cloud }} Console | Initiate [major version upgrades]({% link cockroachcloud/upgrade-cockroach-version.md %}), [set maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) if applicable -Workload | Troubleshoot problems as they pertain to cluster availability | [Size clusters]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) to manage workload requirements, [tune performance]({% link {{ site.versions["stable"] }}/performance-recipes.md %}), and adjust schema designs with support from Cockroach Labs -Backups | Initialize a default backup schedule and write to customer-owned Cloud storage, ensure backup jobs run successfully | Configure a backup schedule as needed to meet RPO/RTO requirements -Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available and appropriate IAM permissions are maintained at all times -Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockroachcloud/costs.md %}) at the per-minute level | Negotiate with cloud service provider, manage infrastructure spend and discounts \ No newline at end of file diff --git a/src/current/cockroachcloud/byoc-aws-deployment.md b/src/current/cockroachcloud/byoc-aws-deployment.md index 6f323e9114d..3f706c2e8cf 100644 --- a/src/current/cockroachcloud/byoc-aws-deployment.md +++ b/src/current/cockroachcloud/byoc-aws-deployment.md @@ -1,22 +1,16 @@ --- -title: Prepare a CockroachDB Cloud BYOC Deployment in AWS +title: Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services summary: Prepare a cloud service account to self-host a CockroachDB Cloud deployment with the BYOC model toc: true keywords: deployment, byoc --- -CockroachDB {{ site.data.products.cloud }} supports a "bring your own cloud" (BYOC) deployment model, where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own account rather than in an account managed by Cockroach Labs. 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 deployment]({% link cockroachcloud/byoc-overview.md %}) of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Amazon Web Services (AWS). {{site.data.alerts.callout_info}} The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). {{site.data.alerts.end}} -This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Microsoft Azure. - -## Shared responsibility model for BYOC - -{% include cockroachcloud/byoc/byoc-responsibility-model.md %} - ## Prerequisites {% include cockroachcloud/byoc/byoc-common-prerequisites.md %} @@ -218,7 +212,22 @@ You may also need to adjust quotas for vCPU and EBS disk storage for the regions ## 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). +In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.products.cloud }} Console or with the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}). + +### Create a cluster with the {{ site.data.products.cloud }} Console + +Follow these steps to create a CockroachDB cluster in the {{ site.data.products.cloud }} console: + +1. Open the {{ site.data.products.cloud }} and select the organization that has been enabled for BYOC. +1. Click **Create cluster** +1. Under **Select a plan**, click **{{ site.data.products.advanced }}. +1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select AWS. +1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the ARN associated with your intermediate IAM role. +1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. + +### Create a cluster with the {{ site.data.products.cloud }} API + +Send a `POST` request to the the `/v1/clusters` endpoint to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `us-east-2` region, specifying the ARN associated with your intermediate IAM role: diff --git a/src/current/cockroachcloud/byoc-azure-deployment.md b/src/current/cockroachcloud/byoc-azure-deployment.md index 0c2a458fd90..2a04878ab65 100644 --- a/src/current/cockroachcloud/byoc-azure-deployment.md +++ b/src/current/cockroachcloud/byoc-azure-deployment.md @@ -5,18 +5,12 @@ toc: true keywords: deployment, byoc --- -CockroachDB {{ site.data.products.cloud }} supports a "bring your own cloud" (BYOC) deployment model, where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own account rather than in an account managed by Cockroach Labs. 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 deployment]({% link cockroachcloud/byoc-overview.md %}) of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Microsoft Azure. {{site.data.alerts.callout_info}} The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). {{site.data.alerts.end}} -This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Microsoft Azure. - -## Shared responsibility model for BYOC - -{% include cockroachcloud/byoc/byoc-responsibility-model.md %} - ## Prerequisites {% include cockroachcloud/byoc/byoc-common-prerequisites.md %} @@ -230,7 +224,22 @@ Register the following [resource providers](https://learn.microsoft.com/azure/az ## 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). +In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.products.cloud }} Console or with the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}). + +### Create a cluster with the {{ site.data.products.cloud }} Console + +Follow these steps to create a CockroachDB cluster in the {{ site.data.products.cloud }} console: + +1. Open the {{ site.data.products.cloud }} and select the organization that has been enabled for BYOC. +1. Click **Create cluster** +1. Under **Select a plan**, click **{{ site.data.products.advanced }}. +1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select Azure. +1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the tenant ID and subscription ID associated with your Azure subscription. +1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. + +### Create a cluster with the {{ site.data.products.cloud }} API + +Send a `POST` request to the the `/v1/clusters` endpoint to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `centralus` region, specifying the `subscription-id` and `customer-tenant-id` associated with your Azure subscription: diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md index b97f2cd49f7..1db0f3db293 100644 --- a/src/current/cockroachcloud/byoc-gcp-deployment.md +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -1,22 +1,16 @@ --- -title: Prepare a CockroachDB Cloud BYOC Deployment in GCP +title: Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform summary: Prepare a cloud service account to self-host a CockroachDB Cloud deployment with the BYOC model toc: true keywords: deployment, byoc --- -CockroachDB {{ site.data.products.cloud }} supports a "bring your own cloud" (BYOC) deployment model, where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own account rather than in an account managed by Cockroach Labs. 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 deployment]({% link cockroachcloud/byoc-overview.md %}) of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Google Cloud Platform (GCP). {{site.data.alerts.callout_info}} The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). {{site.data.alerts.end}} -This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in GCP. - -## Shared responsibility model for BYOC - -{% include cockroachcloud/byoc/byoc-responsibility-model.md %} - ## Prerequisites {% include cockroachcloud/byoc/byoc-common-prerequisites.md %} @@ -56,7 +50,22 @@ Follow these steps to create the intermediate service account: ## Step 3. 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). +In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.products.cloud }} Console or with the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}). + +### Create a cluster with the {{ site.data.products.cloud }} Console + +Follow these steps to create a CockroachDB cluster in the {{ site.data.products.cloud }} console: + +1. Open the {{ site.data.products.cloud }} and select the organization that has been enabled for BYOC. +1. Click **Create cluster** +1. Under **Select a plan**, click **{{ site.data.products.advanced }}. +1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select Google Cloud. +1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the service account email associated with your intermediate service account. +1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. + +### Create a cluster with the {{ site.data.products.cloud }} API + +Send a `POST` request to the the `/v1/clusters` endpoint to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `us-east1` region, specifying the `service_account_email` associated with the intermediate service account you created: diff --git a/src/current/cockroachcloud/byoc-overview.md b/src/current/cockroachcloud/byoc-overview.md index f5ff2f98eae..83d524876fa 100644 --- a/src/current/cockroachcloud/byoc-overview.md +++ b/src/current/cockroachcloud/byoc-overview.md @@ -5,4 +5,32 @@ toc: true keywords: deployment, byoc --- -TODO \ No newline at end of file +CockroachDB {{ site.data.products.cloud }} supports a ["bring your own cloud" (BYOC) deployment model](https://www.cockroachlabs.com/product/cloud/bring-your-own-cloud/), where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own account rather than in an account managed by Cockroach Labs. This model allows you to take more control of security and take advantage of existing cloud service credits or discounts. + +{{site.data.alerts.callout_info}} +The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). +{{site.data.alerts.end}} + +## Shared responsibility model for BYOC + +In any CockroachDB {{ site.data.products.cloud }} deployment, responsibility for a successful and healthy deployment is [split between you and Cockroach Labs]({% link cockroachcloud/production-checklist.md %}). In a BYOC deployment, all of the [CockroachDB {{ site.data.products.cloud }} infrastructure]({% link cockroachcloud/plan-your-cluster-advanced.md %}#advanced-cluster-architecture) except the control plane lives in an account under your control, which means that you incur 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: + +Area | Cockroach Labs responsibility | Customer responsibility +:----------:|:-----------------------------:|:----------------------: +Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible +Deployments | Automate cluster provisioning and scaling, provide hardware best practices | Provision new cloud service accounts and grant IAM permissions for Cockroach Labs to create and manage clusters +Upgrades | Provide automatic minor/patch upgrades and major upgrade automation via Terraform, APIs, or the {{ site.data.products.cloud }} Console | Initiate [major version upgrades]({% link cockroachcloud/upgrade-cockroach-version.md %}), [set maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) if applicable +Workload | Troubleshoot problems as they pertain to cluster availability | [Size clusters]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) to manage workload requirements, [tune performance]({% link {{ site.versions["stable"] }}/performance-recipes.md %}), and adjust schema designs with support from Cockroach Labs +Backups | Initialize a default backup schedule and write to customer-owned Cloud storage, ensure backup jobs run successfully | Configure a backup schedule as needed to meet RPO/RTO requirements +Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available and appropriate IAM permissions are maintained at all times +Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockroachcloud/costs.md %}) at the per-minute level | Negotiate with cloud service provider, manage infrastructure spend and discounts + +## Next steps + +CockroachDB supports BYOC deployments in Amazon Web Services, Microsoft Azure, and Google Cloud Platform. Read the corresponding deployment guides: + +- [Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services]({% link cockroachcloud/byoc-aws-deployment.md %}). +- [Prepare a CockroachDB Cloud BYOC Deployment in Azure]({% link cockroachcloud/byoc-azure-deployment.md %}). +- [Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform]({% link cockroachcloud/byoc-gcp-deployment.md %}). \ No newline at end of file From b3fe5dc4c78e95b56faa17cda8d14d10f231357d Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Thu, 16 Apr 2026 17:38:41 -0400 Subject: [PATCH 04/12] Update old links and remove limitations --- src/current/cockroachcloud/advanced-cluster-management.md | 4 ---- src/current/cockroachcloud/create-an-advanced-cluster.md | 4 ---- src/current/cockroachcloud/plan-your-cluster-advanced.md | 2 +- src/current/v26.1/cockroachdb-feature-availability.md | 2 +- src/current/v26.2/cockroachdb-feature-availability.md | 2 +- 5 files changed, 3 insertions(+), 11 deletions(-) diff --git a/src/current/cockroachcloud/advanced-cluster-management.md b/src/current/cockroachcloud/advanced-cluster-management.md index 998b04e7d58..3bcb0f1530c 100644 --- a/src/current/cockroachcloud/advanced-cluster-management.md +++ b/src/current/cockroachcloud/advanced-cluster-management.md @@ -9,10 +9,6 @@ docs_area: manage This page describes the cluster management and cluster deletion workflows for CockroachDB {{ site.data.products.advanced }}. -{{site.data.alerts.callout_danger}} -If you are managing clusters in a [BYOC deployment]({% link cockroachcloud/byoc-deployment.md %}) you must use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to perform the actions described on this page. -{{site.data.alerts.end}} - ## Planning your cluster Before making any changes to your cluster's nodes or regions, review the [requirements and recommendations]({% link cockroachcloud/plan-your-cluster.md %}) for CockroachDB {{ site.data.products.cloud }} cluster configuration. diff --git a/src/current/cockroachcloud/create-an-advanced-cluster.md b/src/current/cockroachcloud/create-an-advanced-cluster.md index 336901431e5..80047f84ddd 100644 --- a/src/current/cockroachcloud/create-an-advanced-cluster.md +++ b/src/current/cockroachcloud/create-an-advanced-cluster.md @@ -11,10 +11,6 @@ This page guides you through the process of creating a CockroachDB {{ site.data. Only [CockroachDB {{ site.data.products.cloud }} Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) or users with Cluster Creator / Cluster Admin roles assigned at organization scope can create clusters. If you need permission to create a cluster, contact an CockroachDB {{ site.data.products.cloud }} Organization Admin. -{{site.data.alerts.callout_danger}} -If you are creating a cluster for a [BYOC deployment]({% link cockroachcloud/byoc-deployment.md %}) you must use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to perform the actions described on this page. -{{site.data.alerts.end}} - ## Step 1. Start the cluster creation process 1. If you haven't already, sign up for a CockroachDB {{ site.data.products.cloud }} account, then [log in](https://cockroachlabs.cloud/). diff --git a/src/current/cockroachcloud/plan-your-cluster-advanced.md b/src/current/cockroachcloud/plan-your-cluster-advanced.md index 63eb95dbff1..25439a72241 100644 --- a/src/current/cockroachcloud/plan-your-cluster-advanced.md +++ b/src/current/cockroachcloud/plan-your-cluster-advanced.md @@ -23,7 +23,7 @@ CockroachDB {{ site.data.products.cloud }} operations are split into logical lay - Control operations manage the CockroachDB cluster as a whole. These requests are handled by the **CockroachDB Cloud control plane** which communicates directly with cluster nodes as needed. These connections include access to the {{ site.data.products.cloud }} Console, DB Console, [Cloud API]({% link cockroachcloud/cloud-api.md %}), [observability features]({% link cockroachcloud/metrics.md %}), and other cluster management tools. - Data operations involve connections between data applications and your underlying CockroachDB nodes, including SQL queries and responses. Each region has a network load balancer (NLB) that handles and distributes requests across CockroachDB nodes within the region. {{ site.data.products.advanced }} clusters can utilize [private connectivity]({% link cockroachcloud/private-clusters.md %}) across the cloud to limit the amount of network traffic that is sent over the public Internet. -In a "bring your own cloud" (BYOC) deployment of CockroachDB {{ site.data.products.cloud }}, the data operations layer is hosted within your own cloud service account rather than an account managed by Cockroach Labs. To learn more, [read the BYOC deployment documentation]({% link cockroachcloud/byoc-deployment.md %}). +In a "bring your own cloud" (BYOC) deployment of CockroachDB {{ site.data.products.cloud }}, the data operations layer is hosted within your own cloud service account rather than an account managed by Cockroach Labs. To learn more, [read the BYOC deployment documentation]({% link cockroachcloud/byoc-overview.md %}). ## Cluster topology diff --git a/src/current/v26.1/cockroachdb-feature-availability.md b/src/current/v26.1/cockroachdb-feature-availability.md index 41e060a5705..e01ac6fbed9 100644 --- a/src/current/v26.1/cockroachdb-feature-availability.md +++ b/src/current/v26.1/cockroachdb-feature-availability.md @@ -132,7 +132,7 @@ Enabling and managing [Customer-Managed Encryption Keys (CMEK)]({% link cockroac ### Bring your own cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} -Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-deployment.md %}) is in preview for Microsoft Azure. +Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-overview.md %}) is in preview for Amazon Web Services, Microsoft Azure, and Google Cloud Platform. ### Convert a schema from Oracle or Microsoft SQL Server diff --git a/src/current/v26.2/cockroachdb-feature-availability.md b/src/current/v26.2/cockroachdb-feature-availability.md index 1350d34bb26..e7408855441 100644 --- a/src/current/v26.2/cockroachdb-feature-availability.md +++ b/src/current/v26.2/cockroachdb-feature-availability.md @@ -132,7 +132,7 @@ Enabling and managing [Customer-Managed Encryption Keys (CMEK)]({% link cockroac ### Bring your own cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} -Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-deployment.md %}) is in preview for Microsoft Azure. +Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-overview.md %}) is in preview for Amazon Web Services, Microsoft Azure, and Google Cloud Platform. ### Convert a schema from Oracle or Microsoft SQL Server From fc87c845a24d03bb5cd81b94b1e02d980d93de44 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Thu, 16 Apr 2026 17:52:12 -0400 Subject: [PATCH 05/12] Add missing sidebar entry --- .../v26.2/sidebar-data/cloud-deployments.json | 29 +++++++++++++++++-- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json index 6ae5a968ddd..7d182310197 100644 --- a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json @@ -21,9 +21,32 @@ ] }, { - "title": "BYOC Deployments (Preview)", - "urls": [ - "/cockroachcloud/byoc-deployment.html" + "title": "Bring-Your-Own-Cloud (BYOC)", + "items": [ + { + "title": "BYOC Overview", + "urls": [ + "/cockroachcloud/byoc-overview.html" + ] + }, + { + "title": "Deploy BYOC in AWS", + "urls": [ + "/cockroachcloud/byoc-aws-deployment.html" + ] + }, + { + "title": "Deploy BYOC in Azure", + "urls": [ + "/cockroachcloud/byoc-azure-deployment.html" + ] + }, + { + "title": "Deploy BYOC in GCP", + "urls": [ + "/cockroachcloud/byoc-gcp-deployment.html" + ] + } ] }, { From 2115f129267269fde745c9a50c3f65a2292ff963 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 20 Apr 2026 15:14:35 -0400 Subject: [PATCH 06/12] Ryan and Lakshmi comments --- .../byoc/byoc-common-prerequisites.md | 4 +- .../cockroachcloud/byoc-aws-deployment.md | 27 ++++++------ .../cockroachcloud/byoc-azure-deployment.md | 4 +- .../cockroachcloud/byoc-gcp-deployment.md | 43 ++++++++++++++++--- src/current/cockroachcloud/byoc-overview.md | 12 ++++-- 5 files changed, 66 insertions(+), 24 deletions(-) diff --git a/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md b/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md index 524da04e2b2..6f5923dac63 100644 --- a/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md +++ b/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md @@ -2,10 +2,8 @@ - [Create a CockroachDB {{ site.data.products.cloud }} organization]({% link cockroachcloud/create-an-account.md %}) if you do not already have one. -- (Optional) Create an [API service account]({% link cockroachcloud/managing-access.md %}#create-api-keys) to use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) with your {{ site.data.products.cloud }} organization. - - The BYOC deployment option is not available by default and must be requested. Reach out to your account team to express interest in BYOC. -- Review the [Plan a CockroachDB {{ site.data.products.advanced }} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation to plan your cluster sizing and resource allocation. +- Once your cloud account is prepared for a CockroachDB BYOC deployment, cluster configuration and management is identical to a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster. Review the [Plan a CockroachDB {{ site.data.products.advanced }} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation to plan your cluster sizing and resource allocation. - Review cloud service regions supported by [CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }}]({% link cockroachcloud/regions.md %}?filters=advanced). \ No newline at end of file diff --git a/src/current/cockroachcloud/byoc-aws-deployment.md b/src/current/cockroachcloud/byoc-aws-deployment.md index 3f706c2e8cf..c30685eb883 100644 --- a/src/current/cockroachcloud/byoc-aws-deployment.md +++ b/src/current/cockroachcloud/byoc-aws-deployment.md @@ -1,6 +1,6 @@ --- title: Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services -summary: Prepare a cloud service account to self-host a CockroachDB Cloud deployment with the BYOC model +summary: Prepare an Amazon Web Services account to host a BYOC deployment of CockroachDB toc: true keywords: deployment, byoc --- @@ -15,15 +15,17 @@ The BYOC {{ site.data.products.cloud }} deployment option is currently in [Previ {% include cockroachcloud/byoc/byoc-common-prerequisites.md %} +- Create an [API service account]({% link cockroachcloud/managing-access.md %}#create-api-keys) to use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) with your {{ site.data.products.cloud }} organization. + ## Step 1. Create a new AWS account Provision a new AWS account 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 account, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This account can be reused for multiple CockroachDB clusters. ## Step 2. Record your intermediate role's ARN -Cockroach Labs uses an intermediate **IAM role** to provision and manage resources in your AWS account. In this step, use your CockroachDB {{ site.data.products.cloud }} organization label to determine the **Amazon Resource Name (ARN)** of this IAM role. +Cockroach Labs uses an intermediate **IAM role** to provision and manage resources in your AWS account. In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to get the **Amazon Resource Name (ARN)** of this IAM role. -Find your org label in the CockroachDB {{ site.data.products.cloud }} Console or by using the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) with a `GET` request similar to the following example: +Send a `GET` request to the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) similar to the following example: {% include_cached copy-clipboard.html %} ~~~ shell @@ -32,15 +34,16 @@ curl --request GET \ --header 'Authorization: Bearer {secret_key}' ~~~ -Record the ARN of your organization's intermediate IAM role using the following schema: - -~~~ text -arn:aws:iam:::user/byoc/CockroachDB-Cloud-managed-BYOC_ -~~~ +Record the value of `cockroach_cloud_service_principals.aws.user_arn` in the response: -For example, if your organization’s org label is `org-32222` then record your ARN as follows: -~~~ -arn:aws:iam:::user/byoc/CockroachDB-Cloud-managed-BYOC_org-32222 +~~~ json +{ + "cockroach_cloud_service_principals": { + "aws": { + "user_arn": "arn:aws:iam::{AWS Account ID}:example/arn" + } + } +} ~~~ ## Step 3. Create IAM role for Cockroach Labs access @@ -48,7 +51,7 @@ arn:aws:iam:::user/byoc/CockroachDB-Cloud-managed-BYOC_org-32222 Follow these steps to create the intermediate IAM role and grant the necessary permissions: 1. Open the AWS IAM console. -1. Create a new role. This name is arbitrary, in these instructions the role is named `CRLBYOCAdmin`. +1. Create a new role. This name is arbitrary and can be named whatever you want. In these instructions the example role is named `CRLBYOCAdmin`. 1. Use the following trust relationship policy for the new role, using the ARN collected in the previous step: {% include_cached copy-clipboard.html %} ~~~ json diff --git a/src/current/cockroachcloud/byoc-azure-deployment.md b/src/current/cockroachcloud/byoc-azure-deployment.md index 2a04878ab65..eb1078bdb5d 100644 --- a/src/current/cockroachcloud/byoc-azure-deployment.md +++ b/src/current/cockroachcloud/byoc-azure-deployment.md @@ -1,6 +1,6 @@ --- title: Prepare a CockroachDB Cloud BYOC Deployment in Azure -summary: Prepare a cloud service account to self-host a CockroachDB Cloud deployment with the BYOC model +summary: Prepare a Microsoft Azure account to host a BYOC deployment of CockroachDB toc: true keywords: deployment, byoc --- @@ -15,6 +15,8 @@ The BYOC {{ site.data.products.cloud }} deployment option is currently in [Previ {% include cockroachcloud/byoc/byoc-common-prerequisites.md %} +- (Optional) Create an [API service account]({% link cockroachcloud/managing-access.md %}#create-api-keys) to use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) with your {{ site.data.products.cloud }} organization. + ## Step 1. Create a new Azure subscription 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. diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md index 1db0f3db293..5af9be8e7af 100644 --- a/src/current/cockroachcloud/byoc-gcp-deployment.md +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -1,6 +1,6 @@ --- title: Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform -summary: Prepare a cloud service account to self-host a CockroachDB Cloud deployment with the BYOC model +summary: Prepare a Google Cloud Platform account to host a BYOC deployment of CockroachDB toc: true keywords: deployment, byoc --- @@ -15,22 +15,55 @@ The BYOC {{ site.data.products.cloud }} deployment option is currently in [Previ {% include cockroachcloud/byoc/byoc-common-prerequisites.md %} +- Create an [API service account]({% link cockroachcloud/managing-access.md %}#create-api-keys) to use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) with your {{ site.data.products.cloud }} organization. + ## Step 1. Create a new GCP project Provision a fresh **GCP project** with no existing infrastructure, dedicated to your Cockroach {{ site.data.products.cloud }} deployment. The project configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this project, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This project can be reused for multiple CockroachDB clusters. The following requirements apply to the GCP project used for your BYOC deployment: + - The project ID **must not** begin with the reserved prefix `crl-`. - [Enable](https://docs.cloud.google.com/endpoints/docs/openapi/enable-api) the Service Usage API and the Cloud Resource Manager APIs for this project. Cockroach Labs will enable additional APIs as needed, but these two must be initialized first. -## Step 2. Configure an intermediate service account for Cockroach Labs +## Step 2. Grant permissions to the Cockroach Labs service account + +Cockroach Labs provisions a service account for your organization which is used to manage CockroachDB {{ site.data.products.cloud }} resources in your GCP account. In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to collect the email address of the Cockroach Labs service account and grant it the necessary roles. + +Send a `GET` request to the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) similar to the following example: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/organization \ + --header 'Authorization: Bearer {secret_key}' +~~~ + +Record the value of `cockroach_cloud_service_principals.gcp.service_account_email` in the response: + +~~~ json +{ + "cockroach_cloud_service_principals": { + "gcp": { + "service_account_email": "example@email.com" + } + } +} +~~~ + +Grant this service account the following roles in the GCP IAM Console: + +- `Service Account Token Creator (roles/iam.serviceAccountTokenCreator)` +- `View Service Accounts (roles/iam.serviceAccountViewer)` + +## Step 3. Configure an intermediate service account for Cockroach Labs -Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. +Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. In this step, create a new intermediate service account (separate from the service account provisioned by Cockroach Labs) and grant it the necessary roles in your GCP project. Follow these steps to create the intermediate service account: 1. Open the GCP IAM Console. -2. Create a new service account. The name is arbitrary but be sure to note down the email address of the account. +2. Create a new service account. The account's name is arbitrary and can be whatever you want, but be sure to note down the email address of the account. 3. Grant the following IAM roles to the service account: - `Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)` - `Compute Network Admin (roles/compute.networkAdmin)` @@ -48,7 +81,7 @@ Follow these steps to create the intermediate service account: - `Storage Admin (roles/storage.admin)` -## Step 3. Create the CockroachDB {{ site.data.products.cloud }} cluster +## Step 4. Create the CockroachDB {{ site.data.products.cloud }} cluster In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.products.cloud }} Console or with the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}). diff --git a/src/current/cockroachcloud/byoc-overview.md b/src/current/cockroachcloud/byoc-overview.md index 83d524876fa..db42e3caf24 100644 --- a/src/current/cockroachcloud/byoc-overview.md +++ b/src/current/cockroachcloud/byoc-overview.md @@ -19,12 +19,12 @@ The following table describes the split of responsibilities between you and Cock Area | Cockroach Labs responsibility | Customer responsibility :----------:|:-----------------------------:|:----------------------: -Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible +Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible to CRL via cross-account IAM as documented in the corresponding deployment guide Deployments | Automate cluster provisioning and scaling, provide hardware best practices | Provision new cloud service accounts and grant IAM permissions for Cockroach Labs to create and manage clusters Upgrades | Provide automatic minor/patch upgrades and major upgrade automation via Terraform, APIs, or the {{ site.data.products.cloud }} Console | Initiate [major version upgrades]({% link cockroachcloud/upgrade-cockroach-version.md %}), [set maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) if applicable Workload | Troubleshoot problems as they pertain to cluster availability | [Size clusters]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) to manage workload requirements, [tune performance]({% link {{ site.versions["stable"] }}/performance-recipes.md %}), and adjust schema designs with support from Cockroach Labs Backups | Initialize a default backup schedule and write to customer-owned Cloud storage, ensure backup jobs run successfully | Configure a backup schedule as needed to meet RPO/RTO requirements -Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available and appropriate IAM permissions are maintained at all times +Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available, including negotiating cloud resource quotas and availability with your cloud service provider. Maintain appropriate IAM permissions at all times Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockroachcloud/costs.md %}) at the per-minute level | Negotiate with cloud service provider, manage infrastructure spend and discounts ## Next steps @@ -33,4 +33,10 @@ CockroachDB supports BYOC deployments in Amazon Web Services, Microsoft Azure, a - [Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services]({% link cockroachcloud/byoc-aws-deployment.md %}). - [Prepare a CockroachDB Cloud BYOC Deployment in Azure]({% link cockroachcloud/byoc-azure-deployment.md %}). -- [Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform]({% link cockroachcloud/byoc-gcp-deployment.md %}). \ No newline at end of file +- [Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform]({% link cockroachcloud/byoc-gcp-deployment.md %}). + +Once your cloud account is prepared for a BYOC deployment, cluster configuration and management is identical to a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster. Read more about CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster planning and management: + +- [Plan an {{ site.data.products.advanced }} cluster deployment]({% link cockroachcloud/plan-your-cluster-advanced.md %}) +- [Manage a cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) +- [Prepare a deployment for production]({% link cockroachcloud/production-checklist.md %}) From b7cf432c3f6bcb49c9a8b47efcfb7da6f25e1cec Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 20 Apr 2026 16:36:20 -0400 Subject: [PATCH 07/12] Disambiguate between service accounts --- src/current/cockroachcloud/byoc-gcp-deployment.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md index 5af9be8e7af..81af6f1a48e 100644 --- a/src/current/cockroachcloud/byoc-gcp-deployment.md +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -28,7 +28,12 @@ The following requirements apply to the GCP project used for your BYOC deploymen ## Step 2. Grant permissions to the Cockroach Labs service account -Cockroach Labs provisions a service account for your organization which is used to manage CockroachDB {{ site.data.products.cloud }} resources in your GCP account. In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to collect the email address of the Cockroach Labs service account and grant it the necessary roles. +Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. This requires two service accounts: + +- A service account owned by Cockroach Labs which must be granted roles to view and access service accounts in your GCP project. +- An intermediary service account in your GCP project which must be granted roles create and manage infrasturcture. This service account is the target used by Cockroach Labs for cross-account impersonation. + +In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to collect the email address of the Cockroach Labs service account and grant it the necessary roles. Send a `GET` request to the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) similar to the following example: @@ -56,9 +61,9 @@ Grant this service account the following roles in the GCP IAM Console: - `Service Account Token Creator (roles/iam.serviceAccountTokenCreator)` - `View Service Accounts (roles/iam.serviceAccountViewer)` -## Step 3. Configure an intermediate service account for Cockroach Labs +## Step 3. Configure the intermediate service account -Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. In this step, create a new intermediate service account (separate from the service account provisioned by Cockroach Labs) and grant it the necessary roles in your GCP project. +In this step, create the intermediate service account in your GCP project and grant it the necessary roles in your GCP project. Follow these steps to create the intermediate service account: From acdbbd127e15ef968830a61fe447ee363296552c Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 20 Apr 2026 16:47:03 -0400 Subject: [PATCH 08/12] Disambiguate AWS IAM accounts --- src/current/cockroachcloud/byoc-aws-deployment.md | 15 +++++++++++---- src/current/cockroachcloud/byoc-gcp-deployment.md | 2 +- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/src/current/cockroachcloud/byoc-aws-deployment.md b/src/current/cockroachcloud/byoc-aws-deployment.md index c30685eb883..719c70dc666 100644 --- a/src/current/cockroachcloud/byoc-aws-deployment.md +++ b/src/current/cockroachcloud/byoc-aws-deployment.md @@ -21,9 +21,14 @@ The BYOC {{ site.data.products.cloud }} deployment option is currently in [Previ Provision a new AWS account 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 account, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This account can be reused for multiple CockroachDB clusters. -## Step 2. Record your intermediate role's ARN +## Step 2. Collect the Cockroach Labs IAM role ARN -Cockroach Labs uses an intermediate **IAM role** to provision and manage resources in your AWS account. In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to get the **Amazon Resource Name (ARN)** of this IAM role. +Cockroach Labs uses cross-account resource management to provision and manage resources in your AWS account. This requires two **IAM roles**: + +- An IAM role owned by Cockroach Labs which must be granted permissions to access an IAM role in your AWS account. +- An intermediary IAM role in your AWS account which must be granted permissions to create and manage infrastructure. This IAM role is the target used by Cockroach Labs for cross-account management. + +In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to get the **Amazon Resource Name (ARN)** of the IAM role provisioned by Cockroach Labs for your account. Send a `GET` request to the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) similar to the following example: @@ -46,9 +51,11 @@ Record the value of `cockroach_cloud_service_principals.aws.user_arn` in the res } ~~~ -## Step 3. Create IAM role for Cockroach Labs access +## Step 3. Create intermediary IAM role and apply permissions + +In this step, create the intermediary IAM role in your AWS account and apply a trust relationship policy and permissions that allows Cockroach Labs to assume the intermediary role as needed. -Follow these steps to create the intermediate IAM role and grant the necessary permissions: +Follow these steps to create the intermediate IAM role: 1. Open the AWS IAM console. 1. Create a new role. This name is arbitrary and can be named whatever you want. In these instructions the example role is named `CRLBYOCAdmin`. diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md index 81af6f1a48e..dc0a6604dac 100644 --- a/src/current/cockroachcloud/byoc-gcp-deployment.md +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -31,7 +31,7 @@ The following requirements apply to the GCP project used for your BYOC deploymen Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. This requires two service accounts: - A service account owned by Cockroach Labs which must be granted roles to view and access service accounts in your GCP project. -- An intermediary service account in your GCP project which must be granted roles create and manage infrasturcture. This service account is the target used by Cockroach Labs for cross-account impersonation. +- An intermediary service account in your GCP project which must be granted roles to create and manage infrasturcture. This service account is the target used by Cockroach Labs for cross-account impersonation. In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to collect the email address of the Cockroach Labs service account and grant it the necessary roles. From 9681d2bb561b846073d65ffb3005add55d63ff57 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Tue, 21 Apr 2026 14:52:25 -0400 Subject: [PATCH 09/12] Apply suggestions from code review Co-authored-by: bsanchez-the-roach --- .../v26.1/sidebar-data/cloud-deployments.json | 2 +- .../v26.2/sidebar-data/cloud-deployments.json | 2 +- .../cockroachcloud/byoc-aws-deployment.md | 16 ++++++++-------- .../cockroachcloud/byoc-azure-deployment.md | 6 +++--- .../cockroachcloud/byoc-gcp-deployment.md | 8 ++++---- src/current/cockroachcloud/byoc-overview.md | 10 +++++----- .../cockroachcloud/plan-your-cluster-advanced.md | 2 +- .../v26.1/cockroachdb-feature-availability.md | 2 +- .../v26.2/cockroachdb-feature-availability.md | 2 +- 9 files changed, 25 insertions(+), 25 deletions(-) diff --git a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json index 49c0923e4fe..60a59eeb11c 100644 --- a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json @@ -21,7 +21,7 @@ ] }, { - "title": "Bring-Your-Own-Cloud (BYOC)", + "title": "Bring Your Own Cloud (BYOC)", "items": [ { "title": "BYOC Overview", diff --git a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json index 7d182310197..bf8e063837a 100644 --- a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json @@ -21,7 +21,7 @@ ] }, { - "title": "Bring-Your-Own-Cloud (BYOC)", + "title": "Bring Your Own Cloud (BYOC)", "items": [ { "title": "BYOC Overview", diff --git a/src/current/cockroachcloud/byoc-aws-deployment.md b/src/current/cockroachcloud/byoc-aws-deployment.md index 719c70dc666..a50eb75c100 100644 --- a/src/current/cockroachcloud/byoc-aws-deployment.md +++ b/src/current/cockroachcloud/byoc-aws-deployment.md @@ -8,7 +8,7 @@ keywords: deployment, byoc This page describes how to prepare a cloud service account to host a [BYOC deployment]({% link cockroachcloud/byoc-overview.md %}) of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Amazon Web Services (AWS). {{site.data.alerts.callout_info}} -The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). +{% include feature-phases/preview.md %} {{site.data.alerts.end}} ## Prerequisites @@ -19,7 +19,7 @@ The BYOC {{ site.data.products.cloud }} deployment option is currently in [Previ ## Step 1. Create a new AWS account -Provision a new AWS account 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 account, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This account can be reused for multiple CockroachDB clusters. +Provision a new AWS account with no existing infrastructure, dedicated to your CockroachDB {{ site.data.products.cloud }} deployment. The account configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this account, so this step is necessary to isolate these permissions from non-CockroachDB Cloud resources. This account can be reused for multiple CockroachDB clusters. ## Step 2. Collect the Cockroach Labs IAM role ARN @@ -53,12 +53,12 @@ Record the value of `cockroach_cloud_service_principals.aws.user_arn` in the res ## Step 3. Create intermediary IAM role and apply permissions -In this step, create the intermediary IAM role in your AWS account and apply a trust relationship policy and permissions that allows Cockroach Labs to assume the intermediary role as needed. +In this step, create the intermediary IAM role in your AWS account, then apply a trust relationship policy and permissions that allow Cockroach Labs to assume the intermediary role as needed. Follow these steps to create the intermediate IAM role: 1. Open the AWS IAM console. -1. Create a new role. This name is arbitrary and can be named whatever you want. In these instructions the example role is named `CRLBYOCAdmin`. +1. Create a new role. You can choose any name for this role. In these instructions the example role is named `CRLBYOCAdmin`. 1. Use the following trust relationship policy for the new role, using the ARN collected in the previous step: {% include_cached copy-clipboard.html %} ~~~ json @@ -218,7 +218,7 @@ Follow these steps to create the intermediate IAM role: If you plan to use non-default AWS regions, you must manually enable them in the AWS Management Console. You must also activate [global STS tokens](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_region-endpoints.html) for these regions to work with CockroachDB. -You may also need to adjust quotas for vCPU and EBS disk storage for the regions that you plan to create your cluster in. +You may also need to adjust quotas for vCPU and EBS disk storage for the regions in which you plan to create your cluster. ## Step 5. Create the CockroachDB {{ site.data.products.cloud }} cluster @@ -228,9 +228,9 @@ In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.pr Follow these steps to create a CockroachDB cluster in the {{ site.data.products.cloud }} console: -1. Open the {{ site.data.products.cloud }} and select the organization that has been enabled for BYOC. -1. Click **Create cluster** -1. Under **Select a plan**, click **{{ site.data.products.advanced }}. +1. Open the {{ site.data.products.cloud }} Console and select the organization that has been enabled for BYOC. +1. Click **Create cluster**. +1. Under **Select a plan**, click **{{ site.data.products.advanced }}**. 1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select AWS. 1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the ARN associated with your intermediate IAM role. 1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. diff --git a/src/current/cockroachcloud/byoc-azure-deployment.md b/src/current/cockroachcloud/byoc-azure-deployment.md index eb1078bdb5d..cdb0506ff89 100644 --- a/src/current/cockroachcloud/byoc-azure-deployment.md +++ b/src/current/cockroachcloud/byoc-azure-deployment.md @@ -8,7 +8,7 @@ keywords: deployment, byoc This page describes how to prepare a cloud service account to host a [BYOC deployment]({% link cockroachcloud/byoc-overview.md %}) of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Microsoft Azure. {{site.data.alerts.callout_info}} -The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). +{% include feature-phases/preview.md %} {{site.data.alerts.end}} ## Prerequisites @@ -233,8 +233,8 @@ In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.pr Follow these steps to create a CockroachDB cluster in the {{ site.data.products.cloud }} console: 1. Open the {{ site.data.products.cloud }} and select the organization that has been enabled for BYOC. -1. Click **Create cluster** -1. Under **Select a plan**, click **{{ site.data.products.advanced }}. +1. Click **Create cluster**. +1. Under **Select a plan**, click **{{ site.data.products.advanced }}**. 1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select Azure. 1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the tenant ID and subscription ID associated with your Azure subscription. 1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md index dc0a6604dac..2801288e558 100644 --- a/src/current/cockroachcloud/byoc-gcp-deployment.md +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -8,7 +8,7 @@ keywords: deployment, byoc This page describes how to prepare a cloud service account to host a [BYOC deployment]({% link cockroachcloud/byoc-overview.md %}) of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Google Cloud Platform (GCP). {{site.data.alerts.callout_info}} -The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). +{% include feature-phases/preview.md %} {{site.data.alerts.end}} ## Prerequisites @@ -19,7 +19,7 @@ The BYOC {{ site.data.products.cloud }} deployment option is currently in [Previ ## Step 1. Create a new GCP project -Provision a fresh **GCP project** with no existing infrastructure, dedicated to your Cockroach {{ site.data.products.cloud }} deployment. The project configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this project, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This project can be reused for multiple CockroachDB clusters. +Provision a fresh **GCP project** with no existing infrastructure, dedicated to your CockroachDB {{ site.data.products.cloud }} deployment. The project configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this project, so this step is necessary to isolate these permissions from non-CockroachDB Cloud resources. This project can be reused for multiple CockroachDB clusters. The following requirements apply to the GCP project used for your BYOC deployment: @@ -95,8 +95,8 @@ In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.pr Follow these steps to create a CockroachDB cluster in the {{ site.data.products.cloud }} console: 1. Open the {{ site.data.products.cloud }} and select the organization that has been enabled for BYOC. -1. Click **Create cluster** -1. Under **Select a plan**, click **{{ site.data.products.advanced }}. +1. Click **Create cluster**. +1. Under **Select a plan**, click **{{ site.data.products.advanced }}**. 1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select Google Cloud. 1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the service account email associated with your intermediate service account. 1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. diff --git a/src/current/cockroachcloud/byoc-overview.md b/src/current/cockroachcloud/byoc-overview.md index db42e3caf24..46520cd8675 100644 --- a/src/current/cockroachcloud/byoc-overview.md +++ b/src/current/cockroachcloud/byoc-overview.md @@ -5,10 +5,10 @@ toc: true keywords: deployment, byoc --- -CockroachDB {{ site.data.products.cloud }} supports a ["bring your own cloud" (BYOC) deployment model](https://www.cockroachlabs.com/product/cloud/bring-your-own-cloud/), where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own account rather than in an account managed by Cockroach Labs. This model allows you to take more control of security and take advantage of existing cloud service credits or discounts. +CockroachDB {{ site.data.products.cloud }} supports a [Bring Your Own Cloud (BYOC) deployment model](https://www.cockroachlabs.com/product/cloud/bring-your-own-cloud/), where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own cloud account rather than in an account managed by Cockroach Labs. This model allows you to take more control of security and take advantage of existing cloud service credits or discounts. {{site.data.alerts.callout_info}} -The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). +{% include feature-phases/preview.md %} {{site.data.alerts.end}} ## Shared responsibility model for BYOC @@ -19,7 +19,7 @@ The following table describes the split of responsibilities between you and Cock Area | Cockroach Labs responsibility | Customer responsibility :----------:|:-----------------------------:|:----------------------: -Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible to CRL via cross-account IAM as documented in the corresponding deployment guide +Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible to CRL via cross-account IAM as documented in the corresponding [deployment guide](#next-steps) Deployments | Automate cluster provisioning and scaling, provide hardware best practices | Provision new cloud service accounts and grant IAM permissions for Cockroach Labs to create and manage clusters Upgrades | Provide automatic minor/patch upgrades and major upgrade automation via Terraform, APIs, or the {{ site.data.products.cloud }} Console | Initiate [major version upgrades]({% link cockroachcloud/upgrade-cockroach-version.md %}), [set maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) if applicable Workload | Troubleshoot problems as they pertain to cluster availability | [Size clusters]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) to manage workload requirements, [tune performance]({% link {{ site.versions["stable"] }}/performance-recipes.md %}), and adjust schema designs with support from Cockroach Labs @@ -29,13 +29,13 @@ Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockro ## Next steps -CockroachDB supports BYOC deployments in Amazon Web Services, Microsoft Azure, and Google Cloud Platform. Read the corresponding deployment guides: +CockroachDB supports BYOC deployments in Amazon Web Services, Microsoft Azure, and Google Cloud Platform. To prepare your cloud account for a BYOC deployment, refer to the corresponding deployment guide: - [Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services]({% link cockroachcloud/byoc-aws-deployment.md %}). - [Prepare a CockroachDB Cloud BYOC Deployment in Azure]({% link cockroachcloud/byoc-azure-deployment.md %}). - [Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform]({% link cockroachcloud/byoc-gcp-deployment.md %}). -Once your cloud account is prepared for a BYOC deployment, cluster configuration and management is identical to a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster. Read more about CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster planning and management: +Once your cloud account is prepared for a BYOC deployment, cluster configuration and management is identical to a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster. To learn more about CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster planning and management, refer to the following guides: - [Plan an {{ site.data.products.advanced }} cluster deployment]({% link cockroachcloud/plan-your-cluster-advanced.md %}) - [Manage a cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) diff --git a/src/current/cockroachcloud/plan-your-cluster-advanced.md b/src/current/cockroachcloud/plan-your-cluster-advanced.md index 25439a72241..a09a33f7237 100644 --- a/src/current/cockroachcloud/plan-your-cluster-advanced.md +++ b/src/current/cockroachcloud/plan-your-cluster-advanced.md @@ -23,7 +23,7 @@ CockroachDB {{ site.data.products.cloud }} operations are split into logical lay - Control operations manage the CockroachDB cluster as a whole. These requests are handled by the **CockroachDB Cloud control plane** which communicates directly with cluster nodes as needed. These connections include access to the {{ site.data.products.cloud }} Console, DB Console, [Cloud API]({% link cockroachcloud/cloud-api.md %}), [observability features]({% link cockroachcloud/metrics.md %}), and other cluster management tools. - Data operations involve connections between data applications and your underlying CockroachDB nodes, including SQL queries and responses. Each region has a network load balancer (NLB) that handles and distributes requests across CockroachDB nodes within the region. {{ site.data.products.advanced }} clusters can utilize [private connectivity]({% link cockroachcloud/private-clusters.md %}) across the cloud to limit the amount of network traffic that is sent over the public Internet. -In a "bring your own cloud" (BYOC) deployment of CockroachDB {{ site.data.products.cloud }}, the data operations layer is hosted within your own cloud service account rather than an account managed by Cockroach Labs. To learn more, [read the BYOC deployment documentation]({% link cockroachcloud/byoc-overview.md %}). +In a Bring Your Own Cloud (BYOC) deployment of CockroachDB {{ site.data.products.cloud }}, the data operations layer is hosted within your own cloud service account rather than an account managed by Cockroach Labs. To learn more, [read the BYOC deployment documentation]({% link cockroachcloud/byoc-overview.md %}). ## Cluster topology diff --git a/src/current/v26.1/cockroachdb-feature-availability.md b/src/current/v26.1/cockroachdb-feature-availability.md index e01ac6fbed9..80782e931f8 100644 --- a/src/current/v26.1/cockroachdb-feature-availability.md +++ b/src/current/v26.1/cockroachdb-feature-availability.md @@ -130,7 +130,7 @@ Exporting metrics to Azure Monitor is in limited access. Refer to [Export metric Enabling and managing [Customer-Managed Encryption Keys (CMEK)]({% link cockroachcloud/cmek.md %}) for CockroachDB {{ site.data.products.advanced }} in the {{ site.data.products.cloud }} Console is in preview. CMEK management with the [Cloud API]({% link cockroachcloud/cloud-api.md %}) is in general availability. -### Bring your own cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} +### Bring Your Own Cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-overview.md %}) is in preview for Amazon Web Services, Microsoft Azure, and Google Cloud Platform. diff --git a/src/current/v26.2/cockroachdb-feature-availability.md b/src/current/v26.2/cockroachdb-feature-availability.md index e7408855441..c8e3d479d36 100644 --- a/src/current/v26.2/cockroachdb-feature-availability.md +++ b/src/current/v26.2/cockroachdb-feature-availability.md @@ -130,7 +130,7 @@ Exporting metrics to Azure Monitor is in limited access. Refer to [Export metric Enabling and managing [Customer-Managed Encryption Keys (CMEK)]({% link cockroachcloud/cmek.md %}) for CockroachDB {{ site.data.products.advanced }} in the {{ site.data.products.cloud }} Console is in preview. CMEK management with the [Cloud API]({% link cockroachcloud/cloud-api.md %}) is in general availability. -### Bring your own cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} +### Bring Your Own Cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-overview.md %}) is in preview for Amazon Web Services, Microsoft Azure, and Google Cloud Platform. From 68dbfedd90d75e1862bb4b10cfc31e83cf09ce2b Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Tue, 21 Apr 2026 15:21:05 -0400 Subject: [PATCH 10/12] Brandon comments --- src/current/_includes/feature-phases/preview.md | 2 +- .../v26.1/sidebar-data/cloud-deployments.json | 6 +++--- .../v26.2/sidebar-data/cloud-deployments.json | 6 +++--- src/current/cockroachcloud/byoc-aws-deployment.md | 8 ++++---- src/current/cockroachcloud/byoc-azure-deployment.md | 6 +++--- src/current/cockroachcloud/byoc-gcp-deployment.md | 12 ++++++------ src/current/cockroachcloud/byoc-overview.md | 8 ++++---- 7 files changed, 24 insertions(+), 24 deletions(-) diff --git a/src/current/_includes/feature-phases/preview.md b/src/current/_includes/feature-phases/preview.md index 5506a046ba7..8deaa37bcd6 100644 --- a/src/current/_includes/feature-phases/preview.md +++ b/src/current/_includes/feature-phases/preview.md @@ -5,4 +5,4 @@ {% assign link_version = page.version.version %} {% endif %} -**This feature is in [preview]({{base_url}}{{link_version}}/cockroachdb-feature-availability.html)** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com/hc/en-us). \ No newline at end of file +**This feature is in [preview]({{base_url}}{{link_version}}/cockroachdb-feature-availability.html)** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com). diff --git a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json index 60a59eeb11c..21e835a4084 100644 --- a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json @@ -30,19 +30,19 @@ ] }, { - "title": "Deploy BYOC in AWS", + "title": "Deploy BYOC on AWS", "urls": [ "/cockroachcloud/byoc-aws-deployment.html" ] }, { - "title": "Deploy BYOC in Azure", + "title": "Deploy BYOC on Azure", "urls": [ "/cockroachcloud/byoc-azure-deployment.html" ] }, { - "title": "Deploy BYOC in GCP", + "title": "Deploy BYOC on GCP", "urls": [ "/cockroachcloud/byoc-gcp-deployment.html" ] diff --git a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json index bf8e063837a..1c822f96cd0 100644 --- a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json @@ -30,19 +30,19 @@ ] }, { - "title": "Deploy BYOC in AWS", + "title": "Deploy BYOC on AWS", "urls": [ "/cockroachcloud/byoc-aws-deployment.html" ] }, { - "title": "Deploy BYOC in Azure", + "title": "Deploy BYOC on Azure", "urls": [ "/cockroachcloud/byoc-azure-deployment.html" ] }, { - "title": "Deploy BYOC in GCP", + "title": "Deploy BYOC on GCP", "urls": [ "/cockroachcloud/byoc-gcp-deployment.html" ] diff --git a/src/current/cockroachcloud/byoc-aws-deployment.md b/src/current/cockroachcloud/byoc-aws-deployment.md index a50eb75c100..1750a70b413 100644 --- a/src/current/cockroachcloud/byoc-aws-deployment.md +++ b/src/current/cockroachcloud/byoc-aws-deployment.md @@ -68,7 +68,7 @@ Follow these steps to create the intermediate IAM role: { "Effect": "Allow", "Principal": { - "AWS": + "AWS": "arn:aws:iam::{AWS Account ID}:example/arn" }, "Action": "sts:AssumeRole" } @@ -232,7 +232,7 @@ Follow these steps to create a CockroachDB cluster in the {{ site.data.products. 1. Click **Create cluster**. 1. Under **Select a plan**, click **{{ site.data.products.advanced }}**. 1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select AWS. -1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the ARN associated with your intermediate IAM role. +1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the ARN associated with the intermediate IAM role that you created, *not* the ARN of the Cockroach Labs IAM role. 1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. ### Create a cluster with the {{ site.data.products.cloud }} API @@ -260,7 +260,7 @@ curl --request POST \ "plan": "ADVANCED", "customer_cloud_account": { "aws": { - "arn": "arn:aws:iam:::user/byoc/CockroachDB-Cloud-managed-BYOC_" + "arn": "arn:aws:iam::{AWS Account ID}:example/arn" } } } @@ -271,4 +271,4 @@ curl --request POST \ - [Connect to your cluster]({% link cockroachcloud/connect-to-an-advanced-cluster.md %}) - [Manage your cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) -- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) \ No newline at end of file +- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) diff --git a/src/current/cockroachcloud/byoc-azure-deployment.md b/src/current/cockroachcloud/byoc-azure-deployment.md index cdb0506ff89..ade8702ba16 100644 --- a/src/current/cockroachcloud/byoc-azure-deployment.md +++ b/src/current/cockroachcloud/byoc-azure-deployment.md @@ -73,7 +73,7 @@ This reader application also requires admin consent to deploy the reader Service {% include_cached copy-clipboard.html %} ~~~ text - https://login.microsoftonline.com//adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028 + https://login.microsoftonline.com/{customer-tenant-id}/adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028 ~~~ 3. Review the requested permissions and click **Accept**. 4. Once the CockroachDB Cloud BYOC Reader App Registration has been granted admin consent in the tenant, grant the following set of roles to the reader Service Principal: @@ -210,7 +210,7 @@ Follow these steps to enable secure, scoped access for Cockroach Labs to your su ~~~ shell az deployment sub create \ --name cockroach-byoc-lighthouse \ - --location \ + --location {region} \ --template-file byoc-lighthouse.json ~~~ @@ -280,4 +280,4 @@ curl --request POST \ - [Connect to your cluster]({% link cockroachcloud/connect-to-an-advanced-cluster.md %}) - [Manage your cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) -- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) \ No newline at end of file +- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md index 2801288e558..f4a4d0f0564 100644 --- a/src/current/cockroachcloud/byoc-gcp-deployment.md +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -28,10 +28,10 @@ The following requirements apply to the GCP project used for your BYOC deploymen ## Step 2. Grant permissions to the Cockroach Labs service account -Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. This requires two service accounts: +Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. This requires two GCP service accounts: - A service account owned by Cockroach Labs which must be granted roles to view and access service accounts in your GCP project. -- An intermediary service account in your GCP project which must be granted roles to create and manage infrasturcture. This service account is the target used by Cockroach Labs for cross-account impersonation. +- An intermediary service account in your GCP project which must be granted roles to create and manage infrasturcture. This service account is the target used by Cockroach Labs for cross-account impersonation, and you specify this service account when creating CockroachDB {{ site.data.products.cloud }} clusters in this organization. In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to collect the email address of the Cockroach Labs service account and grant it the necessary roles. @@ -44,7 +44,7 @@ curl --request GET \ --header 'Authorization: Bearer {secret_key}' ~~~ -Record the value of `cockroach_cloud_service_principals.gcp.service_account_email` in the response: +In the response, the value of `cockroach_cloud_service_principals.gcp.service_account_email` is the Cockroach Labs service account: ~~~ json { @@ -56,7 +56,7 @@ Record the value of `cockroach_cloud_service_principals.gcp.service_account_emai } ~~~ -Grant this service account the following roles in the GCP IAM Console: +Grant this Cockroach Labs service account the following roles in the GCP IAM Console: - `Service Account Token Creator (roles/iam.serviceAccountTokenCreator)` - `View Service Accounts (roles/iam.serviceAccountViewer)` @@ -98,7 +98,7 @@ Follow these steps to create a CockroachDB cluster in the {{ site.data.products. 1. Click **Create cluster**. 1. Under **Select a plan**, click **{{ site.data.products.advanced }}**. 1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select Google Cloud. -1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the service account email associated with your intermediate service account. +1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the service account email associated with the intermediate service account you created, *not* the email address of the Cockroach Labs service account. 1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. ### Create a cluster with the {{ site.data.products.cloud }} API @@ -141,4 +141,4 @@ curl --request POST \ - [Connect to your cluster]({% link cockroachcloud/connect-to-an-advanced-cluster.md %}) - [Manage your cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) -- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) \ No newline at end of file +- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) diff --git a/src/current/cockroachcloud/byoc-overview.md b/src/current/cockroachcloud/byoc-overview.md index 46520cd8675..8ba28990b8b 100644 --- a/src/current/cockroachcloud/byoc-overview.md +++ b/src/current/cockroachcloud/byoc-overview.md @@ -24,16 +24,16 @@ Deployments | Automate cluster provisioning and scaling, provide hardware best p Upgrades | Provide automatic minor/patch upgrades and major upgrade automation via Terraform, APIs, or the {{ site.data.products.cloud }} Console | Initiate [major version upgrades]({% link cockroachcloud/upgrade-cockroach-version.md %}), [set maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) if applicable Workload | Troubleshoot problems as they pertain to cluster availability | [Size clusters]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) to manage workload requirements, [tune performance]({% link {{ site.versions["stable"] }}/performance-recipes.md %}), and adjust schema designs with support from Cockroach Labs Backups | Initialize a default backup schedule and write to customer-owned Cloud storage, ensure backup jobs run successfully | Configure a backup schedule as needed to meet RPO/RTO requirements -Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available, including negotiating cloud resource quotas and availability with your cloud service provider. Maintain appropriate IAM permissions at all times +Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available to prevent scaling issues, including negotiating cloud resource quotas and availability with your cloud service provider. Maintain appropriate IAM permissions at all times Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockroachcloud/costs.md %}) at the per-minute level | Negotiate with cloud service provider, manage infrastructure spend and discounts ## Next steps CockroachDB supports BYOC deployments in Amazon Web Services, Microsoft Azure, and Google Cloud Platform. To prepare your cloud account for a BYOC deployment, refer to the corresponding deployment guide: -- [Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services]({% link cockroachcloud/byoc-aws-deployment.md %}). -- [Prepare a CockroachDB Cloud BYOC Deployment in Azure]({% link cockroachcloud/byoc-azure-deployment.md %}). -- [Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform]({% link cockroachcloud/byoc-gcp-deployment.md %}). +- [Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services]({% link cockroachcloud/byoc-aws-deployment.md %}) +- [Prepare a CockroachDB Cloud BYOC Deployment in Azure]({% link cockroachcloud/byoc-azure-deployment.md %}) +- [Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform]({% link cockroachcloud/byoc-gcp-deployment.md %}) Once your cloud account is prepared for a BYOC deployment, cluster configuration and management is identical to a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster. To learn more about CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster planning and management, refer to the following guides: From 2caee414276f6d778ee3022ec88918b45e33af0c Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Tue, 21 Apr 2026 17:01:03 -0400 Subject: [PATCH 11/12] Clarify CRL GCP service account collection stesps --- .../cockroachcloud/byoc-gcp-deployment.md | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md index f4a4d0f0564..393f15dce32 100644 --- a/src/current/cockroachcloud/byoc-gcp-deployment.md +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -35,31 +35,31 @@ Cockroach Labs uses cross-account service account impersonation to provision and In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to collect the email address of the Cockroach Labs service account and grant it the necessary roles. -Send a `GET` request to the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) similar to the following example: - -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request GET \ - --url https://cockroachlabs.cloud/api/v1/organization \ - --header 'Authorization: Bearer {secret_key}' -~~~ - -In the response, the value of `cockroach_cloud_service_principals.gcp.service_account_email` is the Cockroach Labs service account: - -~~~ json -{ - "cockroach_cloud_service_principals": { - "gcp": { - "service_account_email": "example@email.com" +Follow these steps to identify the Cockroach Labs service account and grant it the necessary roles: + +1. Send a `GET` request to the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) similar to the following example: + {% include_cached copy-clipboard.html %} + ~~~ shell + curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/organization \ + --header 'Authorization: Bearer {secret_key}' + ~~~ + + In the response, the value of `cockroach_cloud_service_principals.gcp.service_account_email` is the email address of the Cockroach Labs service account: + + ~~~ json + { + "cockroach_cloud_service_principals": { + "gcp": { + "service_account_email": "{Cockroach Labs service account}" + } + } } - } -} -~~~ - -Grant this Cockroach Labs service account the following roles in the GCP IAM Console: + ~~~ -- `Service Account Token Creator (roles/iam.serviceAccountTokenCreator)` -- `View Service Accounts (roles/iam.serviceAccountViewer)` +1. Grant this Cockroach Labs service account the following roles in the GCP IAM Console: + - `Service Account Token Creator (roles/iam.serviceAccountTokenCreator)` + - `View Service Accounts (roles/iam.serviceAccountViewer)` ## Step 3. Configure the intermediate service account @@ -105,7 +105,7 @@ Follow these steps to create a CockroachDB cluster in the {{ site.data.products. Send a `POST` request to the the `/v1/clusters` endpoint to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). -The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `us-east1` region, specifying the `service_account_email` associated with the intermediate service account you created: +The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `us-east1` region, specifying the intermediate service account you created in the `service_account_email` field: {% include_cached copy-clipboard.html %} ~~~ shell From 2032025cacddc3991afabf119edf733dfe092b8e Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Wed, 22 Apr 2026 14:23:51 -0400 Subject: [PATCH 12/12] Remove multiple clusters line for AWS --- src/current/cockroachcloud/byoc-aws-deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/cockroachcloud/byoc-aws-deployment.md b/src/current/cockroachcloud/byoc-aws-deployment.md index 1750a70b413..de2d7d54d04 100644 --- a/src/current/cockroachcloud/byoc-aws-deployment.md +++ b/src/current/cockroachcloud/byoc-aws-deployment.md @@ -19,7 +19,7 @@ This page describes how to prepare a cloud service account to host a [BYOC deplo ## Step 1. Create a new AWS account -Provision a new AWS account with no existing infrastructure, dedicated to your CockroachDB {{ site.data.products.cloud }} deployment. The account configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this account, so this step is necessary to isolate these permissions from non-CockroachDB Cloud resources. This account can be reused for multiple CockroachDB clusters. +Provision a new AWS account with no existing infrastructure, dedicated to your CockroachDB {{ site.data.products.cloud }} deployment. The account configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this account, so this step is necessary to isolate these permissions from non-CockroachDB Cloud resources. ## Step 2. Collect the Cockroach Labs IAM role ARN