Patch Pool - Cloudflare

Apply changes to an existing pool, overwriting the supplied properties.

Request

Path Params

identifier

string

required

Body Params application/json

check_regions

array[string] | null

optional

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

Allowed values:

WNAMENAMWEUEEUNSAMSSAMOCMENAFSAFSASSEASNEASALL_REGIONS

Example:

["WEU","ENAM"]

description

string

optional

A human-readable description of the pool.

Example:

Primary data center - Provider XYZ

enabled

boolean

optional

Whether to enable (the default) or disable this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any).

Default:

true

Example:

false

latitude

number

optional

The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.

load_shedding

object (load_shedding)

optional

Configures load shedding policies and percentages for the pool.

default_percent

number

optional

The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity.

>= 0<= 100

Default:

default_policy

enum<string>

optional

The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs.

Allowed values:

randomhash

Default:

random

session_percent

number

optional

The percent of existing sessions to shed from the pool, according to the session policy.

>= 0<= 100

Default:

session_policy

enum<string>

optional

Only the hash policy is supported for existing sessions (to avoid exponential decay).

Allowed value:

hash

Default:

hash

longitude

number

optional

The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.

minimum_origins

integer

optional

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 will failover to the next available pool.

Default:

monitor

optional

The ID of the Monitor to use for checking the health of origins within this pool.

name

string

optional

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

Example:

primary-dc-1

notification_email

string

optional

The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list.

Example:

someone@example.com,sometwo@example.com

notification_filter

object (notification_filter) | null

optional

Filter pool and origin health notifications by resource type or health status. Use null to reset.

Example:

{"origin":{"disable":true},"pool":{"healthy":false}}

origin

object (filter_options) | null

optional

Filter options for a particular resource type (pool or origin). Use null to reset.

pool

object (filter_options) | null

optional

Filter options for a particular resource type (pool or origin). Use null to reset.

origin_steering

object (origin_steering)

optional

Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity.

policy

enum<string>

optional

The type of origin steering policy to use, either "random" or "hash" (based on CF-Connecting-IP).

Allowed values:

randomhash

Default:

random

origins

array[object (schemas-origin) {5}]

optional

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.

address

string

optional

The IP address (IPv4 or IPv6) of the origin, or the publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare.

Example:

0.0.0.0

enabled

boolean

optional

Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool.

Default:

true

Example:

true

header

object (schemas-header)

optional

The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'.

name

string

optional

A human-identifiable name for the origin.

Example:

app-server-1

weight

number

optional

The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool.

>= 0<= 1

Default:

Example:

0.6

Multiple of:

0.01

Example

{
    "check_regions": [
        "WEU",
        "ENAM"
    ],
    "description": "Primary data center - Provider XYZ",
    "enabled": false,
    "latitude": 0,
    "load_shedding": {
        "default_percent": 0,
        "default_policy": "random",
        "session_percent": 0,
        "session_policy": "hash"
    },
    "longitude": 0,
    "minimum_origins": 1,
    "monitor": null,
    "name": "primary-dc-1",
    "notification_email": "someone@example.com,sometwo@example.com",
    "notification_filter": {
        "origin": {
            "disable": true
        },
        "pool": {
            "healthy": false
        }
    },
    "origin_steering": {
        "policy": "random"
    },
    "origins": [
        {
            "address": "0.0.0.0",
            "enabled": true,
            "header": {
                "Host": "www.example.com"
            },
            "name": "app-server-1",
            "weight": 0.6
        }
    ]
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Patch Pool response

application/json

Body

allOf {2}

optional

object (api-response-single)

optional

errors

array [object {2}]

messages

required

Example:

[]

messages

array [object {2}]

messages

required

Example:

[]

result

required

success

enum<boolean>

required

Whether the API call was successful

Allowed value:

true

Example:

true

object

optional

result

object (pool)

optional

Example

{
    "errors": [],
    "messages": [],
    "result": {
        "check_regions": [
            "WEU",
            "ENAM"
        ],
        "created_on": "2014-01-01T05:20:00.12345Z",
        "description": "Primary data center - Provider XYZ",
        "disabled_at": "2019-08-24T14:15:22Z",
        "enabled": false,
        "id": "17b5962d775c646f3f9725cbc7a53df4",
        "latitude": 0,
        "load_shedding": {
            "default_percent": 0,
            "default_policy": "random",
            "session_percent": 0,
            "session_policy": "hash"
        },
        "longitude": 0,
        "minimum_origins": 1,
        "modified_on": "2014-01-01T05:20:00.12345Z",
        "monitor": null,
        "name": "primary-dc-1",
        "notification_email": "someone@example.com,sometwo@example.com",
        "notification_filter": {
            "origin": {
                "disable": true
            },
            "pool": {
                "healthy": false
            }
        },
        "origin_steering": {
            "policy": "random"
        },
        "origins": [
            {
                "address": "0.0.0.0",
                "disabled_at": "2019-08-24T14:15:22Z",
                "enabled": true,
                "header": {
                    "Host": "www.example.com"
                },
                "name": "app-server-1",
                "weight": 0.6
            }
        ]
    },
    "success": true
}

🟢200Patch Pool response failure