> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform

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 <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

**This feature is in <InternalLink path="cockroachdb-feature-availability">preview</InternalLink>** 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 <InternalLink path="byoc-overview">BYOC deployment</InternalLink> of CockroachDB CockroachDB Cloud Advanced in Google Cloud Platform (GCP).

## Prerequisites

* Review the <InternalLink path="byoc-overview#shared-responsibility-model-for-byoc">shared responsibility model for BYOC</InternalLink>. 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.

* <InternalLink path="create-an-account">Create a CockroachDB Cloud organization</InternalLink> 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 <InternalLink path="plan-your-cluster-advanced">Plan a CockroachDB Advanced Cluster</InternalLink> documentation to plan your cluster sizing and resource allocation.

* Review cloud service regions supported by <InternalLink path="regions?filters=advanced">CockroachDB Cloud Advanced</InternalLink>.

* Create an <InternalLink path="managing-access#create-api-keys">API service account</InternalLink> to use the <InternalLink path="cloud-api">CockroachDB Cloud API</InternalLink> with your CockroachDB Cloud organization.

## Step 1. Create a new GCP project

Provision a fresh **GCP project** with no existing infrastructure, dedicated to your CockroachDB 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](https://docs.cloud.google.com/endpoints/docs/openapi/enable-api) 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 CockroachDB Cloud clusters in this organization.

In this step, use the <InternalLink path="cloud-api">CockroachDB Cloud API</InternalLink> 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 <InternalLink version="api" path="cloud/v1/organizations/get-information-about-the-callers-organization">CockroachDB CockroachDB Cloud API</InternalLink> 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}'
   ```

   In the response, the value of `cockroach_cloud_service_principals.gcp.service_account_email` is the email address of the Cockroach Labs service account:

   ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   {
     "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 CockroachDB Cloud cluster

In BYOC deployments, CockroachDB clusters can be deployed in the CockroachDB Cloud Console or with the <InternalLink path="cloud-api">CockroachDB Cloud API</InternalLink>.

### 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 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 <InternalLink path="plan-your-cluster-advanced">Plan a CockroachDB Advanced Cluster</InternalLink> documentation for more details.

### Create a cluster with the CockroachDB Cloud API

Send a `POST` request to the the `/v1/clusters` endpoint to <InternalLink path="cloud-api#create-an-advanced-cluster">create a CockroachDB CockroachDB Cloud Advanced cluster</InternalLink>.

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:

```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-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

* <InternalLink path="connect-to-an-advanced-cluster">Connect to your cluster</InternalLink>
* <InternalLink path="cloud-api">Manage your cluster using the CockroachDB Cloud API</InternalLink>
* <InternalLink path="production-checklist">Prepare your deployment for production</InternalLink>