Forwarding rules

Forwarding rules work in conjunction with target pools and target instances to support load balancing and protocol forwarding features. To use load balancing and protocol forwarding, you must create a forwarding rule that directs traffic to specific target pools (for load balancing) or target instances (for protocol forwarding). It is not possible to use either of these features without a forwarding rule.

Forwarding Rule resources live in the Forwarding Rules collection. Each forwarding rule matches a particular IP address, protocol, and optionally, port range to a single target pool or target instance. When traffic is sent to an external IP address that is served by a forwarding rule, the forwarding rule directs that traffic to the corresponding target pool or target instances.

See Global forwarding rules for global forwarding rules that are used with HTTP/HTTPS load balancing.

Forwarding rule properties

A forwarding rule object 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 will look like:

  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] A single port or single contiguous port range, ranging from low to high, for which this forwarding rule matches. Packets of the specified protocol sent to these ports will be forwarded on to the appropriate target pool or target instance. If this field is left empty, then the forwarding matches traffic for all ports for the specified protocol. For example:

  200-65536

You can only specify this field for `TCP`, `UDP`, and `SCTP` protocols.

Add 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]
    [--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, passing the forwarding rule properties in the body:

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

{
  "name": NAME,
  "IPAddress": [EXTERNAL_IP],
  "IPProtocol": [TCP] | [UDP],
  "ports": [PORTS],
  "target": [TARGET_HTTP_PROXY] | [TARGET_INSTANCE] | [TARGET_POOL]
}

List 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

Get 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]

Update 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]"
}

Delete 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]

Send feedback about...

Compute Engine Documentation