Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



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. You can create up to 50 forwarding rule objects per project.

Forwarding rule properties

A forwarding rule object contains the following properties:

name
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

The region where this forwarding rule resides. For example:

https://www.googleapis.com/compute/v1/projects/<project-id>/regions/us-central1
IPAddress

A single IP address this forwarding rule matches to. All traffic directed to this IP address will be handled by this forwarding rule. The IP address must be a static reserved IP address or, if left empty, an ephemeral IP address is assigned to the forwarding rule upon creation. For example:

192.0.2.1
target-instance / target-pool

The Target Instance or Target Pool resource that this forwarding rule directs traffic to. Must be a fully-qualified URL such as:

http://www.googleapis.com/compute/v1/projects/<project-id>/zones/us-central1-b/targetInstances/example-instance

For target pools, the URL will look like:

http://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

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 .
port-range

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.

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]
    [--port-range [PORT | PORT-PORT]]
    [--global | --region REGION]
    [--target-http-proxy TARGET_HTTP_PROXY | --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_OR_UDP,
  "portRange": PORT | PORT-PORT,
  "target": TARGET_HTTP_PROXY | TARGET_INSTANCE | TARGET_POOL
}

In the API, send an empty GET request to the following URI:

GET https://www.googleapis.com/compute/v1/project/<project-id>/regions/<region>/forwardingRules

Listing forwarding rules

To get a list of forwarding rules:

$ gcloud compute forwarding-rules list

For verbose output, use describe without specifying a forwarding rule name:

$ gcloud compute forwarding-rules describe

In the API, send an empty GET request to:

https://www.googleapis.com/compute/v1/project/<project-id>/regions/<region>/forwardingRules

Getting 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/NAME

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
    [--global | --region REGION]
    [--target-http-proxy TARGET_HTTP_PROXY | --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>

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.