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

# Bring Your Own Cloud on GCP

> Project setup, permissions, and provisioning flow for deploying Cube BYOC inside a dedicated GCP project.

With Bring Your Own Cloud (BYOC) on Google Cloud Platform (GCP), all the components interacting with private data are deployed on
the customer infrastructure on GCP and managed by the Cube Control Plane via the Cube Operator.
This document provides step-by-step instructions for deploying Cube BYOC on GCP.

## Prerequisites

The bulk of provisioning work will be done remotely by Cube automation.
However, to get started, you'll need:

### Required Information

* **GCP Project ID:** A dedicated GCP project ID that will exclusively host Cube-managed infrastructure.
  This should be a new, isolated project created specifically for Cube BYOC.
* **GCP Region:** [The GCP region][gcp-docs-regions] where the BYOC resources
  should be deployed.

### Required Permissions

You'll need to have the following permissions in your GCP organization/folder to complete the setup:

* **Project Creator** (`roles/resourcemanager.projectCreator`) - To create a new dedicated project
* **Project IAM Admin** (`roles/resourcemanager.projectIamAdmin`) - To grant permissions in the project
* **Billing Account User** (`roles/billing.user`) - To link billing to the new project

If you don't have these permissions, contact your GCP organization administrator.

## Provisioning access

### Step 1: Create a dedicated GCP project

We strongly recommend creating a dedicated GCP project that will exclusively host
Cube-managed infrastructure. This project isolation approach simplifies permission
management and provides clear resource boundaries.

1. Navigate to the [GCP Console][gcp-console]
2. Click **Create Project**
3. Enter a project name (e.g., "cube-cloud-byoc")
4. Note the **Project ID** (not the project name) - you'll need this for subsequent steps
5. Select your billing account
6. Click **Create**

<Info>
  Make sure billing is enabled for the project. You can verify this by navigating to
  **Billing** in the GCP Console and confirming the project is linked to an active billing account.
</Info>

### Step 2: Enable required APIs

Before granting permissions, enable the necessary GCP APIs in your dedicated project.
This ensures that subsequent API calls will work correctly.

**Required APIs:**

* **Compute Engine API** (`compute.googleapis.com`) - For VPC networks and compute resources
* **Kubernetes Engine API** (`container.googleapis.com`) - For GKE clusters
* **Cloud Storage API** (`storage.googleapis.com`) - For Cube Store buckets
* **IAM API** (`iam.googleapis.com`) - For service account management
* **Cloud Resource Manager API** (`cloudresourcemanager.googleapis.com`) - For project IAM operations
* **Service Networking API** (`servicenetworking.googleapis.com`) - For private service connectivity

<Info>
  **Note:** DNS and Artifact Registry APIs are not required in your project. Cube manages DNS in its own project,
  and container images are pulled from Cube's Artifact Registry using Cube-provided credentials.
</Info>

You can enable these APIs through the [API Library][gcp-api-library] in the GCP Console,
or use the `gcloud` command:

```bash theme={"dark"}
# Set your project ID
export PROJECT_ID="your-cube-byoc-project-id"

# Enable all required APIs
gcloud services enable \
  compute.googleapis.com \
  container.googleapis.com \
  storage.googleapis.com \
  iam.googleapis.com \
  cloudresourcemanager.googleapis.com \
  servicenetworking.googleapis.com \
  --project=$PROJECT_ID
```

### Step 3: Grant IAM permissions

In order to manage resources in the Cube-dedicated GCP project, the Cube service principal
needs to be granted administrative permissions to a set of services.

Navigate to **IAM & Admin > IAM** in your dedicated project and add the following IAM
binding for the Cube service account:

**Principal:** `cube-cloud-byoc-installer@cube-cloud-byoc.iam.gserviceaccount.com`

**Roles:**

* **Compute Admin** (`roles/compute.admin`) - Allows creation and management of VPC networks, subnets, routers, NAT gateways, firewall rules, IP addresses, and Private Service Connect endpoints
* **Kubernetes Engine Admin** (`roles/container.admin`) - Allows creation and management of GKE clusters and node pools
* **Storage Admin** (`roles/storage.admin`) - Allows creation and management of Cloud Storage buckets for Cube Store
* **Service Account Admin** (`roles/iam.serviceAccountAdmin`) - Allows creation and management of service accounts for cluster nodes and workload identity
* **Service Account Key Admin** (`roles/iam.serviceAccountKeyAdmin`) - Allows creation and management of service account keys for Cube Store authentication
* **Project IAM Admin** (`roles/resourcemanager.projectIamAdmin`) - Allows granting IAM permissions to created resources (e.g., bucket access for service accounts)

You can grant these permissions through the Google Cloud Console UI or using the
`gcloud` command-line tool:

```bash theme={"dark"}
# Set your project ID (replace with your actual project ID)
export PROJECT_ID="your-cube-byoc-project-id"

# Set the Cube service account (use this exact value)
export CUBE_SA="cube-cloud-byoc-installer@cube-cloud-byoc.iam.gserviceaccount.com"

# Grant all required roles
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/compute.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/container.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/iam.serviceAccountAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/iam.serviceAccountKeyAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/resourcemanager.projectIamAdmin"
```

### Step 4: Grant Service Account User permissions

Additionally, the Cube service account needs permission to use the default Compute Engine service account for GKE node pools.

<Info>
  Make sure you have the `PROJECT_ID` and `CUBE_SA` environment variables set from Step 3 before running these commands.
</Info>

Run the following command to grant the necessary permissions:

```bash theme={"dark"}
# Get the project number
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# Grant the Cube service account permission to use the default compute service account
gcloud iam service-accounts add-iam-policy-binding \
  ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/iam.serviceAccountUser" \
  --project=$PROJECT_ID
```

This allows the Cube service account to create GKE clusters that use the project's default compute service account for worker nodes.

### Step 5: Verify setup

Before notifying Cube, verify that all permissions and APIs are correctly configured:

```bash theme={"dark"}
# Verify APIs are enabled
gcloud services list --enabled --project=$PROJECT_ID | grep -E '(compute|container|storage|iam|cloudresourcemanager|servicenetworking)'

# Verify IAM bindings for the Cube service account
gcloud projects get-iam-policy $PROJECT_ID \
  --flatten="bindings[].members" \
  --format="table(bindings.role)" \
  --filter="bindings.members:serviceAccount:cube-cloud-byoc-installer@cube-cloud-byoc.iam.gserviceaccount.com"

# Verify Service Account User permission
gcloud iam service-accounts get-iam-policy \
  ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
  --project=$PROJECT_ID
```

If all commands return the expected results, you're ready to proceed with deployment.

## Deployment

The actual deployment will be done by Cube automation. All that's left to
do is notify your Cube contact point that access has been granted, and pass
along your GCP Project ID and Region information.

After deployment, Cube will manage the following resources in your dedicated project:

* A VPC network with subnets, Cloud Router, and Cloud NAT for outbound connectivity
* A GKE cluster with node pools for running Cube applications
* Cloud Storage buckets for Cube Store data
* Service accounts and IAM bindings for secure resource access
* Firewall rules and network policies for security

[gcp-console]: https://console.cloud.google.com/

[gcp-docs-regions]: https://cloud.google.com/compute/docs/regions-zones

[gcp-api-library]: https://console.cloud.google.com/apis/library