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:
-
AH
: Specifies the IP Authentication Header protocol. -
ESP
: Specifies the IP Encapsulating Security Payload protocol. -
SCTP
: Specifies the Stream Control Transmission Protocol. -
TCP
: Specifies the Transmission Control Protocol. -
UDP
: Specifies the User Datagram Protocol.
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
, orSCTP
protocols, you must specify a target instance . It is not possible to specify a target pool when using these protocols. -
If you use
TCP
orUDP
, 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
, andSCTP
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>