> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/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 version="releases" 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 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.

* 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 <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>.

* The GCP project must not contain resources that can affect the control plane's ability to operate on CockroachDB clusters.

* 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** dedicated to CockroachDB infrastructure. 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 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 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.

<Danger>
  This permission policy is the minimum required for Cockroach Labs to provision, operate, patch, back up, and heal your cluster over its full lifecycle. This is not a temporary permission set used only at time of creation.

  Do not remove, narrow, or add conditions to these permissions after setup. Many of these are exercised only during a specific lifecycle event, such as replacing a failed node, applying a patch, rotating an encryption key, or running a managed backup. These permissions are required throughout the cluster's lifecycle. Removing a permission might not cause an immediate error. A later operation that requires it, such as replacing a failed node or running a backup, can fail. Reducing the permission set voids the availability commitment for the cluster.

  Guardrails that restrict the account to particular regions or services, without touching the permissions the deployment requires, are compatible. Organization policies that restrict this permission set are not supported.
</Danger>

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

## Create additional BYOC clusters

A GCP project prepared for BYOC can support multiple CockroachDB Cloud clusters. To create an additional BYOC cluster in the same account, follow the [Create the CockroachDB Cloud cluster](#step-4-create-the-cockroachdb-cloud-cluster) steps again.

## Delete a BYOC cluster

To delete a BYOC cluster, delete the cluster from the <InternalLink path="advanced-cluster-management#delete-cluster">CockroachDB Cloud Console</InternalLink> or with the <InternalLink version="api" path="cloud/v1/clusters/delete-a-cluster-and-all-of-its-data">CockroachDB Cloud API</InternalLink>. Deleting the cluster is permanent and cannot be undone.

When you delete a BYOC cluster, Cockroach Labs removes the managed resources that it provisioned in your GCP project for the cluster.

The intermediate service account you created during setup is not removed automatically and remains under your control. You can remove it once deletion is complete.

<Danger>
  Do not remove the intermediate service account or its permissions before deletion has finished. Cockroach Labs needs them to remove the managed resources from your GCP project. Removing access early can leave resources behind that you will need to clean up manually, and that will continue to incur charges from your cloud provider.
</Danger>

### Verify that deletion is complete

After the cluster reports as deleted in the CockroachDB Cloud Console, verify that no managed resources remain in your GCP project. Review the GCP services covered by the IAM roles in Step 3 (for example, Compute Engine, Google Kubernetes Engine, and Cloud Storage) for resources associated with the cluster. If resources remain, contact your Cockroach Labs account team before removing them manually.

### Reuse the GCP project

Before you reuse the GCP project for a subsequent BYOC deployment, verify that deletion of the previous cluster is complete and contact your Cockroach Labs account team to confirm that the project is ready for reuse.

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