Using target pools

External TCP/UDP Network Load Balancing can use either a backend service or a target pool to define the group of backend instances that receive incoming traffic. This page describes configuration options for target pool backends for Network Load Balancing. To learn how Network Load Balancing works with regional backend services instead, see network load balancer with backend services overview.

When a network load balancer's forwarding rule directs traffic to a target pool, the load balancer chooses an instance from the target pool based on a hash of the source IP address, the source port, the destination IP address, and the destination port.

If you intend your target pool to contain a single virtual machine (VM), consider using the protocol forwarding feature instead of load balancing.

Target pool properties

Target pools work with forwarding rules that handle TCP and UDP traffic. You must create a target pool before you can use it with a forwarding rule.

Target pools use legacy HTTP health checks.

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/<var>PROJECT_ID</var>/regions/<var>REGION</var>"
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.

backupPool

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

  1. If the ratio of healthy instances to total instances in the target pool is less than the failover ratio, traffic is sent to healthy instances in the backup pool.
  2. If the ratio of healthy instances to total instances in the target pool is less than the failover ratio but there are no remaining healthy instances in the backup pool, traffic is sent to the remaining healthy instances in the target pool.
  3. If the target pool is not empty and if all instances in both the target pool and the backup pool fail their health checks, traffic is sent to all instances in the target pool, as a last resort.
  4. If the target pool is empty and if all instances in the backup pool fail their health checks, traffic is sent to all instances in the backup pool, as a last resort.

Only one level of failover is supported. For example, if target pool A has backup pool B, and backup pool B has backup pool C, then traffic intended for target pool A can only be directed to backup pool B and not to backup pool C.

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.

Failover conditions

Conditions New connections go to
Failover ratio !=0, healthy VMs in target pool >= FR target pool
Failover ratio =0, healthy VMs in target pool > 0 target pool
Failover ratio !=0, healthy VMs in target pool < FR, and at least one VM in the backup pool is healthy backup pool
Failover ratio =0, healthy VMs in target pool = 0, and at least one VM in the backup pool is healthy backup pool
At least one VM is in the target pool, and all VMs in the target pool are unhealthy, and all VMs in the backup pool are unhealthy target pool (last resort)
No VMs are in the target pool, and all VMs in the backup pool are unhealthy backup pool (last resort)
No VMs are in the target pool, and no VMs are in the backup pool Traffic is dropped

Create a target pool

Console

To use the Cloud Console to create a target pool, use the Load balancing advanced menu.

  1. On the Advanced load balancing page, go to the Target pools tab.
    Go to Target pools
  2. Click Create a target pool.
  3. Enter a Name.
  4. Select a Region.
  5. Under Health check, click Create a new health check or Create another health check. These steps create a legacy HTTP health check which is a requirement for target pools.
    1. Enter basic-check as the Name of the health check.
    2. Retain the default settings.
    3. Click Save and continue.
  6. Depending on the resources available in the region that you selected, click either Select existing instances or Select existing instance groups.
    1. Under VM Instances or Instance groups, select the resources for the target pool.
  7. Click Create.

gcloud

To use gcloud compute to create a target pool, 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"]

Replace the following:

  • TARGET_POOL: a name for the target pool
  • BACKUP_POOL: a name for the backup target pool
  • DESCRIPTION: an optional description
  • FAILOVER_RATIO: a value between 0.0 and 1.0, which determines when the target pool is declared unhealthy
  • HEALTH_CHECK: a health check for this target pool
  • SESSION_AFFINITY: the method used to select a backend virtual machine instance

API

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/zones/ZONE/instances/INSTANCE",
       "https://www.googleapis.com/v1/compute/project/PROJECT_ID/zones/ZONE/instances/INSTANCE-2",
    ]
  }
 

Replace the following:

  • PROJECT_ID: the Google Cloud project ID
  • ZONE: the zone that the target pool's instances are in
  • INSTANCE, INSTANCE-2: the instances to be added to the target pool

Add or remove an instance from a target pool

Console

To use the Cloud Console to add or remove instances from a target pool, use the Load balancing advanced menu.

  1. On the Advanced load balancing page, go to the Target pools tab.
    Go to Target pools
  2. Click the name of the target pool that you want to modify.
  3. Click Edit.
  4. To add more resources to the target pool, use the Add an instance or Add an instance group list.
  5. To remove an instance or an instance group, click the X next to its name.
  6. Click Save.

gcloud

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

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

Replace the following:

  • TARGET_POOL: the name of the target pool
  • INSTANCE, INSTANCE-2: the name of the instance (or instances) to be added to the target pool

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

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

Replace the following:

  • TARGET_POOL: the name of the target pool
  • INSTANCE, INSTANCE-2: the name of the instance (or instances) to be removed from the target pool

API

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

Replace the following:

  • PROJECT_ID: the Google Cloud project ID
  • TARGET_POOL: the name of the target pool to be updated
  • REGION: the region that the target pool is in
  • ZONE: the zone that the updated instances are in
  • INSTANCE, INSTANCE-2: the instances to be added to the target pool

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

List target pools

Console

To see a list of target pools, use the load balancing advanced menu.

On the Advanced load balancing page, go to the Target pools tab.
Go to Target pools

The page displays a list of target pools.

gcloud

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

  gcloud compute target-pools list

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

API

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

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

Replace the following:

  • PROJECT_ID: the Google Cloud project ID
  • REGION: the region that the target pool is in

Describe a target pool

Console

To get information about a target pool, use the load balancing advanced menu.

  1. On the Advanced load balancing page, go to the Target pools tab.
    Go to Target pools
  2. To see detailed information, click on the name of the target pool.

gcloud

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

  gcloud compute target-pools describe TARGET_POOL

Replace the following:

  • TARGET_POOL: the name of the target pool

    When you end the Cloud Shell session, you lose these environment variables.

API

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

Replace the following:

  • PROJECT_ID: the Google Cloud project ID
  • TARGET_POOL: the name of the target pool to be updated
  • REGION: the region that the target pool is in

Get the health status of instances

Console

To get the health status of instances in a target pool, use the load balancing advanced menu.

  1. On the Advanced load balancing page, go to the Target pools tab.
    Go to Target pools
  2. Click the name of the target pool.
  3. The Target pool details page lists all the instances and their health status.

gcloud

To use gcloud compute 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:

  gcloud compute target-pools get-health TARGET_POOL

Replace the following:

  • TARGET_POOL: the name of the target pool

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

API

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

Replace the following:

  • PROJECT_ID: the Google Cloud project ID
  • TARGET_POOL: the name of the target pool to be updated
  • REGION: the region that the target pool is in
  • ZONE: the zone that the instance are in
  • INSTANCE: the instance whose health check status you are checking

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.

Console

To use the Cloud Console to delete a target pool, use the Load balancing advanced menu.

  1. On the Advanced load balancing page, go to the Target pools tab.
    Go to Target pools
  2. Click the name of the target pool.
  3. Click Delete.
  4. In the Delete a target pool window, click Delete.

gcloud

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

  gcloud compute target-pools delete TARGET_POOL

Replace the following:

  • TARGET_POOL: the name of the target pool to be deleted

API

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

Replace the following:

  • PROJECT_ID: the Google Cloud project ID
  • TARGET_POOL: the name of the target pool to be updated
  • REGION: the region that the target pool is in

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, the network load balancer 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.

Network Load Balancing uses legacy HTTP health checks to determine the health of instances in the target pool. A network load balancer can only use a legacy HTTP health check, not a legacy HTTPS health check.

Console

When using the Cloud Console, you can create a legacy HTTP health check either while creating a target pool or while creating a network load balancer with a target pool backend.

You cannot use the Cloud Console Health checks page to create a standalone legacy health check.

To remove the health check associated with a target pool:

  1. On the Advanced load balancing page, go to the Target pools tab.
    Go to Target pools
  2. Click the name of the target pool that you want to modify.
  3. Click Edit.
  4. Under Health check, select No health check.
  5. Click Save.

gcloud

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

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

Replace the following:

  • TARGET_POOL: the name of the target pool
  • HEALTH_CHECK: the legacy HTTP health check to be used with this target pool

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

Replace the following:

  • TARGET_POOL: the name of the target pool
  • HEALTH_CHECK: the legacy HTTP health check to be removed from this target pool

API

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

Replace the following:

  • PROJECT_ID: the Google Cloud project ID
  • TARGET_POOL: the name of the target pool to be updated
  • REGION: the region that the target pool is in
  • HEALTH_CHECK: the legacy HTTP health check to be associated or disassociated with the target pool

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

Console

To add a backup target pool:

  1. On the Advanced load balancing page, go to the Target pools tab.
    Go to Target pools
  2. Click the name of the target pool that you want to modify.
  3. Click Edit.
  4. Under Backup pool, select a backup target pool from the list.
  5. Set a Failover ratio.
  6. Click Save.

To remove a backup target pool:

  1. On the Advanced load balancing page, go to the Target pools tab.
    Go to Target pools
  2. Click the name of the target pool that you want to modify.
  3. Click Edit.
  4. Under Backup pool, select None.
  5. Click Save.

gcloud

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

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

Replace the following:

  • TARGET_POOL: the name of the target pool
  • BACKUP_POOL: a name for the backup target pool
  • FAILOVER_RATIO: a value between 0.0 and 1.0, which determines when the target pool is declared unhealthy

API

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

  POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/targetPools/TARGET_POOL/setBackup?failoverRatio=FAILOVER_RATIO

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

Replace the following:

  • PROJECT_ID: the Google Cloud project ID
  • TARGET_POOL: the name of the target pool to be updated
  • REGION: the region that the target pool is in
  • BACKUP_POOL: the name of the backup pool to be associated with the target pool
  • FAILOVER_RATIO: the failover ratio

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

What's next