Use policy-based routes

Policy-based routes let you select a next hop based on more than a packet's destination IP address. This page describes how to create, list, describe, and delete policy-based routes.

Before you begin

To use the command-line examples in this guide, install or update to the latest version of the Google Cloud CLI.
You must enable the Network Connectivity API in your project.
You need an internal passthrough Network Load Balancer. We recommend enabling global access so that the internal passthrough Network Load Balancer does not drop packets from regions other than the one in which it is defined.

Required roles

To get the permissions that you need to use policy-based routes, ask your administrator to grant you the Compute Network Admin (roles/compute.networkAdmin) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Create policy-based routes

When you create a policy-based route, you specify the following:

Route scope: the resources that the route can apply to.
Classification criteria: the source IP address ranges, destination IP address ranges, and protocols that determine which packets the route applies to. The policy-based route applies to packets that match all of the specified classification criteria.
Next hop: a next hop internal passthrough Network Load Balancer or a next hop that skips other policy-based routes.

Console

In the Google Cloud console, go to Routes.

Go to Routes
Click Route management.
Click Create route.
Enter a Name for the route.
Optional: Enter a Description.
Click Network, and then select the network where you want to add the policy-based route.
Click Route type, and then select Policy-based route.
In the Route scope section, do one of the following:
- To make the route apply to all virtual machine (VM) instances, VLAN attachments for Cloud Interconnect, and Cloud VPN tunnels in the Virtual Private Cloud network, select This route applies to all VM instances, VLAN attachments, and VPN tunnels.
  
  Google recommends caution when creating routes of this type. The route is applied to all egress packets that match the classification criteria, which can include egress traffic from the backend of the internal passthrough Network Load Balancer.
- To make the route apply only to certain VM instances, select This route only applies to VM instances, and then enter the network tags of the VMs that this route should apply to. You can enter multiple network tags in a comma-separated list.
- To make the route apply to all VLAN attachments for Cloud Interconnect in the route's VPC network, select This route only applies to VLAN attachments.
- To make the route apply to VLAN attachments for Cloud Interconnect in a specific region, select This route only applies to VLAN attachments, and then select the region of the VLAN attachments. It is not possible to create a policy-based route that applies to a specific VLAN attachment.
In the Classification criteria section, do the following:
1. Enter a Source IP range.
2. Enter a Destination IP range.
3. Click Protocol, and then select the protocols that this route applies to.
Enter a Priority.
In the Next hop section, click Next hop, and then do the following:
- To specify a next hop internal passthrough Network Load Balancer, select Specify a forwarding rule of the internal passthrough Network Load Balancer, and then do the following:
  - To select a forwarding rule from a list of existing forwarding rules:
    1. Select In use by the forwarding rule of an internal load balancer in the current project.
    2. Click Forwarding rule IP address, and then select an IP address that's associated with an internal load balancer in the selected project.
  - To enter an IP address:
    1. Select Unused.
    2. In the Forwarding rule IP address field, enter an IP address, without a prefix length. The IP address must come from one of the following sources:
      - The IP address ranges of the VPC network where you are creating this policy-based route.
      - The IP address ranges of a VPC network that is connected to the route's VPC network through VPC Network Peering (Preview).
    You can specify an IP address that is already associated with an internal passthrough Network Load Balancer's forwarding rule, or you can specify an unused IP address and create the forwarding rule after you create this policy-based route.
- To create a policy-based route that skips other policy-based routes, select Skip other policy-based routes.
Click Create.

gcloud

Use the policy-based-routes create command.

To apply the route to all VM instances, VLAN attachments for Cloud Interconnect, and Cloud VPN tunnels in the Virtual Private Cloud network, use the following command.

Google recommends caution when creating routes of this type. The route is applied to all egress packets that match the classification criteria, which can include egress traffic from the backend of the internal passthrough Network Load Balancer.
```
gcloud network-connectivity policy-based-routes create ROUTE_NAME \
    --source-range=SOURCE_RANGE \
    --destination-range=DESTINATION_RANGE \
    --ip-protocol=PROTOCOL \
    --protocol-version=IP_VERSION \
    --network="projects/PROJECT_ID/global/networks/NETWORK" \
    --next-hop-ilb-ip=NEXT_HOP \
    --description=DESCRIPTION \
    --priority=PRIORITY
```
Replace the following:
- ROUTE_NAME: the name of the policy-based route.
- SOURCE_RANGE: the source IP CIDR range.
- DESTINATION_RANGE: the destination IP CIDR range.
- PROTOCOL: the protocol of traffic to forward. Options are ALL, TCP, or UDP. The default is ALL.
- IP_VERSION: a single Internet Protocol version that this route applies to. Specify either IPv4 or IPv6 (Preview). The default is IPv4. To specify IPv6, use the beta version of the Google Cloud CLI.
- PROJECT_ID: the ID of the project.
- NETWORK: the name of the network to apply the policy-based route to.
- NEXT_HOP: a single IP address, without a prefix length, for the route's next hop internal passthrough Network Load Balancer. Specify an IPv4 address as a next hop for IPv4 traffic, or specify an IPv6 address for IPv6 traffic (Preview). The load balancer must be in either the same VPC network as the policy-based route or in a VPC network that is connected to the route's VPC network through VPC Network Peering (Preview).
  
  If the route applies to IPv6 traffic (Preview), you must set up the load balancer with dual-stack subnets.
  
  To specify an IPv6 address or an IP address from a peer VPC network, use the beta version of the Google Cloud CLI.
- DESCRIPTION: an optional description of the route.
- PRIORITY: the priority of the policy-based route compared to other policy-based routes.

To apply the route only to certain VM instances, use the following command:

gcloud network-connectivity policy-based-routes create ROUTE_NAME \
    --source-range=SOURCE_RANGE \
    --destination-range=DESTINATION_RANGE \
    --ip-protocol=PROTOCOL \
    --protocol-version=IP_VERSION \
    --network="projects/PROJECT_ID/global/networks/NETWORK" \
    --next-hop-ilb-ip=NEXT_HOP \
    --description=DESCRIPTION \
    --priority=PRIORITY \
    --tags=NETWORK_TAGS

Replace NETWORK_TAGS with one or more network tags of the VMs to apply the route to. You can include multiple network tags in a comma-separated list.

To apply the route only to VLAN attachments for Cloud Interconnect, use the following command. You can apply the route to either VLAN attachments for Cloud Interconnect in a specific region or to all VLAN attachments for Cloud Interconnect in a VPC network.
```
gcloud network-connectivity policy-based-routes create ROUTE_NAME \
    --source-range=SOURCE_RANGE \
    --destination-range=DESTINATION_RANGE \
    --ip-protocol=PROTOCOL \
    --protocol-version=IP_VERSION \
    --network="projects/PROJECT_ID/global/networks/NETWORK" \
    --next-hop-ilb-ip=NEXT_HOP \
    --description=DESCRIPTION \
    --priority=PRIORITY \
    --interconnect-attachment-region=INTERCONNECT_REGION
```
Replace INTERCONNECT_REGION with the region of the VLAN attachments for Cloud Interconnect to apply the route to. To apply the policy-based route to all VLAN attachments for Cloud Interconnect in the route's VPC network, use all.

To specify a next hop that skips other policy-based routes for specific VMs that are identified by network tags, use the following command:

gcloud network-connectivity policy-based-routes create ROUTE_NAME \
    --source-range=SOURCE_RANGE \
    --destination-range=DESTINATION_RANGE \
    --ip-protocol=PROTOCOL \
    --protocol-version=IP_VERSION \
    --network="projects/PROJECT_ID/global/networks/NETWORK" \
    --next-hop-other-routes=DEFAULT_ROUTING \
    --description=DESCRIPTION \
    --priority=PRIORITY \
    --tags=NETWORK_TAGS

API

Send a POST request to the policyBasedRoutes.create method:

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/policyBasedRoutes?policyBasedRouteId=ROUTE_NAME

To apply the route to all VM instances, VLAN attachments for Cloud Interconnect, and Cloud VPN tunnels in the Virtual Private Cloud network, include the following request body.

Google recommends caution when creating routes of this type. The route is applied to all egress packets that match the classification criteria, which can include egress traffic from the backend of the internal passthrough Network Load Balancer.
```
{
  "filter": {
    "srcRange": "SOURCE_RANGE",
    "destRange": "DESTINATION_RANGE",
    "ipProtocol": "PROTOCOL",
    "protocolVersion": "IP_VERSION"
  },
  "network": "projects/PROJECT_ID/global/networks/NETWORK",
  "nextHopIlbIp": "NEXT_HOP",
  "description": "DESCRIPTION",
  "priority": "PRIORITY"
}
```
Replace the following:
- PROJECT_ID: the ID of the project.
- ROUTE_NAME: the name of the policy-based route.
- SOURCE_RANGE: the source IP CIDR range.
- DESTINATION_RANGE: the destination IP CIDR range.
- PROTOCOL: the protocol of traffic to forward. Options are ALL, TCP, or UDP. The default is ALL.
- IP_VERSION: a single Internet Protocol version that the route applies to. Specify either IPv4 or IPv6 (Preview). The default is IPv4. To specify an IPv6 address, use the v1beta API.
- NETWORK: the name of the network to apply the policy-based route to. The route applies to egress traffic from instances in this network that meet the other classification criteria.
- NEXT_HOP: a single IP address, without a prefix length, for the route's next hop internal passthrough Network Load Balancer. Specify an IPv4 address as a next hop for IPv4 traffic, or specify an IPv6 address for IPv6 traffic (Preview). The load balancer must be in either the same VPC network as the policy-based route or in a VPC network that is connected to the route's VPC network through VPC Network Peering (Preview).
  
  If the route applies to IPv6 traffic (Preview), you must set up the load balancer with dual-stack subnets.
  
  To specify an IPv6 address or an IP address from a peer VPC network, use the v1beta API.
- DESCRIPTION: an optional description of the route.
- PRIORITY: the priority of the policy-based route compared to other policy-based routes.

To apply the route only to certain VM instances, include the following request body:

{
  "filter": {
    "srcRange": "SOURCE_RANGE",
    "destRange": "DESTINATION_RANGE",
    "ipProtocol": "PROTOCOL",
    "protocolVersion": "IP_VERSION"
  },
  "network": "projects/PROJECT_ID/global/networks/NETWORK",
  "nextHopIlbIp": "NEXT_HOP",
  "description": "DESCRIPTION",
  "priority": "PRIORITY",
  "virtualMachine": {
    "tags": [
      "NETWORK_TAGS"
    ]
  }
}

Replace NETWORK_TAGS with one or more network tags. The policy-based route applies to egress traffic from instances that have at least one of these tags. You can include multiple tags in the following form: "tag1","tag2","tag3".

To apply the route only to VLAN attachments for Cloud Interconnect, include the following request body. It is not possible to create a policy-based route that applies to a specific VLAN attachment.
```
{
  "filter": {
    "srcRange": "SOURCE_RANGE",
    "destRange": "DESTINATION_RANGE",
    "ipProtocol": "PROTOCOL",
    "protocolVersion": "IP_VERSION"
  },
  "interconnectAttachment": {
    "region": "INTERCONNECT_REGION"
  },
  "network": "projects/PROJECT_ID/global/networks/NETWORK",
  "nextHopIlbIp": "NEXT_HOP",
  "description": "DESCRIPTION",
  "priority": "PRIORITY"
}
```
Replace INTERCONNECT_REGION with the region of the VLAN attachments for Cloud Interconnect to apply this route to. To apply the policy-based route to all VLAN attachments for Cloud Interconnect in the route's VPC network, use all.

To specify a next hop that skips other policy-based routes for specific VMs that are identified by network tags, use the following command:

{
  "filter": {
    "srcRange": "SOURCE_RANGE",
    "destRange": "DESTINATION_RANGE",
    "ipProtocol": "PROTOCOL",
    "protocolVersion": "IP_VERSION"
  },
  "network": "projects/PROJECT_ID/global/networks/NETWORK",
  "nextHopOtherRoutes": "DEFAULT_ROUTING",
  "description": "DESCRIPTION",
  "priority": "PRIORITY",
  "virtualMachine": {
    "tags": [
      "NETWORK_TAGS"
    ]
  }
}

Verify connectivity for a policy-based route

Connectivity Tests is a diagnostics tool that lets you check connectivity between endpoints in your network. It analyzes your configuration and, in some cases, performs run-time verification. Connectivity Tests supports policy-based routes. To run Connectivity Tests with your policy-based routes, see Create and run Connectivity Tests.

List policy-based routes

You can list policy-based routes to view all policy-based routes in a project or network and region.

Console

In the Google Cloud console, go to Routes.

Go to Routes
- To view all policy-based routes in a VPC network and region, do the following:
  1. Click Effective routes.
  2. Click Network, and then select a network.
  3. Click Region, and then select a region.
  4. Click View.
- To view all policy-based routes in a project, do the following:
  1. Click Route management.

gcloud

Use the policy-based-routes list command.

gcloud network-connectivity policy-based-routes list

API

Send a GET request to the policyBasedRoutes.list method.

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/policyBasedRoutes

Replace PROJECT_ID with the ID of the project to list policy-based routes in.

Describe policy-based routes

You can describe a policy-based route to view details about the route.

Console

In the Google Cloud console, go to Routes.

Go to Routes
Click Effective routes.
Click Network, and then select a network.
Click Region, and then select a region.
Click View.
Click the Name of a policy-based route to view its details.

gcloud

To describe a policy-based route, use the policy-based-routes describe command.

gcloud network-connectivity policy-based-routes describe NAME

Replace NAME with the name of the route to describe.

API

Send a GET request to the policyBasedRoutes.get method.

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/policyBasedRoutes/ROUTE_NAME

Replace the following:

PROJECT_ID: the ID of the project.
ROUTE_NAME: the name of the policy-based route to describe.

Delete policy-based routes

You can delete a policy-based route to remove it from a VPC network.

Console

In the Google Cloud console, go to Routes.

Go to Routes
Click Effective routes.
Click Network, and then select a network.
Click Region, and then select a region.
Click View.
Click the Name of a policy-based route.
Click Delete, and then click Delete again to confirm.

gcloud

To delete a policy-based route, use the policy-based-routes delete command.

gcloud network-connectivity policy-based-routes delete NAME

Replace NAME with the name of the route to delete.

API

Send a DELETE request to the policyBasedRoutes.delete method.

DELETE https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/policyBasedRoutes/ROUTE_NAME

Replace the following:

PROJECT_ID: the ID of the project.
ROUTE_NAME: the name of the policy-based route to delete.

Compatibility

Special configuration is necessary to use policy-based routes in the following ways.

Use policy-based routes with GKE

If you create policy-based routes in VPC networks that have Google Kubernetes Engine (GKE) clusters, keep the following in mind:

Do not create policy-based routes whose destinations include cluster node or Pod IP addresses.
Do not create policy-based routes whose destinations include cluster control plane private endpoints.
- Some public Google Kubernetes Engine (GKE) clusters have Private Service Connect control plane private endpoints. For these clusters, by default, GKE creates the Private Service Connect control plane private endpoint in the primary IPv4 address range of the cluster's subnet. To choose a custom subnet range (of a subnet in the same region) for the Private Service Connect control plane private endpoint, see Create a cluster and select the control plane IP range.
- When you create a private GKE cluster, you specify an IP address range for the control plane private endpoint (--master-ipv4-cidr). Ensure that you don't create a policy-based route whose destination includes this range. For more information, see Endpoints in private clusters.

Policy-based routes and Private Service Connect for published services

Policy-based routes cannot be used to route traffic from VMs to Private Service Connect endpoints for published services or Private Service Connect backends for published services. When using policy-based routes and Private Service Connect for published services:

Use network tags so that policy-based routes apply to specific VMs.
Avoid creating policy-based routes with source or destination IP address ranges of 0.0.0.0/0.
If you need to create a policy-based route with a destination range that includes the IP address of a Private Service Connect endpoint or backend, create a higher priority policy-based route that skips other policy-based routes. Configure the destination of the higher priority policy-based route with a more specific IP address range that includes the IP address of the Private Service Connect endpoint or backend.

Policy-based routes and accessing Google APIs and services

Google Cloud does not support routing traffic to Google APIs and services through other VM instances or custom next hops—including to VM backends of next hop internal passthrough Network Load Balancers in policy-based routes.

If you use any of the following ways to access Google APIs and services, see the best practices that are listed in the following section:

Using Private Google Access to access Google APIs and services
Accessing Google APIs and services from VMs with external IP addresses
Using Private Service Connect endpoints for Google APIs
Using Private Service Connect backends for Google APIs

Best practices

We recommend the following best practices for the preceding ways of accessing Google APIs and services:

Use network tags so that the policy-based routes apply to specific VMs.
Avoid creating policy-based routes with source or destination ranges of 0.0.0.0/0.
If you create policy-based routes that include destination ranges that are used by Google APIs and services, Private Service Connect endpoints for Google APIs, or Private Service Connect backends for APIs, create higher priority policy-based routes that skip other policy-based routes. Set the destinations of these higher priority policy-based routes to match the IP addresses for Google APIs and services, Private Service Connect endpoints, or Private Service Connect backends that you use. IP address ranges used by Google APIs and services include the following:
- The IP addresses for the default domains used by Google APIs and services
- The Private Google Access virtual IP addresses (VIPs):
  - private.googleapis.com (199.36.153.8/30)
  - restricted.googleapis.com (199.36.153.4/30)