Skip to main content

​
Customer-managed VPC (BYO-VPC) for GCP

If you prefer to use an existing VPC to deploy ClickHouse BYOC instead of having ClickHouse Cloud provision a new VPC, follow the steps below. This approach provides greater control over your network configuration and allows you to integrate ClickHouse BYOC into your existing network infrastructure.
1

Configure your existing VPC

  1. Allocate at least 1 private subnet in a region supported by ClickHouse BYOC for the ClickHouse Kubernetes (GKE) cluster. Ensure the subnet has a minimum CIDR range of /24 (e.g., 10.0.0.0/24) to provide sufficient IP addresses for GKE cluster nodes.
  2. Within the private subnet, allocate at least 1 secondary IPv4 range that will be used for GKE cluster pods. The secondary range must be at least /21. Smaller ranges do not provide enough pod IP addresses for the GKE cluster to finish provisioning, and infrastructure setup will fail.
  3. Enable Private Google Access on the subnet. This allows GKE nodes to reach Google APIs and services without requiring external IP addresses.
To expose services over Private Service Connect, you also need a dedicated subnet with purpose PRIVATE_SERVICE_CONNECT in this VPC. You can create it now or later, before enabling private link.
2

Ensure network connectivity

Cloud NAT Gateway Ensure a Cloud NAT gateway is deployed for the VPC. It provides outbound connectivity for instances without external IP addresses, and two things depend on it:
  • Tailscale. ClickHouse BYOC components register with the Tailscale control plane, which provides secure, zero-trust networking for private management operations without requiring inbound public access.
  • Container images. Some images the deployment runs are not mirrored into the BYOC registry, including community images, and are pulled from their upstream registries.
A VPC with no outbound path will not finish provisioning; pre-flight validation checks that a Cloud NAT gateway covers the network. There is no single published endpoint list; if your network policy requires an explicit inventory, contact support to review your setup.DNS Resolution Ensure your VPC has working DNS resolution and doesn’t block, interfere with, or overwrite standard DNS names. ClickHouse BYOC relies on DNS to resolve Tailscale control servers and ClickHouse service endpoints. If DNS is unavailable or misconfigured, BYOC services may fail to connect or operate properly.
3

Set up BYOC infrastructure

When you click Set up Infrastructure, ClickHouse Cloud automatically runs pre-flight validation before provisioning. It checks that the management service account has the required permissions and that the required Google Cloud APIs are enabled, and it validates the VPC you bring: that the network and subnet resolve, that the subnet’s primary range and pod secondary range are large enough, and that a Cloud NAT gateway covers the network. If anything is missing, setup halts with the specific issues to fix.
In the ClickHouse Cloud console, configure the following when setting up new infrastructure:
  1. Under VPC configuration, select Use existing VPC.
  2. Enter your VPC network name.
  3. Enter the Subnet name you allocated for ClickHouse.
  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.
  5. If your VPC lives in a Shared VPC host project, enter the Shared VPC host project ID. Leave it empty when the VPC is in the same project as the infrastructure. See Shared VPC from a host project below.
  6. Click Set up Infrastructure to begin provisioning.

​
Shared VPC from a host project

You can run BYOC in a service project on a network that lives in a separate Shared VPC host project, which lets you keep networking centralized. The VPC and its subnets are owned by the host project, while the BYOC infrastructure runs in an attached service project. The requirements above are unchanged; they simply apply to the subnet in the host project. Two prerequisites are specific to this setup:
  • Enable the host project as a Shared VPC host, and attach the service project to it, before you begin. Both steps are required and are separate: a project that is not already a Shared VPC host must be enabled as one first, and only then can the service project be attached. A Shared VPC GKE cluster requires that attachment to exist. Pre-flight validation reads your network and subnet through the host-project grants whether or not the attachment is in place, so it passes either way and provisioning then fails later at cluster creation. Both operations are organization-level and are performed by whoever administers Shared VPC in your organization; the onboarding Terraform cannot do them for you.
  • Run the onboarding Terraform with the host project set. Pass shared_vpc_host_project_id, shared_vpc_host_subnet_region and shared_vpc_host_private_subnet_id to the onboarding module. shared_vpc_host_private_subnet_id is the host subnet your GKE nodes run in — the one you configured above — and not the Private Service Connect subnet described below. Pointing it at the PSC subnet places the roles/compute.networkUser grant on the wrong subnet, and provisioning then fails at cluster creation. A single invocation writes into both projects, so the credentials running it need IAM admin on the service project and on the host project.
The grants the module adds to your host project are narrow, but they are not all read-only: 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.
Last modified on September 15, 2026