This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB Cloud Advanced in Google Cloud Platform (GCP).
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 GCP project
Provision a fresh GCP project with no existing infrastructure, dedicated to your Cockroach 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 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
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:
- Open the GCP IAM Console.
- Create a new service account. The name is arbitrary but be sure to note down the email address of the account.
- 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)
Step 3. 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 Google Cloud.
- Under Cloud account, click Select your cloud account > Add new cloud account. Enter the service account email associated with your intermediate service account.
- 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-east1 region, specifying the service_account_email associated with the intermediate service account you created:
curl --request POST \
--url https://cockroachlabs.cloud/api/v1/clusters \
--header "Authorization: Bearer {secret_key}" \
--json '{
"name": "byoc-gcp-cluster-1",
"plan": "ADVANCED",
"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
}
}
}
}'
