Skip to content

Commit a2e7aea

Browse files
bsod90bsod90
authored
docs: more detailed GCP BYOC installation doc (#10167)
1 parent 268aa93 commit a2e7aea

File tree

1 file changed

+111
-32
lines changed

1 file changed

+111
-32
lines changed

‎docs/pages/product/deployment/cloud/byoc/gcp/deployment.mdx‎

Lines changed: 111 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -7,37 +7,85 @@ This document provides step-by-step instructions for deploying Cube Cloud BYOC o
77
## Prerequisites
88

99
The bulk of provisioning work will be done remotely by Cube Cloud automation.
10-
However, to get started, you'll need to provide Cube with the necessary access
11-
along with some additional information that includes:
10+
However, to get started, you'll need:
11+
12+
### Required Information
1213

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

18-
In addition to that, you'll need to make sure you have sufficient access to grant
19-
IAM permissions in the dedicated project to allow Cube Cloud to:
20-
- Create and manage VPC networking
21-
- Create and manage GKE clusters
22-
- Create and manage Cloud Storage buckets
23-
- Create and manage Cloud DNS zones
24-
- Create and manage service accounts
25-
- Configure IAM permissions for resources
26-
- Read from Artifact Registry
19+
### Required Permissions
20+
21+
You'll need to have the following permissions in your GCP organization/folder to complete the setup:
22+
23+
- **Project Creator** (`roles/resourcemanager.projectCreator`) - To create a new dedicated project
24+
- **Project IAM Admin** (`roles/resourcemanager.projectIamAdmin`) - To grant permissions in the project
25+
- **Billing Account User** (`roles/billing.user`) - To link billing to the new project
26+
27+
If you don't have these permissions, contact your GCP organization administrator.
2728

2829
## Provisioning access
2930

30-
### Create a dedicated GCP project
31+
### Step 1: Create a dedicated GCP project
3132

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

36-
Navigate to the [GCP Console][gcp-console] and create a new project for Cube Cloud BYOC.
37-
Note the **Project ID** (not the project name) as you'll need it for the next steps
38-
and to share with your Cube contact point.
37+
1. Navigate to the [GCP Console][gcp-console]
38+
2. Click **Create Project**
39+
3. Enter a project name (e.g., "cube-cloud-byoc")
40+
4. Note the **Project ID** (not the project name) - you'll need this for subsequent steps
41+
5. Select your billing account
42+
6. Click **Create**
43+
44+
<InfoBox>
45+
Make sure billing is enabled for the project. You can verify this by navigating to
46+
**Billing** in the GCP Console and confirming the project is linked to an active billing account.
47+
</InfoBox>
48+
49+
### Step 2: Enable required APIs
50+
51+
Before granting permissions, enable the necessary GCP APIs in your dedicated project.
52+
This ensures that subsequent API calls will work correctly.
53+
54+
**Required APIs:**
55+
56+
- **Compute Engine API** (`compute.googleapis.com`) - For VPC networks and compute resources
57+
- **Kubernetes Engine API** (`container.googleapis.com`) - For GKE clusters
58+
- **Cloud Storage API** (`storage.googleapis.com`) - For Cube Store buckets
59+
- **IAM API** (`iam.googleapis.com`) - For service account management
60+
- **Cloud Resource Manager API** (`cloudresourcemanager.googleapis.com`) - For project IAM operations
61+
- **Service Networking API** (`servicenetworking.googleapis.com`) - For private service connectivity
62+
63+
<InfoBox>
64+
65+
**Note:** DNS and Artifact Registry APIs are not required in your project. Cube manages DNS in its own project,
66+
and container images are pulled from Cube's Artifact Registry using Cube-provided credentials.
67+
68+
</InfoBox>
69+
70+
You can enable these APIs through the [API Library][gcp-api-library] in the GCP Console,
71+
or use the `gcloud` command:
72+
73+
```bash
74+
# Set your project ID
75+
export PROJECT_ID="your-cube-byoc-project-id"
76+
77+
# Enable all required APIs
78+
gcloud services enable \
79+
compute.googleapis.com \
80+
container.googleapis.com \
81+
storage.googleapis.com \
82+
iam.googleapis.com \
83+
cloudresourcemanager.googleapis.com \
84+
servicenetworking.googleapis.com \
85+
--project=$PROJECT_ID
86+
```
3987

40-
### Grant IAM permissions
88+
### Step 3: Grant IAM permissions
4189

4290
In order to manage resources in the Cube-dedicated GCP project, Cube Cloud Service Principal
4391
needs to be granted administrative permissions to a set of services.
@@ -53,16 +101,17 @@ binding for the Cube Cloud service account:
53101
- **Kubernetes Engine Admin** (`roles/container.admin`) - Allows creation and management of GKE clusters and node pools
54102
- **Storage Admin** (`roles/storage.admin`) - Allows creation and management of Cloud Storage buckets for Cube Store
55103
- **Service Account Admin** (`roles/iam.serviceAccountAdmin`) - Allows creation and management of service accounts for cluster nodes and workload identity
104+
- **Service Account Key Admin** (`roles/iam.serviceAccountKeyAdmin`) - Allows creation and management of service account keys for Cube Store authentication
56105
- **Project IAM Admin** (`roles/resourcemanager.projectIamAdmin`) - Allows granting IAM permissions to created resources (e.g., bucket access for service accounts)
57106

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

61110
```bash
62-
# Set your project ID
111+
# Set your project ID (replace with your actual project ID)
63112
export PROJECT_ID="your-cube-byoc-project-id"
64113

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

68117
# Grant all required roles
@@ -82,33 +131,63 @@ gcloud projects add-iam-policy-binding $PROJECT_ID \
82131
--member="serviceAccount:$CUBE_SA" \
83132
--role="roles/iam.serviceAccountAdmin"
84133

134+
gcloud projects add-iam-policy-binding $PROJECT_ID \
135+
--member="serviceAccount:$CUBE_SA" \
136+
--role="roles/iam.serviceAccountKeyAdmin"
137+
85138
gcloud projects add-iam-policy-binding $PROJECT_ID \
86139
--member="serviceAccount:$CUBE_SA" \
87140
--role="roles/resourcemanager.projectIamAdmin"
88141
```
89142

90-
### Enable required APIs
143+
### Step 4: Grant Service Account User permissions
91144

92-
Ensure the following GCP APIs are enabled in your dedicated project:
145+
Additionally, the Cube Cloud service account needs permission to use the default Compute Engine service account for GKE node pools.
93146

94-
- Compute Engine API (`compute.googleapis.com`)
95-
- Kubernetes Engine API (`container.googleapis.com`)
96-
- Cloud Storage API (`storage.googleapis.com`)
97-
- IAM API (`iam.googleapis.com`)
98-
- Service Networking API (`servicenetworking.googleapis.com`)
147+
<InfoBox>
99148

100-
You can enable these APIs through the [API Library][gcp-api-library] in the GCP Console,
101-
or use the `gcloud` command:
149+
Make sure you have the `PROJECT_ID` and `CUBE_SA` environment variables set from Step 3 before running these commands.
150+
151+
</InfoBox>
152+
153+
Run the following command to grant the necessary permissions:
102154

103155
```bash
104-
gcloud services enable compute.googleapis.com \
105-
container.googleapis.com \
106-
storage.googleapis.com \
107-
iam.googleapis.com \
108-
servicenetworking.googleapis.com \
156+
# Get the project number
157+
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
158+
159+
# Grant the Cube service account permission to use the default compute service account
160+
gcloud iam service-accounts add-iam-policy-binding \
161+
${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
162+
--member="serviceAccount:$CUBE_SA" \
163+
--role="roles/iam.serviceAccountUser" \
164+
--project=$PROJECT_ID
165+
```
166+
167+
This allows the Cube Cloud service account to create GKE clusters that use the project's default compute service account for worker nodes.
168+
169+
### Step 5: Verify setup
170+
171+
Before notifying Cube, verify that all permissions and APIs are correctly configured:
172+
173+
```bash
174+
# Verify APIs are enabled
175+
gcloud services list --enabled --project=$PROJECT_ID | grep -E '(compute|container|storage|iam|cloudresourcemanager|servicenetworking)'
176+
177+
# Verify IAM bindings for the Cube service account
178+
gcloud projects get-iam-policy $PROJECT_ID \
179+
--flatten="bindings[].members" \
180+
--format="table(bindings.role)" \
181+
--filter="bindings.members:serviceAccount:cube-cloud-byoc-installer@cube-cloud-byoc.iam.gserviceaccount.com"
182+
183+
# Verify Service Account User permission
184+
gcloud iam service-accounts get-iam-policy \
185+
${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
109186
--project=$PROJECT_ID
110187
```
111188

189+
If all commands return the expected results, you're ready to proceed with deployment.
190+
112191
## Deployment
113192

114193
The actual deployment will be done by Cube Cloud automation. All that's left to

0 commit comments

Comments
 (0)