Connect a Google Cloud Environment to a Network Connectivity Center Hub
Attach a private Agentic Data Plane environment on Google Cloud to a Network Connectivity Center hub that you own. The environment’s virtual private cloud (VPC) becomes a VPC spoke on the hub. Self-managed agents, test harnesses, and applications in the hub’s other VPC spokes can then reach the environment’s AI Gateway and API over private IPv4 addresses.
This page applies only to environments on Google Cloud. For an environment on AWS, see Connect an AWS Environment to a Transit Gateway. To connect a single VPC on either cloud, see Peer a VPC with an Environment.
After reading this page, you will be able to:
-
Attach a private environment’s VPC on Google Cloud to a Network Connectivity Center hub as a VPC spoke
-
Limit the address ranges that the environment exports to the hub
-
Verify that workloads in another spoke reach the environment
Prerequisites
-
An environment on Google Cloud with
Privateaccess that showsReady. To create one, see Create an Agentic Data Plane Environment. -
A Network Connectivity Center hub that has your workloads' VPCs attached as VPC spokes. See VPC spokes overview in the Google Cloud documentation.
-
The Network Connectivity API (
networkconnectivity.googleapis.com) enabled in the project that you deployed the environment into. -
Permission to create a VPC spoke for the environment’s VPC:
-
The Spoke Admin role (
roles/networkconnectivity.spokeAdmin) in the project that you deployed the environment into. -
The Compute Network Admin role (
roles/compute.networkAdmin) on the environment’s VPC. -
The Group User role (
roles/networkconnectivity.groupUser) on the hub.
-
-
The gcloud CLI, or Terraform 1.5 or later with the Google Cloud provider.
-
Workloads and address ranges that meet these requirements:
Requirement Details Region
Your workloads run in the environment’s region, because the endpoints use a regional internal load balancer. A workload in another region times out, even though the hub has a route to the environment.
Address ranges
The environment’s CIDR block doesn’t overlap the subnet ranges of the hub’s other spokes. The CIDR block is fixed when you create the environment, so check it against your hub first.
By default, the environment exports every range in its CIDR block, including its pod and service secondary ranges. Network Connectivity Center doesn’t allow overlapping subnet ranges across a hub’s VPC spokes, so an overlap blocks the spoke unless you exclude the overlapping range. Don’t exclude the range that holds the load balancer, because workloads in other spokes then have no route to it. See Limit the ranges the environment exports.
Outbound traffic
Your design doesn’t depend on the hub for the environment’s outbound traffic. The hub gives your spokes a path to the environment, not a path from the environment to the internet. See How the hub connects your VPCs.
Deletion order
You delete the spoke before you delete the environment. See Remove the spoke.
Firewall rules
You don’t need to change firewall rules for workloads that call the environment. The endpoints accept connections from any source address.
How the hub connects your VPCs
An environment with Private access serves its AI Gateway and API endpoints from an internal load balancer in the environment’s VPC. The endpoint hostnames are in public DNS and resolve to the load balancer’s private address, so workloads in other spokes need no DNS configuration. Requests use HTTPS on TCP port 443.
When the environment’s VPC becomes a spoke, the hub adds the environment’s subnet ranges to its route table, and each of the other spokes gets a route to them. The environment’s VPC gets a route to the subnets of each of the other spokes. VPC spokes exchange subnet routes with each other. They don’t exchange static routes.
The hub therefore doesn’t change how the environment reaches the internet. Redpanda Cloud manages the default route in the environment’s VPC. Outbound traffic, such as calls to LLM providers, keeps using that route and the environment’s own Cloud NAT gateway. A default route in another spoke doesn’t reach the environment’s VPC, so you can’t send the environment’s internet traffic through a central firewall or NAT gateway.
You attach the environment once, instead of peering it with each VPC. A hub that uses the mesh topology connects every spoke to every other spoke. In a hub that uses the star topology, edge-group spokes reach only center-group spokes, so put the environment’s spoke, or your workloads' spokes, in the center group.
You create and manage the spoke in your own Google Cloud projects. Redpanda Cloud doesn’t create, track, or remove the spoke, and it doesn’t remove the routes that the hub adds to the environment’s VPC. Delete the spoke yourself before you delete the environment. See Remove the spoke.
To give people access from their computers or from an office network, connect them to the environment’s VPC through a VPN instead. See Connect to a Private Environment from Your Computer.
Find the environment’s network details
Find the environment’s network ID, region, CIDR block, and AI Gateway URL in the Redpanda Cloud UI. For the steps, see Find the environment’s network details. You need only the values, not the peering commands that the Redpanda Cloud UI shows.
The commands on this page use these placeholders:
| Placeholder | Value |
|---|---|
|
The environment’s Redpanda network ID. The environment’s VPC is the network |
|
The project that you deployed the environment into. |
|
The project that owns your hub. |
|
The name of your hub. |
|
A name for the environment’s spoke. |
|
A range in the environment’s VPC that you don’t want in the hub, such as a secondary range. |
|
The environment’s |
Attach the environment’s VPC to the hub
Create the spoke with the gcloud CLI, or declare it in Terraform.
If the hub is in a different project from the environment, the spoke can start as a proposal that becomes active only after the hub’s administrator accepts it. See Work with hubs and spokes in the Google Cloud documentation.
| This configuration refers to a third-party product. Specific UI elements may not be up to date. For current syntax, see the vendor documentation linked on this page. |
-
gcloud CLI
-
Terraform
-
Create the spoke. Use credentials for the project that you deployed the environment into.
gcloud network-connectivity spokes linked-vpc-network create <spoke-name> \ --project=<environment-project-id> \ --global \ --hub=projects/<hub-project-id>/locations/global/hubs/<hub-name> \ --vpc-network=projects/<environment-project-id>/global/networks/redpanda-<network-id>If one of the environment’s ranges overlaps another spoke, add
--exclude-export-ranges=<range-to-exclude>to this command so that the spoke never exports that range. See Limit the ranges the environment exports. -
Confirm that the spoke shows
ACTIVE:gcloud network-connectivity spokes describe <spoke-name> \ --project=<environment-project-id> \ --global --format="value(state)"
variable "network_id" {
description = "The environment's Redpanda network ID."
type = string
}
variable "environment_project_id" {
description = "The project that you deployed the environment into."
type = string
}
variable "hub" {
description = "The ID of your hub, in the form projects/PROJECT_ID/locations/global/hubs/HUB_NAME."
type = string
}
variable "spoke_name" {
description = "A name for the environment's spoke."
type = string
}
variable "exclude_export_ranges" {
description = "Ranges of the environment's VPC to keep out of the hub."
type = list(string)
default = []
}
data "google_compute_network" "environment" {
name = "redpanda-${var.network_id}"
project = var.environment_project_id
}
resource "google_network_connectivity_spoke" "environment" {
name = var.spoke_name
project = var.environment_project_id
location = "global"
hub = var.hub
linked_vpc_network {
uri = data.google_compute_network.environment.self_link
exclude_export_ranges = var.exclude_export_ranges
}
}
output "spoke_state" {
value = google_network_connectivity_spoke.environment.state
}
For resource arguments, see google_network_connectivity_spoke.
Set the variables, then run terraform init and terraform apply. Confirm that the spoke_state output shows ACTIVE.
Limit the ranges the environment exports
By default, the spoke exports every subnet range in the environment’s VPC to the hub. These include the secondary ranges that the environment’s Kubernetes pods and services use. All of the ranges are inside the environment’s CIDR block.
Workloads that call the environment need a route to only one of these ranges: the primary range of the subnet that holds the internal load balancer. To keep the other ranges out of your hub, exclude them from the spoke’s exports.
Limit the exports only when traffic flows one way, from your spokes to the environment. If agents and MCP servers in the environment also call services in your other spokes, keep the default exports. The default gives your other spokes a route to every range in the environment’s VPC.
-
List the environment’s subnet ranges:
gcloud compute networks subnets list \ --project=<environment-project-id> \ --network=redpanda-<network-id> \ --format="table(name,ipCidrRange,secondaryIpRanges[].ipCidrRange.list():label=SECONDARY_RANGES)"The subnet that has secondary ranges holds the load balancer. Keep its primary range. The address that the AI Gateway hostname resolves to is inside it.
-
Exclude the ranges that you don’t want in the hub:
gcloud network-connectivity spokes linked-vpc-network update <spoke-name> \ --project=<environment-project-id> \ --global \ --exclude-export-ranges=<range-to-exclude>,<range-to-exclude>The
--exclude-export-rangesflag replaces the spoke’s whole list of excluded ranges, so include every range that you want excluded. With Terraform, setexclude_export_rangesand runterraform apply.
Changing the excluded ranges updates the spoke in place. You don’t need to detach the spoke.
Verify the connection
Routes appear in the hub’s route table as soon as a spoke is active. Traffic between spokes can take several minutes longer to start flowing after you add a spoke, so wait before you test.
-
Confirm that the hub’s route table lists the environment’s ranges:
gcloud network-connectivity hubs route-tables routes list \ --project=<hub-project-id> \ --hub=<hub-name> --route_table=default \ --format="table(ipCidrRange,type,state,spoke.basename())"The output lists each range that the environment exports, with the name of the environment’s spoke in the last column.
-
From a machine in another spoke, in the environment’s region, send a request to the environment’s AI Gateway:
curl -sS --connect-timeout 5 -o /dev/null -w '%{http_code}\n' <ai-gateway-url>Any HTTP status code means the network path works. A timeout means traffic doesn’t reach the environment.
For how workloads authenticate and what they need to call the environment, see Run agents and harnesses in your VPC. The same guidance applies to workloads in a spoke.
Allow traffic from the environment to your services
To let agents and MCP servers reach a service in one of your spokes, such as a database, keep the default exports on the environment’s spoke. See Limit the ranges the environment exports. Your service’s VPC gets a route to every range in the environment’s VPC. Also add an ingress firewall rule in the service’s VPC that allows the environment’s CIDR block on the service’s port.
Remove the spoke
Delete the spoke when you no longer need it, and before you delete the environment. Google Cloud blocks deletion of a VPC that is attached to a hub as a spoke. If the spoke still exists when you delete the environment, the step that removes the environment’s VPC fails with an error that names the spoke. The VPC stays in your project until you delete the spoke and run the failed step again.
gcloud network-connectivity spokes delete <spoke-name> \
--project=<environment-project-id> \
--global
If you created the spoke with Terraform, run terraform destroy for that configuration instead.
Troubleshooting
| Symptom | Action |
|---|---|
Requests from a workload in another spoke time out. |
Check each of these:
|
Requests from the environment’s region work, but requests from another region time out. |
This is expected. The endpoints use a regional internal load balancer, so run the workload in the environment’s region. |
Google Cloud reports that a subnet range overlaps another network on the hub. |
Subnet ranges can’t overlap across a hub’s VPC spokes.
For the rules on overlapping ranges, see Work with hubs and spokes in the Google Cloud documentation. |
The environment’s hostname resolves, but to an address your network can’t reach. |
This is expected outside the hub’s spokes, because the hostname always resolves to the private address. Some corporate DNS resolvers drop public answers that contain private addresses. If yours does, ask your network team to allow the environment’s hostnames. |
Agents or MCP servers can’t reach a service in another spoke. |
Check that a firewall rule in that VPC allows inbound traffic from the environment’s CIDR block, and that the environment’s spoke exports the ranges that your agents and MCP servers run in. The default exports include all of them. |
Outbound traffic from the environment doesn’t go through your hub’s firewall or NAT gateway. |
This is expected. The hub exchanges only subnet routes, so the environment keeps its own default route and its own Cloud NAT gateway. See How the hub connects your VPCs. |
Deleting the environment fails with an error that says the network is already being used by a spoke. |
Google Cloud blocks deletion of the environment’s VPC while the spoke exists. Delete the spoke, then run the failed step again. See Remove the spoke. |