Use policy-based routes

Policy-based routes let you select a next hop based on more thana 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 updateto the latest version of theGoogle Cloud CLI.
You mustenabletheNetwork Connectivity APIin your project.
You need aninternal passthrough Network Load Balancer. We recommendenabling global accessso that the internal passthrough Network Load Balancer does not drop packets from regions other thanthe 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 theCompute Network Admin (roles/compute.networkAdmin) IAM role on your project. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined 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 IPaddress ranges, and protocols that determine which packets the route appliesto. The policy-based route applies to packets that matchallof the specified classification criteria.
Next hop: a next hop internal passthrough Network Load Balancer or a next hop thatskips otherpolicy-based routes.

Console

In the Google Cloud console, go toRoutes.
Go to Routes
ClickRoute management.
ClickCreate route.
Enter a name for the route.
Optional: Enter a description.
ClickNetwork, and then select the network where you want to add thepolicy-based route.
ClickRoute type, and then selectPolicy-based route.
Select an IP version.
In theRoute scope section, do one of the following:
- To make the route apply to all virtual machine (VM) instances, VLANattachments for Cloud Interconnect, and Cloud VPN tunnels inthe Virtual Private Cloud network, selectThis route applies to all VMinstances, VLAN attachments, and VPN tunnels.
  Google recommends caution when creating routes of this type. Theroute is applied to all egress packets that match the classificationcriteria, which can include egress traffic from the backend of theinternal passthrough Network Load Balancer.
- To make the route apply only to certain VM instances, selectThis route only applies to VM instances, and then enter thenetwork tags of the VMs that this route should apply to. Youcan enter multiple network tags in a comma-separated list.
- To make the route apply to all VLAN attachments forCloud Interconnect in the route's VPC network,selectThis route only applies to VLAN attachments.
- To make the route apply to VLAN attachments forCloud Interconnect in a specific region, selectThis route only applies to VLAN attachments, and thenselect the region of the VLAN attachments. It is not possibleto create a policy-based route that applies to a specific VLANattachment.
In theClassification criteria section, do the following:
1. Enter a source IP range.
2. Enter a destination IP range.
3. ClickProtocol, and then select the protocols that this routeapplies to.
Enter a priority.
In theNext hop section, clickNext hop, and then do thefollowing:
- To specify a next hop internal passthrough Network Load Balancer, selectSpecify a forwardingrule of the internal passthrough Network Load Balancer, and thendo the following:
  - To select a forwarding rule from a list of existing forwardingrules:
    1. SelectIn use by the forwarding rule of an internal loadbalancer in the current project.
    2. ClickForwarding rule IP address, and then select an IPaddress that's associated with an internal load balancer in theselected project.
  - To enter an IP address:
    1. SelectUnused.
    2. In theForwarding rule IP address field, enter an IPaddress, without a prefix length. The IP address must come fromone of the following sources:
      - The IP address ranges of the VPC network whereyou are creating this policy-based route.
      - The IP address ranges of a VPC network thatis connected to the route's VPC network throughVPC Network Peering.
    You can specify an IP address that isalready associated with an internal passthrough Network Load Balancer's forwarding rule, oryou can specify an unused IP address and create the forwardingrule after you create this policy-based route.
- To create a policy-based route that skips other policy-based routes,selectSkip other policy-based routes.
ClickCreate.

gcloud

Use thepolicy-based-routes create command.

To apply the route to all VM instances, VLAN attachments forCloud Interconnect, and Cloud VPN tunnels in the Virtual Private Cloudnetwork, use the following command.
Google recommends caution when creating routes of this type. Theroute is applied to all egress packets that match the classificationcriteria, which can include egress traffic from the backend of theinternal passthrough Network Load Balancer.
```
gcloud network-connectivity policy-based-routes createROUTE_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 toforward. Options areALL,TCP, orUDP. The default isALL.
- IP_VERSION: a single Internet Protocol versionthat this route applies to. Specify eitherIPv4 orIPv6.The default isIPv4.
- PROJECT_ID: the ID of the project.
- NETWORK: the name of the network to apply thepolicy-based route to.
- NEXT_HOP: a single IP address, without a prefixlength, for the route's next hop internal passthrough Network Load Balancer. Specify an IPv4address as a next hop for IPv4 traffic, or specify an IPv6 address forIPv6 traffic.The load balancer must be in either the same VPC networkas the policy-based route or in a VPC network that isconnected to the route's VPC network throughVPC Network Peering.
  If the route applies to IPv6 traffic, you mustset up the load balancer with subnets that have IPv6 address ranges.
- DESCRIPTION: an optional description of theroute.
- PRIORITY: the priority of the policy-based routecompared to other policy-based routes.

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

gcloud network-connectivity policy-based-routes createROUTE_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

ReplaceNETWORK_TAGS with one or more network tagsof the VMs to apply the route to. You can include multiple network tagsin 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 VLANattachments for Cloud Interconnect in a specific region or to all VLANattachments for Cloud Interconnect in a VPC network.
```
gcloud network-connectivity policy-based-routes createROUTE_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
```
ReplaceINTERCONNECT_REGION with the region ofthe VLAN attachments for Cloud Interconnect to apply the route to. Toapply the policy-based route to all VLAN attachments forCloud Interconnect in the route's VPC network, useall.

To specify a next hop that skips other policy-based routes forspecific VMs that are identified by network tags, use thefollowing command:

gcloud network-connectivity policy-based-routes createROUTE_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 aPOST request to thepolicyBasedRoutes.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 forCloud Interconnect, and Cloud VPN tunnels in the Virtual Private Cloudnetwork, include the following request body.
Google recommends caution when creating routes of this type. Theroute is applied to all egress packets that match the classificationcriteria, which can include egress traffic from the backend of theinternal 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 toforward. Options areALL,TCP, orUDP. The default isALL.
- IP_VERSION: a single Internet Protocol versionthat the route applies to. Specify eitherIPv4 orIPv6. The defaultisIPv4.
- NETWORK: the name of the network to apply thepolicy-based route to. The route applies to egress traffic from instancesin this network that meet the other classification criteria.
- NEXT_HOP: a single IP address, without a prefixlength, for the route's next hop internal passthrough Network Load Balancer. Specify an IPv4address as a next hop for IPv4 traffic, or specify an IPv6 address forIPv6 traffic.The load balancer must be in either the same VPC networkas the policy-based route or in a VPC network that isconnected to the route's VPC network throughVPC Network Peering.
  If the route applies to IPv6 traffic, you mustset up the load balancer with subnets that have IPv6 address ranges.
- DESCRIPTION: an optional description of theroute.
- PRIORITY: the priority of the policy-based routecompared to other policy-based routes.

To apply the route only to certain VM instances, include the followingrequest 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"    ]  }}

ReplaceNETWORK_TAGS with one or more networktags. The policy-based route applies to egress traffic from instances thathave at least one of these tags. You can include multiple tags in thefollowing 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 createa 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"}
```
ReplaceINTERCONNECT_REGION with the region ofthe VLAN attachments for Cloud Interconnect to apply this route to.To apply the policy-based route to all VLAN attachments forCloud Interconnect in the route's VPC network, useall.

To specify a next hop that skips other policy-based routes forspecific VMs that are identified by network tags, use thefollowing 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 Testsis a diagnostics tool that lets you check connectivity between endpoints in yournetwork. It analyzes your configuration and, in some cases, performs run-timeverification. Connectivity Tests supports policy-based routes. To runConnectivity Tests with your policy-based routes, seeCreate and run Connectivity Tests.

List policy-based routes

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

Console

In the Google Cloud console, go toRoutes.
Go to Routes
- To view all policy-based routes in a VPC network andregion, do the following:
  1. ClickEffective routes.
  2. ClickNetwork, and then select a network.
  3. ClickRegion, and then select a region.
  4. ClickView.
- To view all policy-based routes in a project, do the following:
  1. ClickRoute management.

gcloud

Use thepolicy-based-routes list command.

gcloud network-connectivity policy-based-routes list

API

Send aGET request to thepolicyBasedRoutes.list method.

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

ReplacePROJECT_ID with the ID of the project tolist 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 toRoutes.
Go to Routes
ClickEffective routes.
ClickNetwork, and then select a network.
ClickRegion, and then select a region.
ClickView.
Click the name of a policy-based route to view its details.

gcloud

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

gcloud network-connectivity policy-based-routes describeNAME

ReplaceNAME with the name of the route to describe.

API

Send aGET request to thepolicyBasedRoutes.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 todescribe.

Delete policy-based routes

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

Console

In the Google Cloud console, go toRoutes.
Go to Routes
ClickEffective routes.
ClickNetwork, and then select a network.
ClickRegion, and then select a region.
ClickView.
Click the name of a policy-based route.
ClickDelete, and then clickDelete again to confirm.

gcloud

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

gcloud network-connectivity policy-based-routes deleteNAME

ReplaceNAME with the name of the route to delete.

API

Send aDELETE request to thepolicyBasedRoutes.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 todelete.

Compatibility

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