Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform

On this page

This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB Cloud Advanced in Google Cloud Platform (GCP).

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 Cloud API with your Cloud organization.

Step 1. Create a new GCP project

Provision a fresh GCP project with no existing infrastructure, dedicated to your CockroachDB 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-CockroachDB 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. Grant permissions to 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.
• 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.

In this step, use the Cloud API to collect the email address of the Cockroach Labs service account and grant it the necessary roles.

Follow these steps to identify the Cockroach Labs service account and grant it the necessary roles:

1. Send a GET request to the /v1/organization endpoint of the CockroachDB Cloud API 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

In this step, create the intermediate service account in your GCP project and grant it the necessary roles in your GCP project.

Follow these steps to create 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

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:

1. Open the 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 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 intermediate service account you created in the service_account_email field:

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

Next steps

• Connect to your cluster
• Manage your cluster using the Cloud API
• Prepare your deployment for production