Using Target Pools

A Target Pool resource defines a group of instances that receive incoming
traffic from forwarding rules. When a forwarding rule directs traffic to a
target pool, Google Cloud Load Balancing picks an instance from these target pools
based on a hash of the source IP and port and the destination IP and port. See
the
Load distribution algorithm
for more information about how traffic is distributed to instances.

Note: If you intend your target pool to contain a single virtual machine
instance, you should consider using the
Protocol Forwarding feature instead.

Target pools can only be used with forwarding rules that handle TCP and UDP
traffic. You must
create a target pool before you can use it with a forwarding rule. Each project
can have up to 50 target pools. A target pool can have only one health check.
Network load balancing only supports
httpHealthChecks.

Target pool properties

A target pool is made up of the following properties:

name

[Required] The name of this target pool. 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.

description

[Optional] A user-defined description of this target pool.

region

[Required] The fully-qualified URL to the region where this target pool
should live. This should be the same region where your desired instances
will live. For example:

[Optional] An optional list of health checks for this target pool. Only
one health check can be attached to a particular target pool. See
Health checking for more information.

instances[ ]

[Required] A list of instance URLs that should handle traffic for this
target pool. All instances must reside in the same region as the target
pool, but instances can belong to different zones within a single region.
For example:

[Optional] Controls the method used to select a backend virtual machine
instance. You can only set this value during the creation of the target
pool. Once set, you cannot modify this value. The hash method selects a
backend based on a subset of the following 5 values:

Source / Destination IP

Source / Destination Port

Layer 4 Protocol (TCP, UDP)

Possible hashes are:

NONE (i.e., no hash specified) (default)

5-tuple hashing, which uses the source and destination IPs, source
and destination ports, and protocol. Each new connection can end up on
any instance, but all traffic for a given connection will stay on the
same instance, if the instance stays healthy.

CLIENT_IP_PROTO

3-tuple hashing, which uses the source and destination IPs
and the protocol. All connections from a client will end up on
the same instance as long as they use the same protocol
and the instance stays healthy.

CLIENT_IP

2-tuple hashing, which uses the source and destination IPs. All
connections from a client will end up on the same instance
regardless of protocol as long as the instance stays healthy.

5-tuple hashing provides a good distribution of traffic across many
virtual machines. However, a second session from the same client may
arrive on a different instance because the source port may change. If you
want all sessions from the same client to reach the same backend, as long
as the backend stays healthy, you can specify CLIENT_IP_PROTO or
CLIENT_IP options.

In general, if you select a 3-tuple or 2-tuple method, it will provide for
better session affinity than the default 5-tuple method, but the overall
traffic may not be as evenly distributed.

Fragmented UDP packets: If you are load balancing UDP traffic that is
likely to be fragmented, set session affinity to CLIENT_IP_PROTO
or CLIENT_IP. Do not use NONE (5-tuple hashing). This is because
UDP fragments other than the first one do not carry the port number,
and the load balancer may drop the fragments without the port. See
Load balancing and fragmented UDP packets
for more information.

Caution: If a large percentage of
your clients are behind a proxy server, you
should not use CLIENT_IP_PROTO or CLIENT_IP.
Using them sends all traffic from those clients to the same instance.

backupPool

[Optional] A fully-qualified URL to another target pool resource. You
must also define failoverRatio to use this feature. If
the ratio of healthy virtual machines in your primary target pool falls
below the failoverRatio, Google Cloud Load Balancing sends traffic to your backup
pool. You can only provide one backup pool per primary target pool. The
backup pool must be in the same region as the primary target pool. If the
ratio of healthy instances in your primary target pool falls below your
configured failover ratio, Google Cloud Load Balancing uses the following rules to
route your traffic:

If a primary target pool is declared unhealthy (falls below the
failover ratio), traffic will be sent to healthy instances in the
backup pool.

If the primary target pool is declared unhealthy, but there are no
remaining healthy instances in the backup pool, traffic is sent to the
remaining healthy instances in the primary pool.

If the primary pool is unhealthy and there are no remaining healthy
instances in either pools, traffic will be sent to all instances in the
primary pool so as to not drop traffic.

If the primary pool doesn't contain any instances, and none of the
instances in the backup pool are healthy, traffic will be sent to all
instances in the backup pool so as to not drop any traffic.

At most, only one level of failover is supported. For example, if target
pool A has backup pool B and back pool B has a backup pool C, then traffic
intended for target pool A can only reach up to backup pool B and not C.

Note: If you intend to use
backup target pools, you
should set up health checks as backup target pools will not work correctly
without health checks enabled.

failoverRatio

[Optional] A float between 0.0 and 1.0, which determines when this
target pool is declared unhealthy. For example, if this value is set to .1,
then this target pool is declared unhealthy if the number of healthy instances
is below .1 (10%). If the failover ratio is 0.0, then at least one
backend must be healthy for the pool to be considered healthy. If the
failover ratio is set to 1.0, then all instances must be healthy for the
pool to be considered healthy. You must define this if you define the
backupPool field.

The diagram below helps visualize how the failover ratio and backup pool works
together:

Note: If you remove an instance from a target pool without draining it first, you will
break all TCP sessions to that instance. To remove an instance safely, first
drain the instance by having it fail its
health check. After TCP sessions
close naturally, remove the instance from the pool.

Delete a target pool

To delete a target pool, you must first make sure that the target pool is not
being referenced by any forwarding rules. If a forwarding rule is currently
referencing a target pool, you must delete the forwarding rule to remove the
reference.

Add or remove a health check from a target pool

Health check objects are standalone, global resources that can be associated or
disassociated from any target pool.

If a target pool has no associated health check, Google Cloud Load Balancing
will treat all instances as healthy and send traffic to all instances in the
target pool. However, if you query for the health status of a target pool
without a health check, the status will return as unhealthy to indicate that
the target pool does not have a health check. We recommend that your target
pools should have associated health checks to help you manage your instances.

Add or remove a backup target pool

When you first create a target pool, you can choose to apply a backup target
pool that receives traffic if your primary target pool becomes unhealthy.

If you have never set up a backup target pool before, you should also set up
health checks for the feature to work
correctly.

Note: If your target pool currently has the
sessionAffinity field set, resizing the target pool could
cause requests that come from the same IP to go to a different instance
initially. Eventually, all connections from the IP will go to the same virtual
machine, as the old connections close.