Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform

​

Prerequisites

• Review the . 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.
• if you do not already have one.
• More than one BYOC cluster can run in a single GCP project. However, if the project contains a BYOC cluster created before multiple-cluster support was enabled, that cluster must be deleted or its data migrated before additional clusters can be created in the same project.
• 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 documentation to plan your cluster sizing and resource allocation.
• Review cloud service regions supported by .
• The GCP project must not contain resources that can affect the control plane’s ability to operate on CockroachDB clusters.
• Create an to use the with your CockroachDB Cloud organization.

​

Step 1. Create a new GCP project

• 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. Grant permissions to the Cockroach Labs service account

• 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, and you specify this service account when creating CockroachDB Cloud clusters in this organization.

1. Send a GET request to the /v1/organization endpoint of the similar to the following example:
   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:
   {
     "cockroach_cloud_service_principals": {
       "gcp": {
         "service_account_email": "{Cockroach Labs service account}"
       }
     }
   }
   
2. 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

1. Open the GCP IAM Console.
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)
   • 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 4. Create the CockroachDB Cloud cluster

​

Create a cluster with the CockroachDB Cloud Console

1. Open the CockroachDB Cloud 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 Google Cloud.
5. 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.
6. Follow the rest of the Create Cluster steps to configure your cluster’s regions, capacity, and features as desired. Read the documentation for more details.

​

Create a cluster with the CockroachDB Cloud API

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
            }
          }
        }
      }'

​

Create additional BYOC clusters

​

Delete a BYOC cluster

​

Verify that deletion is complete

​

Reuse the GCP project

​

Next steps