Shared VPC
Shared VPC lets one host project own the VPC networks while other projects, its service projects, create resources in the host's subnets. On the GCP Enterprise Baseline, acme-core-network is the only host: the stage projects run their workloads in its networks and may use only their own stage subnets.
What it does
A host project has Shared VPC enabled and owns the networks, subnets, routes and firewall policies. A service project is attached to the host; its resources, such as GKE nodes, Cloud Run direct VPC egress or Private Service Connect endpoints, take addresses from the host's subnets. Who may use a subnet is IAM: roles/compute.networkUser on the subnet. Network administration stays with the host's owners, workload administration with the service project's owners.
How BuiltForProd uses it
One host. The organization-scoped host-project unit enables Shared VPC on acme-core-network, and the organization policy compute.restrictSharedVpcHostProjects allows no other host anywhere. The three VPC networks live there, with their firewall policies, Cloud NAT and DNS.
One attachment per stage. Every stage project runs the shared-vpc-service unit from the plat-project template, which picks the stage's isolation-domain VPC from network.hcl and its subnets from the address plan:
| Grant or setting | On | To |
|---|---|---|
| Service project attachment | acme-core-network | the stage project |
roles/compute.networkUser | each subnet of the stage | the GKE, Google APIs, Cloud Run and Dataproc service agents, the stage deployer, the stage's engineer groups |
roles/container.hostServiceAgentUser | acme-core-network | the stage's GKE service agent |
custom sharedVpcNetworkUse | acme-core-network | the stage deployer |
compute.restrictSharedVpcSubnetworks | the stage project | an organization policy listing only the stage's own subnets |
Dev and staging share the nonprod VPC, yet the organization policy keeps each stage project on its own subnets. The custom role sharedVpcNetworkUse holds only compute.networks.use: a Private Service Connect endpoint, such as the Web App Blueprint's Memorystore endpoints, names the Shared VPC network, and the predefined role on the host would open every subnet instead. GKE does not get the right to write firewall rules in the host (grant_gke_firewall_admin = false), since the domain firewall policies already carry the cluster flows.
The runner project. When the optional self-hosted runners are on, acme-core-auto also attaches as a service project and its GKE and Google APIs agents get compute.networkUser on the hub's runner subnet only.
The unit is organization-scoped because attaching a service project needs Shared VPC Admin and the subnet restriction is an organization policy; in CI it runs as sa-acme-baseline-ci.
Terms you will see
| Term | Meaning |
|---|---|
| Host project | acme-core-network, the owner of the networks. |
| Service project | A stage project, or acme-core-auto, that uses the host's subnets. |
| Network User | roles/compute.networkUser, the right to use a subnet. |
sharedVpcNetworkUse | The custom role with compute.networks.use alone. |
| Subnet restriction | compute.restrictSharedVpcSubnetworks, set per stage project. |
Where to read more
- GCP Enterprise Baseline overview and its architecture overview.
- Identity and Access Management for the other resource-level grants.
- Hub-and-spoke networking for the topology.