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 TCP/UDP load balancer. We recommend enabling global access so that the internal TCP/UDP 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.

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 can specify one or more matching criteria. Traffic is redirected to the specified internal TCP/UDP load balancer if it matches all of your chosen criteria. You cannot create a policy-based route without including either network tags or Cloud Interconnect connection regions.

Create a policy-based route for traffic within a VPC network

gcloud

To create a policy-based route for traffic within a VPC network, use the policy-based-routes create command.

gcloud network-connectivity policy-based-routes create ROUTE_NAME \
    --source-range=IP_RANGE_A \
    --destination-range=IP_RANGE_B \
    --ip-protocol=IP_PROTOCOL \
    --network="projects/PROJECT_ID/global/networks/NETWORK" \
    --tags=NETWORK_TAGS \
    --next-hop-ilb-ip=LOAD_BALANCER_IP \
    --description=DESCRIPTION \
    --priority=PRIORITY

Replace the following:

ROUTE_NAME: the name of the policy-based route
IP_RANGE_A: the source IP CIDR range
IP_RANGE_B: the destination IP CIDR range
IP_PROTOCOL: the IP protocol of traffic to forward. Options are ALL, TCP, or UDP. The default is ALL.
PROJECT_ID: the ID of the project
NETWORK: the name of the network to forward traffic in
NETWORK_TAGS: one or more network tags. The policy-based route applies to any instances that have at least one of these tags. You can include multiple tags in a comma-separated list.
LOAD_BALANCER_IP: the IP address of the internal TCP/UDP load balancer
DESCRIPTION: an optional description of the route
PRIORITY: the priority of the policy-based route compared to other policy-based routes

To route response traffic in the same way as a policy-based route, create a second policy-based route with the same next hop and protocols, but switch the source and destination IP address ranges.

gcloud network-connectivity policy-based-routes create RETURN_ROUTE_NAME \
    --source-range=IP_RANGE_B \
    --destination-range=IP_RANGE_A \
    --ip-protocol=IP_PROTOCOL \
    --network="projects/PROJECT_ID/global/networks/NETWORK" \
    --tags=NETWORK_TAGS \
    --next-hop-ilb-ip=LOAD_BALANCER_IP \
    --description=DESCRIPTION \
    --priority=PRIORITY

Replace RETURN_ROUTE_NAME with the name of the return route.

API

To create a policy-based route for traffic within a VPC network, make a POST request to the policyBasedRoutes.create method.

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/policyBasedRoutes?policyBasedRouteId=ROUTE_NAME
{
  "filter": {
    "srcRange": "IP_RANGE_A",
    "destRange": "IP_RANGE_B",
    "ipProtocol": "IP_PROTOCOL",
    "protocolVersion": "IPv4"
  },
  "network": "projects/PROJECT_ID/global/networks/NETWORK",
  "nextHopIlbIp": "LOAD_BALANCER_IP",
  "description": "DESCRIPTION",
  "priority": "PRIORITY",
  "virtualMachine": {
    "tags": [
      "NETWORK_TAGS"
    ]
  }
}

Replace the following:

PROJECT_ID: the ID of the project
ROUTE_NAME: the name of the policy-based route
IP_RANGE_A: the source IP CIDR range
IP_RANGE_B: the destination IP CIDR range
IP_PROTOCOL: the IP protocol of traffic to forward. Options are ALL, TCP, or UDP. The default is ALL.
NETWORK: the name of the network
LOAD_BALANCER_IP: the IP address of the internal TCP/UDP load balancer
DESCRIPTION: an optional description of the route
PRIORITY: the priority of the policy-based route compared to other policy-based routes
NETWORK_TAGS: one or more optional network tags. The policy-based route applies to any instances that have at least one of these tags. You can include multiple tags in the following form: "tag1","tag2","tag3".

To route response traffic in the same way as a policy-based route, create a second policy-based route with the same next hop and protocols, but switch the source and destination IP address ranges.

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/policyBasedRoutes?policyBasedRouteId=RETURN_ROUTE_NAME
{
  "filter": {
    "srcRange": "IP_RANGE_B",
    "destRange": "IP_RANGE_A",
    "ipProtocol": "IP_PROTOCOL",
    "protocolVersion": "IPv4"
  },
  "network": "projects/PROJECT_ID/global/networks/NETWORK",
  "nextHopIlbIp": "LOAD_BALANCER_IP",
  "description": "DESCRIPTION",
  "priority": "PRIORITY",
  "virtualMachine": {
    "tags": [
      "NETWORK_TAGS"
    ]
  }
}

Replace RETURN_ROUTE_NAME with the name of the return route.

Create a policy-based route for use with a Cloud Interconnect connection

You can create policy-based routes to direct traffic that moves from an on-premises network to a VPC network through a Cloud Interconnect connection. When you create a policy-based route for Cloud Interconnect traffic, you specify a region, and the route is enabled for all Cloud Interconnect connections in that region. It is not possible to create a policy-based route for a specific Cloud Interconnect connection.

gcloud

To create a policy-based route for traffic that originates from an on-premises network, use the policy-based-routes create command.

gcloud network-connectivity policy-based-routes create ROUTE_NAME \
    --interconnect-attachment-region=INTERCONNECT_REGION \
    --tags=NETWORK_TAGS \
    --source-range=IP_RANGE_A \
    --destination-range=IP_RANGE_B \
    --ip-protocol=IP_PROTOCOL \
    --network="projects/PROJECT_ID/global/networks/NETWORK" \
    --next-hop-ilb-ip=LOAD_BALANCER_IP \
    --description=DESCRIPTION \
    --priority=PRIORITY

Replace the following:

ROUTE_NAME: the name of the policy-based route
INTERCONNECT_REGION: the region of the Cloud Interconnect connections to apply policy-based routes to
NETWORK_TAGS: one or more optional network tags. The policy-based route applies to any instances that have at least one of these tags. You can include multiple tags in a comma-separated list.
IP_RANGE_A: the source IP CIDR range
IP_RANGE_B: the destination IP CIDR range
IP_PROTOCOL: the IP protocol of traffic to forward. Options are ALL, TCP, or UDP. The default is ALL.
PROJECT_ID: the ID of the project
NETWORK: the name of the network to forward traffic in
LOAD_BALANCER_IP: the IP address of the internal TCP/UDP load balancer
DESCRIPTION: an optional description of the route
PRIORITY: the priority of the policy-based route compared to other policy-based routes

API

To create a policy-based route for traffic that originates from an on-premises network, make a POST request to the policyBasedRoutes.create method.

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/global/policyBasedRoutes?policyBasedRouteId=ROUTE_NAME
{
  "filter": {
    "srcRange": "IP_RANGE_A",
    "destRange": "IP_RANGE_B",
    "ipProtocol": "IP_PROTOCOL",
    "protocolVersion": "IPv4"
  },
  "interconnectAttachment": {
    "region": "INTERCONNECT_REGION"
  },
  "network": "projects/PROJECT_ID/global/networks/NETWORK",
  "nextHopIlbIp": "LOAD_BALANCER_IP",
  "description": "DESCRIPTION",
  "priority": "PRIORITY",
  "virtualMachine": {
    "tags": [
      "NETWORK_TAGS"
    ]
  }
}

Replace the following:

PROJECT_ID: the ID of the project
ROUTE_NAME: the name of the policy-based route
IP_RANGE_A: the source IP CIDR range
IP_RANGE_B: the destination IP CIDR range
IP_PROTOCOL: the IP protocol of traffic to forward. Options are ALL, TCP, or UDP. The default is ALL.
INTERCONNECT_REGION: the region of the Cloud Interconnect connections to apply policy-based routes to
NETWORK: the name of the network
LOAD_BALANCER_IP: the IP address of the internal TCP/UDP load balancer
DESCRIPTION: an optional description of the route
PRIORITY: the priority of the policy-based route compared to other policy-based routes
NETWORK_TAGS: one or more optional network tags. The policy-based route applies to any instances that have at least one of these tags. You can include multiple tags in the following form: "tag1","tag2","tag3".

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.

gcloud

To list policy-based routes, use the policy-based-routes list command.

gcloud network-connectivity policy-based-routes list

API

To list policy-based routes, make 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.

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

To describe a policy-based route, make 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.

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

To delete a policy-based route, make 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