Set up VPC connectivity for Agent Gateway

This document guides you through the process of configuring VPC connectivity when deploying an Agent Gateway so that it can privately communicate with a VPC network in your organization.

Setting up VPC connectivity lets you do the following:

• Enforce VPC egress for traffic: You can configure how the gateway routes traffic through your Private Service Connect network attachment into your VPC network using the vpcEgress setting:

  • Traffic to private IP address ranges (PRIVATE_RANGES_ONLY): Routes traffic destined only for certain private IP address ranges into your VPC network. For the specific IP address ranges, see Subnet requirements.

  • Traffic to all IP address ranges (ALL_TRAFFIC): Routes all outbound traffic originating from your agents through your VPC network, including traffic destined for public and non-RFC 1918 IP address ranges.

    Because this setting routes all outbound traffic into your VPC, you're responsible for managing its routing and security. Ensure that your VPC network has a default route (0.0.0.0/0) to forward this traffic to your outbound gateways or security appliances (such as next-hop firewalls or Cloud Interconnect interfaces).

• Static source IP address range for egress traffic: When you enable VPC connectivity, egress traffic originating from Agent Gateway uses the private IP address range of the subnet assigned to your Private Service Connect interface network attachment as its source IP address. This static source IP range lets you configure firewall policies for your VPC network to govern traffic coming from the gateway. When vpcEgress is set to ALL_TRAFFIC, you can enable internet egress for traffic routed through your VPC by configuring Cloud NAT on the subnet assigned to your Private Service Connect network attachment.

• Custom DNS resolution: You can resolve internal and external domain names directly from your agents. Your agents can connect to services in the target VPC network using stable, human-readable DNS names instead of IP addresses.

• Perimeter security and data exfiltration protection: Enforce VPC Service Controls service perimeters for agent communications. When you configure Agent Gateway with an agent connectivity template (in ALL_TRAFFIC mode), all agent traffic is routed through your private VPC network attachment, ensuring that your organization's VPC Service Controls perimeter rules are applied to agent traffic as well.

To configure VPC connectivity from your Agent Gateway, you create a resource called an agent connectivity template (AgentConnectivityTemplate) where you define and manage egress networking settings for your Agent Gateway instances. For steps, see Configure VPC connectivity.

Required roles and permissions

To configure VPC connectivity for Agent Gateway, ensure that the identity used for provisioning and the gateway service agent have the required roles.

In a standalone project where the gateway, network attachment, and VPC network reside in the same project, standard Agent Gateway permissions apply. For details, see Required permissions.

Shared VPC or cross-project deployments

If you are using a Shared VPC or cross-project setup where the target VPC network, network attachment, or private DNS zones reside in a central host project (TARGET_VPC_PROJECT_ID), the following roles are required:

Configure VPC connectivity

To deploy an Agent Gateway with an agent connectivity template, perform the following steps:

1. Create a Private Service Connect network attachment in the VPC network that you want to connect to.

   Note the following requirements:

   • Connection preference: Configure the network attachment to automatically accept connections (--connection-preference=ACCEPT_AUTOMATIC).
   • Same VPC network requirement: The network attachment subnet and the target network configured for DNS peering (targetNetwork) must be in the exact same VPC network. If the network attachment's subnet belongs to a different network than the DNS peering target network, configuration validation fails.
   • Certificate requirement: The endpoint that you connect to must support HTTP or HTTPS with a publicly signed or trusted certificate. If Agent Gateway is unable to validate the certificate, the connection fails.

   • Subnet requirements: Note the following requirements for the network attachment subnet:

     • Agent Gateway requires a minimum /28 subnet for the network attachment. A /28 subnet provides 12 usable IP addresses, which is sufficient for a single Agent Gateway instance. If you plan to connect multiple gateways to the same network attachment or subnet, use a larger subnet (such as /26 or /24) to avoid IP address exhaustion.

     • The network attachment subnet supports all valid ranges. Traffic routing behavior depends on the vpcEgress setting configured in your agent connectivity template:

       • PRIVATE_RANGES_ONLY (default): Agent Gateway routes traffic destined only for the following private IP address ranges through your VPC network:

         • RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
         • RFC 6598: 100.64.0.0/10
         • Class E: 240.0.0.0/4
         • private.googleapis.com: 199.36.153.8/30
         • restricted.googleapis.com: 199.36.153.4/30
         • PSC endpoints for Google APIs: If you deploy a custom Private Service Connect endpoint for Google APIs using an internal private IP address in your VPC network, traffic to this endpoint is routed through your VPC network. Ensure that Cloud DNS peering is configured in the connectivity template so that Agent Gateway correctly resolves Google API domains to your internal PSC endpoint IP address.

         Requests to standard public Google API endpoints are handled automatically using Private Google Access within the managed service environment. Internet-bound traffic isn't routed through your VPC network.

       • ALL_TRAFFIC: All outbound traffic originating from your agents is routed through the VPC network attachment, including public internet and non-RFC 1918 addresses.

   • Shared VPC setup requirements:

     In a Shared VPC architecture, you can create the network attachment in either the service project (recommended) or the host project:

     • Recommended: Network attachment in service project:

       1. Create the subnet in the host project.
       2. Create the network attachment in the service project, referencing the host project's subnet.

     • Network attachment in host project:

       1. Create the subnet in the host project.
       2. Create the network attachment in the host project.

     Note the URI of the network attachment. You'll need it when you update the PSC_NETWORK_ATTACHMENT_URI attribute of the connectivity template resource in a later step.

2. Configure DNS peering for the service that you are connecting to. With DNS peering, your agents can connect to services in the target VPC network using stable, human-readable DNS names instead of IP addresses. DNS peering lets Agent Gateway resolve DNS names using the records from a Cloud DNS private zone in your VPC.

   1. Set up your private DNS zone for DNS resolution and traffic routing. To add DNS records to your private DNS zone, see Add a resource record set.

   2. Gather the DNS information to enable peering:

      • Domain name: The domain name for DNS peering. Each domain must end with a trailing dot (.) (for example, example.com. or corp.internal.).
      • Specific domain suffixes only: Specify only the specific domain suffixes that your agents need to reach in the target VPC network. Don't use root or catch-all wildcard domains (such as .) or Google service domains (such as googleapis.com.). Using these domains routes all gateway DNS traffic to your private VPC, which can cause unexpected issues.
      • Exact match zones required: The private Cloud DNS zones in the target VPC network must have exact match zones for the domain suffixes configured for peering.
      • Target network URI: The full resource URI of the VPC network. This must be the same VPC network that contains the network attachment.

3. Create a YAML configuration file named agw-connectivity-template.yaml to define the connectivity template:

   name: projects/AGENT_GATEWAY_PROJECT_ID/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
   accessPath: AGENT_TO_ANYWHERE
   egressNetworkConfig:
     networkAttachment: PSC_NETWORK_ATTACHMENT_URI
     dnsPeeringConfig:
       domain: DOMAIN_NAME
       targetNetwork: TARGET_VPC_NETWORK_URI
     vpcEgress: VPC_EGRESS_MODE
   

   Replace the following:

   • AGENT_GATEWAY_PROJECT_ID: The project ID of the Google Cloud project where the gateway is deployed.
   • LOCATION: The location for the agent connectivity template (for example, europe-west1).
   • CONNECTIVITY_TEMPLATE_NAME: The name of the agent connectivity template resource.
   • PSC_NETWORK_ATTACHMENT_URI: The PSC interface network attachment for connectivity to VPCs. If the network attachment is created in a project different from where you deployed the gateway (such as the Shared VPC host project), pass the full path of your network attachment: projects/TARGET_VPC_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME. Note: This field is immutable once configured.
   • DOMAIN_NAME: (Optional) A specific domain suffix for DNS peering (for example, example.com. or corp.internal.). This value is required, must end with a trailing dot (.), and must have an exact match private Cloud DNS managed zone authorized for the target network. Don't use root or wildcard domains (such as .) or Google service domains (such as googleapis.com.).
   • TARGET_VPC_NETWORK_URI: The target VPC network where you created the network attachment. This must be of the form: projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME. This network must be the exact same VPC network where the network attachment is created.
   • VPC_EGRESS_MODE: The egress traffic routing setting. Set to PRIVATE_RANGES_ONLY (default) to route traffic destined for private IP ranges through your VPC network, or set to ALL_TRAFFIC to route all outbound agent traffic (including public internet addresses) through your VPC network.

4. Run the following command to create the agent connectivity template:

   gcloud network-services agent-connectivity-templates import CONNECTIVITY_TEMPLATE_NAME \
       --source="agw-connectivity-template.yaml" \
       --location=LOCATION
   

   Replace the following:

   • CONNECTIVITY_TEMPLATE_NAME: The name of the agent connectivity template resource.
   • LOCATION: The location where you want to create the agent connectivity template resource. For example, europe-west1.

5. Define a new Agent Gateway resource by creating a gateway YAML configuration file (for example, my-agent-gateway-vpc-egress.yaml) that references the connectivity template:

   name: AGENT_GATEWAY_NAME
   protocols:
     - MCP
   googleManaged:
     governedAccessPath: AGENT_TO_ANYWHERE
   agentConnectivityTemplate: projects/AGENT_GATEWAY_PROJECT_ID/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
   registries:
     - AGENT_REGISTRY_PATH
   

   Replace the following:

   • AGENT_GATEWAY_NAME: The name of the Agent Gateway resource.
   • AGENT_GATEWAY_PROJECT_ID: The project ID of the Google Cloud project where you created the gateway and connectivity template.
   • LOCATION: The location of the agent connectivity template (for example, europe-west1).
   • CONNECTIVITY_TEMPLATE_NAME: The name of the agent connectivity template resource.
   • AGENT_REGISTRY_PATH: The path to the Agent Registry. For Agent Runtime agents, use a regional registry (//agentregistry.googleapis.com/projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION). For Gemini Enterprise, use the global, multi-region, or regional registry that corresponds to your deployment (for example, //agentregistry.googleapis.com/projects/AGENT_GATEWAY_PROJECT_ID/locations/global).

6. Run the following command to create the Agent Gateway resource based on the YAML specification:

   gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
       --source="my-agent-gateway-vpc-egress.yaml" \
       --location=LOCATION
   

   Replace LOCATION with the location where you want to create the Agent Gateway resource. For example, europe-west1.

What's next