Target pools

A Target Pool resource defines a group of instances that should receive incoming traffic from forwarding rules. When a forwarding rule directs traffic to a target pool, Google Compute Engine 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.

Target pools can only be used with forwarding rules that handle TCP and UDP traffic. For all other protocols, you must create a target instance. 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.

Network load balancing supports Compute Engine Autoscaler, which allows users to perform autoscaling on the instance groups in a target pool based on CPU utilization or custom Stackdriver Monitoring metrics. For more information, see Scaling based on network load balancing.

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:

"region" : "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]"
healthChecks[ ]

[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:

"instances" : [
  "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE]",
  "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE-2]"
]

sessionAffinity

[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 portion of your clients are behind a proxy server, you should not use CLIENT_IP_PROTO or CLIENT_IP. Using them would end up sending all the 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 Compute Engine 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 Compute Engine uses the following rules to route your traffic:

  1. If a primary target pool is declared unhealthy (falls below the failover ratio), traffic will be sent to healthy instances in the backup pool.
  2. 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.
  3. 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.
  4. 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:

Visualization of fail over ratio
  and backup pools

Add a target pool

To add a target pool using gcloud compute, use the target-pools create command:

gcloud compute target-pools create TARGET_POOL \
    [--backup-pool BACKUP_POOL] \
    [--description DESCRIPTION] \
    [--failover-ratio FAILOVER_RATIO] \
    [--http-health-check HEALTH_CHECK] \
    [--session-affinity SESSION_AFFINITY; default="NONE"]

To create a target pool in the API, make a HTTP POST request to the following URI:

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

{
  "name": name,
  "instances": [
     "https://www.googleapis.com/v1/compute/project/[PROJECT_ID]/[ZONE]/[ZONE]/instances/[INSTANCE]",
     "https://www.googleapis.com/v1/compute/project/[PROJECT_ID]/[ZONE]/[ZONE]/instances/[INSTANCE-2]",
  ]
}

Add or remove an instance from a target pool

To add instances to a target pool using gcloud compute, use the target-pools add-instances command:

gcloud compute target-pools add-instances TARGET_POOL \
    --instances INSTANCE [INSTANCE ...]

To remove instances, use the target-pools remove-instances command:

gcloud compute target-pools remove-instances TARGET_POOL \
    --instances INSTANCE,[INSTANCE ...]

In the API, send a POST request to the following URIs:

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

The body of your request should include the fully-qualified URIs to the instances that you want to add or remove:

{
 "instances": [
    {"instance": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE]"},
    {"instance": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE-2]"}
  ]
}

For more information, see the API reference documentation for the targetPools.addInstance and targetPools.removeInstance methods.

List target pools

To list existing target pools using gcloud compute, use the target-pools list command:

gcloud compute target-pools list

For more verbose output, use the describe command and specify a pool name:

gcloud compute target-pools describe TARGET_POOL

In the API, send a GET request to the following URI:

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

Get a target pool

To get information about a single target pool using gcloud compute, use the target-pools describe command:

gcloud compute target-pools describe TARGET_POOL

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

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

Get the health status of instances

To check the current health status of an instance in your target pool or of all instances in the target pool, you can use the gcloud compute target-pools get-health command.

To check the current health of an instance in your target pool, or of all instances in the target pool using gcloud compute, use the target-pools get-health command:

gcloud compute target-pools get-health TARGET_POOL \
    [--fields FIELDS [FIELDS ...]] \
    [--format FORMAT; default="yaml"] \
    [--limit LIMIT] \
    [--raw-links] \
    [--sort-by SORT_BY]

The command returns the health status as determined by the configured health check, either healthy or unhealthy.

In the API, make a HTTP POST request to the following URI with the instance specified in the request body:

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

{
  "instance": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE]"
}

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.

To delete a target pool with gcloud compute, use the target-pools delete command:

gcloud compute target-pools delete TARGET_POOL

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

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

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 Compute Engine 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.

To add a health check to a target pool with gcloud compute, use the target-pools add-health-checks command:

gcloud compute target-pools add-health-checks TARGET_POOL \
    --http-health-check HEALTH_CHECK

To remove a health check, use the target-pools remove-health-checks command:

gcloud compute target-pools remove-health-checks TARGET_POOL \
  --http-health-check HEALTH_CHECK

To associate or disassociate a health check using the API, make a HTTP POST request to the appropriate URIs:

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

The body of your request should contain the health check to associate or disassociate:

{
  "healthCheck": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/httpHealthChecks/HEALTH_CHECK"
}

For more information, see the API reference documentation for targetPools.addHealthCheck and targetPools.removeHealthCheck.

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.

To update the a backup pool resource with gcloud compute, use the target-pools set-backup command:

gcloud compute target-pools set-backup TARGET_POOL \
    --backup-pool BACKUP_POOL \
    --failover-ratio FAILOVER_RATIO

To make a request to update or remove a backup pool through the API, send a POST request to the following URI:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/targetPools/[TARGET_POOL]/setBackup?failoverRatio=FAILOVER

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

If you define an empty target, or do not define a failover ratio, the backup pool behavior will be disabled for this target pool.

For more information, see the API reference documentation for targetPools.setBackup.

Send feedback about...

Compute Engine Documentation