Using Forwarding Rules

Forwarding rules provide the frontend configuration for GCP load balancers, individual instances, and Cloud VPN gateways. This page describes their use with respect to load balancers.

Each forwarding rule references an IP address on which traffic is received. It also specifies an IP protocol — such as TCP or UDP — and port information, if necessary. The forwarding rule directs traffic to the appropriate configuration object for each type of load balancer.

For HTTP(S), SSL Proxy, and TCP Proxy load balancers, an external forwarding rule points to the appropriate target proxy resource. For network load balancers, a forwarding rule points to its target pool. For internal load balancers, an internal forwarding rule points to the load balancer's backend service.

See Global forwarding rules for information about global forwarding rules, which are used with global load balancers.

Forwarding rule properties

A forwarding rule resource contains the following properties that apply to Network Load Balancing:

name
[Required] The name of the forwarding rule. The name must be unique in this project, from 1-63 characters long and match the regular expression: [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
region

[Required] The region where this forwarding rule resides. For example:

https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/us-central1
IPAddress

[Optional] The regional, external IP address this forwarding rule will match against. All traffic that matches the IP address, protocol, and ports of this forwarding rule will be handled by this rule. The IP address must be a regional static external IP address. A global external IP address will not work with Network Load Balancing. If no address is specified, one is generated automatically.

target-instance / target-pool

[Required] The Target Instance or Target Pool resource that this forwarding rule directs traffic to. One or the other is required. Must be a fully-qualified URL such as:

https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-central1-b/targetInstances/example-instance

For target pools, the URL should look like this:

https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/targetPools/[TARGET_POOL]

The target pool or target instance must exist before you create your forwarding rule and must reside in the same region as the forwarding rule.

IPProtocol

[Optional] The type of protocol that this forwarding rule matches. Valid values are:

If left empty, this field will default to TCP. Also note that certain protocols can only be used with target pools or target instances:

  • If you use ESP, AH, or SCTP protocols, you must specify a target instance. It is not possible to specify a target pool when using these protocols.
  • If you use TCP or UDP, you can specify either a target pool or a target instance.
ports

[Optional] Up to 5 listed ports, a port range of up to 5, or ALL. Packets of the specified protocol sent to these ports will be forwarded to the appropriate target pool or target instance. You can only specify this field for TCP, UDP, and SCTP protocols.

For internal TCP/UDP load balancers, you can specify ALL, meaning that the forwarding rule matches traffic for all ports for the specified protocol.

Adding a forwarding rule

To add a new forwarding rule with gcloud compute, use the forwarding-rules create command:

gcloud compute forwarding-rules create [FORWARDING_RULE]
    [--address [ADDRESS]]
    [--description [DESCRIPTION]]
    [--ip-protocol [IP_PROTOCOL]]
    [--ports [PORTS] | ALL
    [--region [REGION]]
    [--target-instance [TARGET_INSTANCE] | --target-pool [TARGET_POOL]]
    [--target-instance-zone [TARGET_INSTANCE_ZONE]]

To add a forwarding rule using the API, send a POST request to the following URI:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/forwardingRules

Listing forwarding rules

To get a list of forwarding rules:

gcloud compute forwarding-rules list

In the API, send an empty GET request to:

https://www.googleapis.com/compute/v1/project/[PROJECT_ID]/regions/[REGION]/forwardingRules

Getting information about forwarding rules

To get information about a single forwarding rule:

gcloud compute forwarding-rules describe [FORWARDING_RULE]

In the API, send an empty GET request to:

GET https://www.googleapis.com/compute/v1/project/[PROJECT_ID]/regions/[REGION]/forwardingRules/[FORWARDING_RULE]

Updating the forwarding rule target

To change a forwarding rule's target pool using gcloud compute, use the forwarding-rules set-target command:

gcloud compute forwarding-rules set-target [FORWARDING_RULE]
    [--region [REGION]]
    [--target-instance [TARGET_INSTANCE] | --target-pool [TARGET_POOL]]
    [--target-instance-zone [TARGET_INSTANCE_ZONE]]

In the API, send a POST request to the following URI, passing the fully qualified URI to the target pool in the request body:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/forwardingRules/[FORWARDING_RULE]/setTarget

{
  "target": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/targetPools/[TARGET_POOL]"
}

Deleting forwarding rules

To delete a forwarding rule using gcloud compute, use the forwarding-rules delete command:

gcloud compute forwarding-rules delete [FORWARDING_RULE]

To delete a forwarding rule from the API, send a DELETE request to the following URI with an empty request body:

DELETE https://www.googleapis.com/compute/v1/project/[PROJECT_ID]/regions/[REGION]/forwardingRules/[FORWARDING_RULE]

Temporarily stopping a load balancer by deleting a forwarding rule

There are times when you might want to stop a load balancer for a limited time, without deleting it entirely. Examples of when this might be useful include the following:

  • Temporarily suspend charges for a load balancer
  • Temporarily pause incoming requests to your VM instances

If the forwarding rule points to a reserved IP address, you can delete the forwarding rule to stop a load balancer. This stops traffic to the destination that the forwarding rule is forwarding to. To restart the load balancer, re-create the forwarding rule, keeping the same IP address.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Load Balancing