This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB Cloud Advanced in Amazon Web Services (AWS).
The BYOC Cloud deployment option is currently in Preview.
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.
(Optional) Create an API service account to use the Cloud API with your 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 Advanced Cluster documentation to plan your cluster sizing and resource allocation.
Review cloud service regions supported by CockroachDB Cloud Advanced.
Step 1. Create a new AWS account
Provision a new AWS account with no existing infrastructure, dedicated to your Cockroach 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 Cloud organization label to determine the Amazon Resource Name (ARN) of this IAM role.
Find your org label in the CockroachDB Cloud Console or by using the /v1/organization endpoint of the CockroachDB Cloud API with a GET request similar to the following example:
curl --request GET \
--url https://cockroachlabs.cloud/api/v1/organization \
--header 'Authorization: Bearer {secret_key}'
Record the ARN of your organization's intermediate IAM role using the following schema:
arn:aws:iam::<AWS Account ID>:user/byoc/CockroachDB-Cloud-managed-BYOC_<org-label>
For example, if your organization’s org label is org-32222 then record your ARN as follows:
~~~
arn:aws:iam::
Step 3. Create IAM role for Cockroach Labs access
Follow these steps to create the intermediate IAM role and grant the necessary permissions:
- Open the AWS IAM console.
- Create a new role. This name is arbitrary, in these instructions the role is named
CRLBYOCAdmin. Use the following trust relationship policy for the new role, using the ARN collected in the previous step:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": <intermediate IAM user's ARN> }, "Action": "sts:AssumeRole" } ] }Apply an IAM policy to the intermediate role granting the following list of permissions:
// 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 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 Cloud cluster
In BYOC deployments, CockroachDB clusters can be deployed in the Cloud Console or with the Cloud API.
Create a cluster with the Cloud Console
Follow these steps to create a CockroachDB cluster in the Cloud console:
- Open the Cloud and select the organization that has been enabled for BYOC.
- Click Create cluster
- Under Select a plan, click **Advanced.
- Under Cloud & Regions, click Bring Your Own Cloud and select AWS.
- Under Cloud account, click Select your cloud account > Add new cloud account. Enter the ARN associated with your intermediate IAM role.
- 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 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:
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>:user/byoc/CockroachDB-Cloud-managed-BYOC_<org-label>"
}
}
}
}'
