Skip to content
Load Balancing
Visit Load Balancing on GitHub
Set theme to dark (⇧+D)

Pools

Overview

A Cloudflare Load Balancing pool represents a group of origin servers, each identified by their IP address or hostname. You can configure multiple pools, as well as failover priority (Pool A-> Pool B-> Pool C). If you're familiar with DNS terminology, think of a pool as a “record set,” except we only return addresses that are considered healthy. You can attach health checks to individual pools to tailor monitoring for collections of origin servers.


Important notes

When working with pools, note the following:

When adding origin servers to a pool, you can identify the origin by hostname or IP address.

The order of pools in the load balancer determines the standard failover priority. When the number of healthy origins in a pool drops below the configured threshold, Load Balancing routes traffic to the next available pool.

By default, pools are ordered by date created. You can reorder them from the Load Balancing dashboard and via Cloudflare API (use the Update Pools command to set a new origins array).

Dynamic Steering uses Round Trip Time (RTT) profiles to determine pool priority. If there is no RTT data for a pool in a region or colocation center, Load Balancing will use pool order to determine failover priority.

Geo Steering directs traffic to pools based on the client’s region or point of presence. If there is no Geo Steering configuration for a region or pool, the load balancer will use pool order to determine failover priority.


Properties

Cloudflare Pool objects have the following properties:

Name / typeDescription / exampleConstraints
check_regions

arraynull
A list of regions from which to run health checks. Null means every Cloudflare data center.

[

"WEU",

"ENAM"

]
created_on

string (date-time)
Creation time

"2014-01-01T05:20:00.12345Z"
Read only
description

string
A human-readable description of the pool

"This pool is for example.com"
enabled

boolean
Set to true to enable the pool; false, to disable.

Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers associated with the pool to failover to the next pool (if any).

true
Default value: true

Valid values: true, false
id

string
API item identifier tag for the pool

"17b5962d775c646f3f9725cbc7a53df4"
Max. length: 32 bytes

Read only
minimum_origins

integer
The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and the load balancer will failover to the next available pool.

2
modified_on

string (date-time)
Last modification time

"2014-01-01T05:20:00.12345Z"
Read only
monitor

string
The ID of the monitor to use for health checking origins within this pool

"f1aba936b94213e5b8dca0c0dbf1f9cc"
Max. length: 32 bytes

Read only
name

string
A short name (tag) for the pool. Only alphanumeric characters, hyphens and underscores are allowed.

"primary-dc-1"
notification_email

string
The email address to which health status notifications are sent. This can be an individual mailbox or a mailing list.

"someone@example.com"
origins

array
The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy.

[

{

"name": "app-server-1",

"address": "0.0.0.0",

"enabled": true,

"weight": 0.56

}

]

Per origin Host header override

To balance traffic across multiple hosts, add Host headers to individual origins within the same pool.

For example, you might have a pool with origins hosted in multiple AppEngine projects or Amazon S3 buckets. You also might want to set up specific failover origins within a pool.

Since these examples require specific hostnames per origin, your load balancer could not properly route traffic without a Host header override.

If you need an origin Host header override, add it when creating or editing a pool. For security reasons, this header also needs to be a subdomain of the overall zone. See Configure Cloudflare and Heroku for more details.

For details about how origin and monitor Host headers interact, see Host header prioritization.


Managing pools via the Cloudflare API

Endpoints

Pool endpoints are available in the Cloudflare API at both the user and account level, respectively:

  • user/load_balancers/pools
  • accounts/:account_identifier/load_balancers/pools

Commands

The Cloudflare API supports the following commands. For more detail, see Cloudflare API: Load Balancer Pools.

CommandMethodEndpoint
Create PoolPOSTuser/load_balancers/pools
Delete PoolDELETEuser/load_balancers/pools/:identifier
List PoolsGETuser/load_balancers/pools
Pool DetailsGETuser/load_balancers/pools/:identifier
Pool Health DetailsGETuser/load_balancers/pools/:identifier/health
Update PoolPUTuser/load_balancers/pools/:identifier