Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



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.

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-name>"
healthChecks[ ]

[Optional] An optional list of health checks for this 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/us-central1-a/instances/<instance-name>",
  "https://www.googleapis.com/compute/v1/projects/<project-id>/zones/us-central1-b/instances/<instance-name>"
]
sessionAffinity

[Optional] Describes 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. By default, a 5-tuple method is used and the default value for this field is NONE. The 5-tuple hash method selects a backend based on:

  • Layer 4 Protocol (e.g. TCP, UDP)
  • Source / Destination IP
  • Source / Destination Port

5-tuple hashing provides a good distribution of traffic across many virtual machines but if you wanted to use a single backend with a specific client ('stick' a client to a single virtual machine instance), you can also specify the following options:

CLIENT_IP_PROTO
3-tuple hashing, which includes the source / destination IP and network protocol
CLIENT_IP
2-tuple hashing, which includes the source / destination IP

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, at the cost of possibly unequal distribution of traffic.

Caution: If a large portion of your clients are behind a proxy server, you should not use the sessionAffinity feature because it would force all clients behind the proxy to be pinned to a specific backend.

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 targetpools 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%). 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

Adding a target pool

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

$ gcloud compute target-pools create TARGET_POOL
    --region REGION
    [--backup-pool BACKUP_POOL]
    [--description DESCRIPTION]
    [--failover-ratio FAILOVER_RATIO]
    [--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": [
     "http://www.googleapis.com/v1/compute/project/<project-id>/zone/<zone>/instances/<instance-name>",
     "http://www.googleapis.com/v1/compute/project/<project-id>/zone/<zone>/instances/<instance-name>",
  ]
}

Adding and removing 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 ...]
    --region REGION
    --zone ZONE

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

$ gcloud compute target-pools remove-instances TARGET_POOL
    --instances INSTANCE [INSTANCE ...]
    --region REGION
    --zone ZONE

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-d>/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": "http://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/instances/<instance-name>"},
    {"instance": "http://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/instances/<instance-name>"}
  ]
}

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

Listing 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 without specifying a name: 

$ gcloud compute target-pools get

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

https://www.googleapis.com/compute/v1/projects/<project-id>/regions/<region>/targetPools

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

Getting 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 gloud compute , use the target-pools get-health command: 

$ gcloud compute target-pools get-health TARGET_POOL
    --region REGION
    [--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": "http://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/instances/<instance-name>"
}

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

Adding and removing 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
    --region REGION

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
  --region REGION

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-d>/regions/<region>/targetPools/<target-pool>/addHealthCheck

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

{
  "healthCheck": "http://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 .

Adding and removing 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
    --region REGION

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.