BYOC public preview docs for Azure/AWS/GCP by jhlodin · Pull Request #23182 · cockroachdb/docs

jhlodin · 2026-04-14T21:10:10Z

Prepare BYOC documentation for public preview

Adds BYOC guides for AWS and GCP
Adds BYOC overview page, shuffle content as needed
Adds instructions for deployment via console UI

https://cockroachlabs.atlassian.net/browse/DOC-15891
https://cockroachlabs.atlassian.net/browse/DOC-15892
https://cockroachlabs.atlassian.net/browse/DOC-15645

github-actions · 2026-04-14T21:10:35Z

Files changed:

src/current/_data/redirects.yml
src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md:

src/current/_includes/feature-phases/preview.md
src/current/_includes/v26.1/sidebar-data/cloud-deployments.json
src/current/_includes/v26.2/sidebar-data/cloud-deployments.json
src/current/cockroachcloud/advanced-cluster-management.md
src/current/cockroachcloud/byoc-aws-deployment.md
src/current/cockroachcloud/byoc-azure-deployment.md
src/current/cockroachcloud/byoc-gcp-deployment.md
src/current/cockroachcloud/byoc-overview.md
src/current/cockroachcloud/create-an-advanced-cluster.md
src/current/cockroachcloud/plan-your-cluster-advanced.md
src/current/v26.1/cockroachdb-feature-availability.md
src/current/v26.2/cockroachdb-feature-availability.md

github-actions · 2026-04-14T21:10:43Z

Diagram Anchor Check: Passed

All sql-grammar.html#anchor references in SQL diagram files resolve correctly against stmt_block.html.

netlify · 2026-04-14T21:39:00Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`30022d2`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/69ea4ddb2d5e20000858bb46

netlify · 2026-04-14T21:39:01Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`30022d2`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/69ea4ddbfbe715000868480f

netlify · 2026-04-14T21:39:10Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`30022d2`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/69ea4ddb3326210008f87b41
😎 Deploy Preview	https://deploy-preview-23182--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

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

nicholas-tao

Console UI docs LGTM. Let me know when these docs go live, as we'll want to update the docs links in the Console UI. They currently point to /byoc-deployment but I think we'll want to point to CSP-specific pages

jhlodin · 2026-04-17T17:31:47Z

Console UI docs LGTM. Let me know when these docs go live, as we'll want to update the docs links in the Console UI. They currently point to /byoc-deployment but I think we'll want to point to CSP-specific pages

@nicholas-tao I have a redirect in place that'll point existing links to /byoc-deployment to /byoc-azure-deployment because that was previously the only guide. If it makes sense to link to a specific cloud provider guide, you'll want /byoc-azure-deployment, /byoc-gcp-deployment, or /byoc-aws-deployment respectively. But if it's a generic "learn more about BYOC" link, or especially if it's a "learn more about the BYOC shared responsibility model" link, you'll want to use the new landing page at /byoc-overview.

nicholas-tao · 2026-04-17T17:32:55Z

Console UI docs LGTM. Let me know when these docs go live, as we'll want to update the docs links in the Console UI. They currently point to /byoc-deployment but I think we'll want to point to CSP-specific pages

@nicholas-tao I have a redirect in place that'll point existing links to /byoc-deployment to /byoc-azure-deployment because that was previously the only guide. If it makes sense to link to a specific cloud provider guide, you'll want /byoc-azure-deployment, /byoc-gcp-deployment, or /byoc-aws-deployment respectively. But if it's a generic "learn more about BYOC" link, or especially if it's a "learn more about the BYOC shared responsibility model" link, you'll want to use the new landing page at /byoc-overview.

@jhlodin Makes sense, thanks for the context!

rgcase · 2026-04-20T17:37:49Z

+
+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.
+
+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:


Find your org label

I don't think we should rely on the structure of this IAM string. The template you show below is how it will look today but I think we should encourage them to just get the entire IAM identifier string from the API response in case we change the format later.

Reworked this step to have the reader collect the ARN with the cloud API. Which also means I needed to make the cloud API setup prerequisite non-optional for AWS.

If we think users will bristle at being told they need to use the API just for this step, we should surface the ARN in the Console somewhere for easy reference.

rgcase · 2026-04-20T17:40:45Z

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


We're missing the lookup of the CRL-owned GCP intermediate service account, similar to the IAM user in AWS. They should look it up using the public API method just like for AWS, and grant two roles on it.

Added a step similar to what I wrote for AWS.

What's the difference from a user's perspective between the CRL-owned intermediate service account and the customer-created intermediate service account? Should be able to say, at a high level, why they're creating each one and giving them their respective roles (but not in so much depth that the customer gets the idea to exclude some roles)

kannanlakshmi

Thanks Joe -- I left somewhat minor comments. I did not carefully review the actual account roles and set up, Ryan or Bill are better suited for that. Thanks!

bsanchez-the-roach

lots of nits with some more substantive comments

bsanchez-the-roach

a few more comments

bsanchez-the-roach · 2026-04-21T19:41:31Z

+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 the intermediate service account you created, *not* the email address of the Cockroach Labs service account.


Suggested change

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. 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.

Bold for emphasis, italics for introducing a new phrase, I believe?

Not currently in the style guide, and because we're already using bold in this line to describe UI elements I don't want to overload bold usage.

bsanchez-the-roach · 2026-04-21T19:42:57Z

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


Could maybe link to this, to help clarify the difference: https://www.cockroachlabs.com/docs/cockroachcloud/managing-access.html#manage-service-accounts

Both of these are GCP service accounts, neither is a CRDB service account. The This requires two GCP service accounts line is my attempt at clarifying that, I'm not sure what more I can do

bsanchez-the-roach · 2026-04-21T19:47:54Z

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


I'd repeat that same clarification here. I'd also maybe avoid using the service_account_email string in this bit of text, as I so associate it with the snippet from Step 2 that I immediately associate it with the CRL service account email address.

We do need to call out the field by name, but reworded to clarify

bsanchez-the-roach · 2026-04-21T19:49:28Z

+{
+  "cockroach_cloud_service_principals": {
+    "gcp": {
+      "service_account_email": "example@email.com"


I don't think that this email address actually gets used, does it? If it's not, I might just remove this bit entirely, as then you won't have to worry about differentiating between the two email addresses later.

As discussed offline, it does - it's the service account that you grant the token creator/view service accounts roles later in this step

bsanchez-the-roach

LGTM

caobill · 2026-04-22T14:37:37Z

+
+## 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.


This account can be reused for multiple CockroachDB clusters.

Can we leave this out for now until we fully release this functionality.

Co-authored-by: bsanchez-the-roach <brandon.sanchez@cockroachlabs.com>

kannanlakshmi · 2026-04-23T17:11:05Z

Thank you! LGTM!

jhlodin force-pushed the jl/doc-15891 branch from 8b9d997 to a70d3d9 Compare April 16, 2026 19:36

jhlodin marked this pull request as ready for review April 16, 2026 21:34

jhlodin changed the title ~~BYOC public preview docs set~~ BYOC public preview docs for Azure/AWS/GCP Apr 16, 2026

nicholas-tao approved these changes Apr 17, 2026

View reviewed changes

rgcase reviewed Apr 20, 2026

View reviewed changes

jhlodin force-pushed the jl/doc-15891 branch from 8840f15 to 2080980 Compare April 20, 2026 17:43

kannanlakshmi reviewed Apr 20, 2026

View reviewed changes

bsanchez-the-roach reviewed Apr 21, 2026

View reviewed changes

jhlodin force-pushed the jl/doc-15891 branch 2 times, most recently from ab9cde7 to d25712d Compare April 21, 2026 19:26

bsanchez-the-roach reviewed Apr 21, 2026

View reviewed changes

bsanchez-the-roach approved these changes Apr 22, 2026

View reviewed changes

caobill reviewed Apr 22, 2026

View reviewed changes

jhlodin and others added 9 commits April 22, 2026 14:24

BYOC public preview docs set

0a59856

Finish instructions

f978b9b

Add UI instructions and overview

bfc592b

Update old links and remove limitations

b3fe5dc

Add missing sidebar entry

fc87c84

Ryan and Lakshmi comments

2115f12

Disambiguate between service accounts

b7cf432

Disambiguate AWS IAM accounts

acdbbd1

Apply suggestions from code review

9681d2b

Co-authored-by: bsanchez-the-roach <brandon.sanchez@cockroachlabs.com>

jhlodin added 3 commits April 22, 2026 14:24

Brandon comments

68dbfed

Clarify CRL GCP service account collection stesps

2caee41

Remove multiple clusters line for AWS

2032025

jhlodin force-pushed the jl/doc-15891 branch from 0563b4f to 2032025 Compare April 22, 2026 18:24

jhlodin added 2 commits April 23, 2026 15:58

Merge branch 'main' into jl/doc-15891

d5b1d28

Merge branch 'main' into jl/doc-15891

30022d2

jhlodin enabled auto-merge (squash) April 23, 2026 16:51

jhlodin merged commit 39b7bb6 into main Apr 23, 2026
7 checks passed

jhlodin deleted the jl/doc-15891 branch April 23, 2026 16:59


		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.

		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:

	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. 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.


		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.


		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:


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

Conversation

jhlodin commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files changed:

Uh oh!

github-actions Bot commented Apr 14, 2026

Diagram Anchor Check: Passed

Uh oh!

netlify Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

netlify Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

netlify Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

nicholas-tao left a comment

Choose a reason for hiding this comment

Uh oh!

jhlodin commented Apr 17, 2026

Uh oh!

nicholas-tao commented Apr 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhlodin Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kannanlakshmi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bsanchez-the-roach left a comment

Choose a reason for hiding this comment

Uh oh!

bsanchez-the-roach left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

jhlodin commented Apr 14, 2026 •

edited

Loading

github-actions Bot commented Apr 14, 2026 •

edited

Loading

netlify Bot commented Apr 14, 2026 •

edited

Loading

netlify Bot commented Apr 14, 2026 •

edited

Loading

netlify Bot commented Apr 14, 2026 •

edited

Loading

jhlodin Apr 20, 2026 •

edited

Loading