> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services
export const InternalLink = ({version, path = "", children, ...props}) => {
let detectedVersion = version || "stable";
if (typeof window !== 'undefined' && !version) {
const match = window.location.pathname.match(/\/docs\/([^/]+)/);
if (match) {
detectedVersion = match[1];
}
}
const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
return
{children}
;
};
**This feature is in preview** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com).
This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB Cloud Advanced in Amazon Web Services (AWS).
## Prerequisites
* Review the 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 Cloud organization if you do not already have one.
* The BYOC deployment option is not available by default and must be requested. Reach out to your account team to express interest in BYOC.
* Once your cloud account is prepared for a CockroachDB BYOC deployment, cluster configuration and management is identical to a CockroachDB Cloud Advanced cluster. Review the Plan a CockroachDB Advanced Cluster documentation to plan your cluster sizing and resource allocation.
* Review cloud service regions supported by CockroachDB Cloud Advanced.
* Create an API service account to use the CockroachDB Cloud API with your CockroachDB Cloud organization.
* The AWS account must not contain a BYOC cluster created before 27 July 2026. More than one BYOC cluster can run in a single AWS account, but any BYOC clusters created before this date must be deleted or their data migrated before additional clusters can be created in the same account.
* The AWS account must not contain resources that can affect the control plane's ability to operate on CockroachDB clusters.
## Step 1. Create a new AWS account
Provision a new **AWS account** dedicated to CockroachDB infrastructure. 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 and allow Cockroach Labs to meet cluster uptime SLAs. This account can be reused for multiple CockroachDB clusters.
## Step 2. Collect the Cockroach Labs IAM role ARN
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 CockroachDB Cloud API 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 Cloud API similar to the following example:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
--url https://cockroachlabs.cloud/api/v1/organization \
--header 'Authorization: Bearer {secret_key}'
```
Record the value of `cockroach_cloud_service_principals.aws.user_arn` in the response:
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
"cockroach_cloud_service_principals": {
"aws": {
"user_arn": "arn:aws:iam::{AWS Account ID}:example/arn"
}
}
}
```
## Step 3. Create intermediary IAM role and apply permissions
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.
This permission policy is the minimum required for Cockroach Labs to provision, operate, patch, back up, and heal your cluster over its full lifecycle. This is not a temporary permission set used only at time of creation.
Do not remove, narrow, or add conditions to these permissions after setup, or use Resource Control Policies (RCPs) against this account that may affect control plane operations. Many of these are exercised only during a specific lifecycle event, such as replacing a failed node, applying a patch, rotating an encryption key, or running a managed backup. Removing a permission might not cause an immediate error. A later operation that requires it, such as replacing a failed node or running a backup, can fail. Reducing the permission set voids the availability commitment for the cluster.
Guardrails that restrict the account to particular regions or services, without touching the permissions the deployment requires, are compatible. Conditional or time-bounded policies, and service control policies that restrict this permission set, are not supported.
Follow these steps to create the intermediate IAM role:
1. Open the AWS IAM console.
2. Create a new role. You can choose any name for this role. In these instructions the example role is named `CRLBYOCAdmin`.
3. Use the following trust relationship policy for the new role, using the ARN collected in the previous step:
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::{AWS Account ID}:example/arn"
},
"Action": "sts:AssumeRole"
}
]
}
```
4. Apply an IAM policy to the intermediate role granting the following list of permissions:
```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
// 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:CreateVpcEndpointServiceConfiguration",
"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 in which you plan to create your cluster.
## Step 5. Create the CockroachDB Cloud cluster
In BYOC deployments, CockroachDB clusters can be deployed in the CockroachDB Cloud Console or with the CockroachDB Cloud API.
### Create a cluster with the CockroachDB Cloud Console
Follow these steps to create a CockroachDB cluster in the CockroachDB Cloud console:
1. Open the CockroachDB Cloud Console and select the organization that has been enabled for BYOC.
2. Click **Create cluster**.
3. Under **Select a plan**, click **Advanced**.
4. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select AWS.
5. 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.
6. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the Plan a CockroachDB Advanced Cluster documentation for more details.
### Create a cluster with the CockroachDB Cloud API
Send a `POST` request to the the `/v1/clusters` endpoint to create a CockroachDB Cloud Advanced cluster.
The following example request creates a 3-node Advanced cluster in the `us-east-2` region, specifying the ARN associated with your intermediate IAM role:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request POST \
--url https://cockroachlabs.cloud/api/v1/clusters \
--header 'Authorization: Bearer {secret_key}' \
--json '{
"name": "byoc-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::{AWS Account ID}:example/arn"
}
}
}
}'
```
## Create additional BYOC clusters
An AWS account prepared for BYOC can support multiple CockroachDB Cloud clusters. To create an additional BYOC cluster in the same account, follow the [Create the CockroachDB Cloud cluster](#step-5-create-the-cockroachdb-cloud-cluster) steps again. If you need to deploy the new cluster in non-AWS default regions, follow the [Enable additional regions](#step-4-optional-enable-additional-regions) step.
## Delete a BYOC cluster
To delete a BYOC cluster, delete the cluster from the CockroachDB Cloud Console or with the CockroachDB Cloud API. Deleting the cluster is permanent and cannot be undone.
When you delete a BYOC cluster, Cockroach Labs removes the managed resources that it provisioned in your AWS account for the cluster.
The intermediary IAM role you created during setup is not removed automatically and remains under your control. You can remove it once deletion is complete.
Do not remove the intermediary IAM role or its permissions before deletion has finished. Cockroach Labs needs them to remove the managed resources from your AWS account. Removing access early can leave resources behind that you will need to clean up manually, and that will continue to incur charges from your cloud provider.
### Verify that deletion is complete
After the cluster reports as deleted in the CockroachDB Cloud Console, verify that no managed resources remain in your AWS account. Review the AWS services covered by the permission set in Step 3 (for example, EC2, EKS, S3, and CloudWatch Logs) for resources associated with the cluster. If resources remain, contact your Cockroach Labs account team before removing them manually.
### Reuse the AWS account
Before you reuse the AWS account for a subsequent BYOC deployment, verify that deletion of the previous cluster is complete and contact your Cockroach Labs account team to confirm that the account is ready for reuse.
## Next steps
* Connect to your cluster
* Manage your cluster using the CockroachDB Cloud API
* Prepare your deployment for production