Using target pools

A target pool is a group of backend instances that receive incoming traffic fromexternal passthrough Network Load Balancers. All backend instances of a target pool must reside in the sameGoogle Cloud region.External passthrough Network Load Balancers canuse either a backend service or a target pool to define the group of backendinstances. If you're creating new external passthrough Network Load Balancers, we recommendusing backendservices.

This page describes configuration options for target pool backends. When anexternal passthrough Network Load Balancer's forwarding rule directs traffic to a target pool, the loadbalancer chooses an instance from the target pool based on ahash of thesource IP address, the source port, the destination IP address, and thedestination port.

If you intend your target pool to contain a single virtual machine (VM),consider using theprotocolforwarding feature instead of loadbalancing.

Note: This page describes how to configure a specific load balancer component orfeature before or after you've already created a load balancer. Working withspecific components is useful for advanced configurations and necessary for someconfiguration options. Before using the information on this page, know the typeof Google Cloud load balancerthat you need.

Target pool properties

Target pools work with forwarding rules that handleTCP andUDPtraffic. You must create a target pool before you can use it with a forwardingrule.

Target pools uselegacy HTTP healthchecks.

A target pool is made up of the following properties:

name

The name of this target pool. The name must be unique in thisproject, 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 alowercase letter, and all following characters must be a dash, lowercaseletter, or digit, except the last character, which cannot be a dash.

description

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

region

The fully qualified URL of the target pool's region. The regionshould be the same region where your backend instances reside. 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 onehealth check can be attached to a particular target pool. SeeHealthchecking for more information.

instances[ ]

A list of instance URLs that should handle traffic for this targetpool. All instances must reside in the same region as the target pool, butinstances 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 machineinstance. 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 basedon 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, sourceand destination ports, and protocol. Each new connection can end up onany instance, but all traffic for a given connection will stay on thesame instance, if the instance stays healthy.
CLIENT_IP_PROTO: 3-tuple hashing, which uses the source and destination IPsand the protocol. All connections from a client will end up onthe same instance as long as they use the same protocoland the instance stays healthy.
CLIENT_IP: 2-tuple hashing, which uses the source and destination IPs. Allconnections from a client will end up on the same instanceregardless of protocol as long as the instance stays healthy.

5-tuple hashing provides a good distribution of traffic across manyvirtual machines. However, a second session from the same client mayarrive on a different instance because the source port may change. If youwant all sessions from the same client to reach the same backend, as longas the backend stays healthy, you can specifyCLIENT_IP_PROTO orCLIENT_IP options.

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

Fragmented UDP packets: If you are load balancing UDP traffic that islikely to be fragmented, set session affinity toCLIENT_IP_PROTOorCLIENT_IP. Don't useNONE (5-tuple hashing). This is becauseUDP fragments other than the first one don't carry the port number,and the load balancer may drop the fragments without the port. SeeLoad balancing and fragmented UDPpacketsfor more information.

Caution: If a large percentage ofyour clients are behind a proxy server, don'tuseCLIENT_IP_PROTO orCLIENT_IP.Using them sends all traffic from those clients to the same instance.

backupPool

Optional. A fully qualified URL to another target pool resource. A backuppool is a target pool that another target pool references. Youmust also define failoverRatio to use this feature. Ifthe ratio of healthy virtual machines in your target pool fallsbelow thefailoverRatio, the external passthrough Network Load Balancer sends traffic to your backuppool. You can only provide one backup pool per target pool. Thebackup pool must be in the same region as the target pool. If theratio of healthy instances in your target pool falls below yourconfigured failover ratio, the external passthrough Network Load Balancer uses the following rules toroute your traffic:

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.
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.
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.
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 targetpool A has backup pool B, and backup pool B has backup pool C, then trafficintended for target pool A can only be directed to backup pool B and notto backup pool C.

failoverRatio

Optional. A float between0.0 and1.0, which determines when thistarget pool is declared unhealthy. For example, if this value is set to0.1,then this target pool is declared unhealthy if the number of healthy instancesare less than0.1 (10%). If the failover ratio is0.0, then at least onebackend must be healthy for the pool to be considered healthy. If thefailover ratio is set to1.0, then all instances must be healthy for thepool to be considered healthy. You must define this if you define thebackupPool 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

Target pools can't be created in the Google Cloud console.You can create a target pool by using the Google Cloud CLI or the API.

To learn how to create a target pool-based external passthrough Network Load Balancer by using theGoogle Cloud CLI, seeSet up an external passthrough Network Load Balancer with a targetpool.

gcloud

To usegcloud compute to create a target pool, use thetarget-poolscreate command:

  gcloud compute target-pools createTARGET_POOL \      [--backup-pool=BACKUP_POOL] \      [--description=DESCRIPTION] \      [--failover-ratio=FAILOVER_RATIO] \      [--http-health-check=HEALTH_CHECK] \      [--region=REGION]      [--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: a description of the target pool
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
REGION: a region of the target pool
SESSION_AFFINITY: themethodused to select a backend virtual machine instance

API

To create a target pool in the API, make aHTTP POST request tothe 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 instancesare in
INSTANCE,INSTANCE-2: theinstances to be added to the target pool

Add or remove an instance from a target pool

Console

Target pools can't be edited in the Google Cloud console.You can edit a target pool by using the Google Cloud CLI or the API.

gcloud

To usegcloud compute to add instances to a target pool, use thetarget-pools add-instances command:

  gcloud compute target-pools add-instancesTARGET_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 thetarget-pools remove-instances command:

  gcloud compute target-pools remove-instancesTARGET_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

Note: Removing an instance from a target pool without draining it first breaksall TCP sessions to that instance. To remove an instance safely, firstdrain the instance by making it fail its health check. After TCP sessionsclose, remove the instance from the 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 theinstances 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 beupdated
REGION: the region that the target pool is in
ZONE: the zone that the updated instances are in
INSTANCE,INSTANCE-2: theinstances to be added to the target pool

For more information, see the API reference documentation for thetargetPools.addInstance andtargetPools.removeInstancemethods.

List target pools

Console

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

On theAdvanced load balancing page, go to theTarget pools tab.
Go to Target pools

The page displays a list of target pools.

gcloud

To usegcloud compute to list existing target pools, use thetarget-pools list command:

  gcloud compute target-pools list

For more verbose output, use thedescribe command and specifya 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.

On theAdvanced load balancing page, go to theTarget pools tab.
Go to Target pools
To see detailed information, click the name of the target pool.

gcloud

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

  gcloud compute target-pools describeTARGET_POOL

ReplaceTARGET_POOL with the name of the target pool.

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 beupdated
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 balancingadvanced menu.

On theAdvanced load balancing page, go to theTarget pools tab.
Go to Target pools
Click the name of the target pool.
TheTarget pool details page lists all the instances and their healthstatus.

gcloud

To usegcloud compute to check the current health status of an instancein your target pool or of all instances in the target pool, you can use thegcloud compute target-pools get-health command:

  gcloud compute target-pools get-healthTARGET_POOL

ReplaceTARGET_POOL with the name of the targetpool.

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

API

In the API, make a HTTP POST request to the following URI with the instancespecified 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 beupdated
REGION: the region that the target pool is in
ZONE: the zone that the instance are in
INSTANCE: the instance whose health check statusyou are checking

Delete a target pool

To delete a target pool, you must first make sure that the target pool is notbeing referenced by any forwarding rules. If a forwarding rule isreferencing a target pool, you must delete the forwarding rule to remove thereference.

Console

To use the Google Cloud console to delete a target pool, use the Loadbalancing advanced menu.

On theAdvanced load balancing page, go to theTarget pools tab.
Go to Target pools
Click the name of the target pool.
ClickDelete.
In theDelete a target pool window, clickDelete.

gcloud

To usegcloud compute to delete a target pool, use thetarget-pools delete command:

  gcloud compute target-pools deleteTARGET_POOL

ReplaceTARGET_POOL with the name of the target poolto 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 beupdated
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 disassociatedfrom any target pool.

If a target pool has no associated health check, the external passthrough Network Load Balancerwill treat all instances as healthy and send traffic to all instances in thetarget pool. However, if you query for the health status of a target poolwithout a health check, the status will return asunhealthy to indicate thatthe target pool does not have a health check. We recommend that your targetpools should have associated health checks to help you manage your instances.

External passthrough Network Load Balancers uselegacy HTTP healthchecks todetermine the health of instances in the target pool. An external passthrough Network Load Balancer canonly use a legacy HTTP health check, not a legacy HTTPS health check.

Console

When using the Google Cloud console, you can create a legacy HTTPhealth check whilecreating an external passthrough Network Load Balancer with a target poolbackend.

Youcannot use the Google Cloud consoleHealth checks page to createa standalone legacy health check.

gcloud

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

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

Replace the following:

TARGET_POOL: the name of the target pool
HEALTH_CHECK: the legacy HTTP healthcheck to be used with this target pool

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

  gcloud compute target-pools remove-health-checksTARGET_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 beremoved from this target pool

API

To associate or disassociate a health check using the API, make aHTTP POSTrequest 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 ordisassociate:

  {    "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 beupdated
REGION: the region that the target pool is in
HEALTH_CHECK: the legacy HTTP health check to beassociated or disassociated with the target pool

For more information, see the API reference documentation fortargetPools.addHealthCheckandtargetPools.removeHealthCheck.

Add or remove a backup target pool

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

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

Note: If your target pool has thesessionAffinity field set, resizing the target pool couldcause requests that come from the same IP to go to a different instanceinitially. Eventually, all connections from the IP will go to the same virtualmachine, as the old connections close.

Console

Target pools can't be edited in the Google Cloud console.You can edit a target proxy by using the Google Cloud CLI or the API.

gcloud

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

  gcloud compute target-pools set-backupTARGET_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 aPOST 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 beupdated
REGION: the region that the target pool is in
BACKUP_POOL: the name of the backup pool to beassociated with the target pool
FAILOVER_RATIO: thefailover ratio

If you define an empty target or don't define a failover ratio, the backuppool behavior is disabled for this target pool.

What's next

For more information about target pools, see the API reference documentation fortargetPools.setBackup.
For more information about forwarding rules, seeForwarding rules overview.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.

Movatterモバイル変換

Using target pools Stay organized with collections Save and categorize content based on your preferences.

Target pool properties

Failover conditions

Create a target pool

Console

gcloud

API

Add or remove an instance from a target pool

Console

gcloud

API

List target pools

Console

gcloud

API

Describe a target pool

Console

gcloud

API

Get the health status of instances

Console

gcloud

API

Delete a target pool

Console

gcloud

API

Add or remove a health check from a target pool

Console

gcloud

API

Add or remove a backup target pool

Console

gcloud

API

What's next

Using target pools