Docs: document GCP Shared VPC for BYOC bring-your-own-VPC - #119881
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Workflow [PR], commit [13c39bb] Summary: ✅ AI ReviewSummaryThis PR updates the GCP bring-your-own-VPC onboarding page to document Shared VPC host-project setups, the new Secondary range names and Shared VPC host project ID console fields, and the refreshed screenshot. I checked the current diff against the page, the updated image, the related BYOC GCP networking docs, and the referenced Missing context / blind spots
Final Verdict✅ No new findings. |
clickhouse-gh
Bot
added
the
pr-documentation
![clickhouse-gh[bot]](https://avatars.githubusercontent.com/in/928874?s=60&v=4){kind=small}
There was a problem hiding this comment.
Note
Copilot was unable to run its full agentic suite in this review.
Pull request overview
Documents GCP Shared VPC support for BYOC (“bring-your-own-VPC”) onboarding by expanding the existing-VPC console instructions and adding a Shared VPC host-project section.
Changes:
- Adds console fields for Secondary range names and Shared VPC host project ID in the “Set up BYOC infrastructure” step.
- Introduces a “Shared VPC from a host project” section describing prerequisites, required Terraform inputs, and host-project IAM grants.
- Notes PSC subnet placement guidance for Shared VPC setups.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| | Grant on the host project | Granted to | Why | | ||
| |---|---|---| | ||
| | `compute.networks.get`, `compute.subnetworks.get`, `compute.subnetworks.use` | ClickHouse management service account | Read your network and subnet, and let the Private Service Connect attachment use your PSC subnet | | ||
| | `roles/compute.networkUser` on the subnet | ClickHouse management service account, your service project's GKE service agent, and your service project's Google APIs service account | The three identities that consume the subnet | | ||
| | `roles/container.hostServiceAgentUser` | Your service project's GKE service agent | Required for any Shared VPC GKE cluster | | ||
| | `compute.firewalls.create`, `compute.firewalls.delete`, `compute.firewalls.get`, `compute.firewalls.list`, `compute.firewalls.update`, and `compute.networks.updatePolicy` | Your service project's GKE service agent | Under Shared VPC, GKE creates its cluster and load-balancer firewall rules in the host project rather than the service project. Without this the internal load balancer health-check rule is never created, ingress backends stay unhealthy, and private link does not work. This is Google's documented granular alternative to granting `roles/compute.securityAdmin`. | |
There was a problem hiding this comment.
Thanks for looking, but I don't think this one holds — declining it.
I decoded the file at the current head (13c39bbedb5b) and checked the raw bytes rather than the rendered diff. Every table line has a single leading pipe, and there is no || sequence anywhere in the file. Six lines total: one header, one separator, four body rows, three columns throughout.
| Grant on the host project | Granted to | Why |
|---|---|---|
| `compute.networks.get`, ... | ClickHouse management service account | ... |
| `roles/compute.networkUser` on the node subnet | ... | ... |
| `roles/container.hostServiceAgentUser` | Your service project's GKE service agent | ... |
| `compute.firewalls.create`, ... | Your service project's GKE service agent | ... |
Docs check (Mintlify) and Style check have also passed over this table on several commits, and the Mintlify preview renders it as three columns.
My guess is that the double pipe is the boundary between two adjacent cells as the diff wraps — the last row has very long cell contents. Happy to be shown otherwise if you are seeing something concrete I have missed.
| | `compute.firewalls.create`, `compute.firewalls.delete`, `compute.firewalls.get`, `compute.firewalls.list`, `compute.firewalls.update`, and `compute.networks.updatePolicy` | Your service project's GKE service agent | Under Shared VPC, GKE creates its cluster and load-balancer firewall rules in the host project rather than the service project. Without this the internal load balancer health-check rule is never created, ingress backends stay unhealthy, and private link does not work. This is Google's documented granular alternative to granting `roles/compute.securityAdmin`. | | ||
|
|
||
| The last row is the only write access, and it is granted to your own project's GKE service agent rather than to ClickHouse. The ClickHouse management service account never writes to the host project. The module also enables the `container.googleapis.com` API on the host project, which provisions that project's own GKE service agent. | ||
|
|
||
| Then enter the host project in the **Shared VPC host project ID** field described above. If you want private link, create the `PRIVATE_SERVICE_CONNECT` subnet in the host project as well, in the same region as the infrastructure. |
There was a problem hiding this comment.
Declining this one, on local-consistency grounds.
Across all BYOC docs the aggregate does favour capitalization — roughly 48 "PrivateLink", 32 "Private Link", 14 lowercase — but that count is dominated by the AWS pages, where "AWS PrivateLink" is a product name. On the GCP pages the convention is the opposite: customization-gcp.mdx and network-gcp.mdx use lowercase "private link" seven times against one "PrivateLink", including the heading "Enable private link in ClickHouse console".
This page already used lowercase before my change — the pre-existing Note near the top of the "Configure your existing VPC" step reads "before enabling private link" — and network-gcp.mdx, which this section links to, does the same. Capitalizing only my paragraphs would leave the new section inconsistent with the page it sits on and with the page it points at.
Standardizing the term across all BYOC docs does seem worth doing, but as its own cleanup rather than as a partial change riding on this PR.
| 2. Enter your **VPC network name**. | ||
| 3. Enter the **Subnet name** you allocated for ClickHouse. | ||
| 4. Click **Set up Infrastructure** to begin provisioning. | ||
| 4. Optionally enter **Secondary range names** to pin which of the subnet's secondary ranges GKE uses for pods. Leave it empty to use all of them; every name you list must already exist on the subnet. |
| | `compute.networks.get`, `compute.subnetworks.get`, `compute.subnetworks.use` | ClickHouse management service account | Read your network and subnet, and let the Private Service Connect attachment use your PSC subnet | | ||
| | `roles/compute.networkUser` on the node subnet | ClickHouse management service account, your service project's GKE service agent, and your service project's Google APIs service account | The three identities that consume the subnet | | ||
| | `roles/container.hostServiceAgentUser` | Your service project's GKE service agent | Required for any Shared VPC GKE cluster | | ||
| | `compute.firewalls.create`, `compute.firewalls.delete`, `compute.firewalls.get`, `compute.firewalls.list`, `compute.firewalls.update`, and `compute.networks.updatePolicy` | Your service project's GKE service agent | Under Shared VPC, GKE creates its cluster and load-balancer firewall rules in the host project rather than the service project. Without this the internal load balancer health-check rule is never created, ingress backends stay unhealthy, and private link does not work. This is Google's documented granular alternative to granting `roles/compute.securityAdmin`. | |
| 6. Click **Set up Infrastructure** to begin provisioning. | ||
|
|
||
| <Image img="/images/cloud/reference/byoc-gcp-existing-vpc-ui.webp" size="lg" alt="ClickHouse Cloud BYOC setup UI with Use existing VPC selected for GCP" /> | ||
| <Image img="/images/cloud/reference/byoc-gcp-existing-vpc-ui.webp" size="lg" alt="ClickHouse Cloud BYOC setup UI with Use existing VPC selected for GCP, showing the VPC network name, subnet name, secondary range names, and Shared VPC host project ID fields" /> |
|
|
||
| The last row is the only write access, and it is granted to your own project's GKE service agent rather than to ClickHouse. The ClickHouse management service account never writes to the host project. The module also enables the `container.googleapis.com` API on the host project, which provisions that project's own GKE service agent. | ||
|
|
||
| Then enter the host project in the **Shared VPC host project ID** field described above. If you want private link, create a separate `PRIVATE_SERVICE_CONNECT` subnet in the host project, in the same network and region as the node subnet. It sits alongside the node subnet rather than replacing it, and it is not the subnet you pass as `shared_vpc_host_private_subnet_id`. |
robot-ch-test-poll4
added
the
pr-synced-to-cloud
Related: https://github.com/ClickHouse/control-plane/issues/39727
Related: https://github.com/ClickHouse/control-plane/issues/38340
Changelog category (leave one):
Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):
...
Documents GCP Shared VPC support for BYOC bring-your-own-VPC in
customization-gcp.mdx:### Shared VPC from a host projectsection covering the service-project attachment prerequisite, the required onboarding Terraform inputs, and PSC subnet placement in the host project.Generated by Mintlify Agent.
Requested by: shiqiang.duan@clickhouse.com via Slack
Mintlify session: slack_1789354492.362649_C0APBM6N5UP
Workflow [PR]
Sync PR [sync-upstream/pr/119881]
Version info
26.9.1.1455(included in26.9and later)