Patch Load Balancer - Cloudflare

Request

Path Params

identifier

string

required

identifier1

string

required

Body Params application/json

adaptive_routing

object (adaptive_routing)

optional

Controls features that modify the routing of requests to pools and origins in response to dynamic conditions, such as during the interval between active health monitoring requests. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin.

failover_across_pools

boolean

optional

Extends zero-downtime failover of requests to healthy origins from alternate pools, when no healthy alternate exists in the same pool, according to the failover order defined by traffic and origin steering. When set false (the default) zero-downtime failover will only occur between origins within the same pool. See session_affinity_attributes for control over when sessions are broken or reassigned.

Default:

false

Example:

true

country_pools

object (country_pools)

optional

A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools.

Example:

{"GB":["abd90f38ced07c2e2f4df50b1f61d4194"],"US":["de90f38ced07c2e2f4df50b1f61d4194","00920f38ce07c2e2f4df50b1f61d4194"]}

default_pools

array[string]

optional

A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region.

Example:

["17b5962d775c646f3f9725cbc7a53df4","9290f38c5d07c2e2f4df57b1f61d4196","00920f38ce07c2e2f4df50b1f61d4194"]

description

string

optional

Object description.

Example:

Load Balancer for www.example.com

enabled

boolean

optional

Whether to enable (the default) this load balancer.

Default:

true

Example:

true

fallback_pool

optional

The pool ID to use when all other pools are detected as unhealthy.

location_strategy

object (location_strategy)

optional

Controls location-based steering for non-proxied requests. See steering_policy to learn how steering is affected.

mode

enum<string>

optional

Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.

"pop": Use the Cloudflare PoP location.

"resolver_ip": Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.

Allowed values:

popresolver_ip

Default:

pop

Example:

resolver_ip

prefer_ecs

enum<string>

optional

Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.

"always": Always prefer ECS.

"never": Never prefer ECS.

"proximity": Prefer ECS only when steering_policy="proximity".

"geo": Prefer ECS only when steering_policy="geo".

Allowed values:

alwaysneverproximitygeo

Default:

proximity

Example:

always

name

string

optional

The DNS hostname to associate with your Load Balancer. If this hostname already exists as a DNS record in Cloudflare's DNS, the Load Balancer will take precedence and the DNS record will not be used.

Example:

www.example.com

pop_pools

object (pop_pools)

optional

(Enterprise only): A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools.

Example:

{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]}

proxied

boolean

optional

Whether the hostname should be gray clouded (false) or orange clouded (true).

Default:

false

Example:

true

random_steering

object (random_steering)

optional

Configures pool weights for random steering. When steering_policy is 'random', a random pool is selected with probability proportional to these pool weights.

default_weight

number

optional

The default weight for pools in the load balancer that are not specified in the pool_weights map.

>= 0<= 1

Default:

Example:

0.2

Multiple of:

0.1

pool_weights

object

optional

A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer.

Example:

{"9290f38c5d07c2e2f4df57b1f61d4196":0.5,"de90f38ced07c2e2f4df50b1f61d4194":0.3}

region_pools

object (region_pools)

optional

A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools.

Example:

{"ENAM":["00920f38ce07c2e2f4df50b1f61d4194"],"WNAM":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"]}

rules

array [object {7}]

optional

BETA Field Not General Access: A list of rules for this load balancer to execute.

condition

string

optional

The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions.

Example:

http.request.uri.path contains "/testing"

disabled

boolean

optional

Disable this specific rule. It will no longer be evaluated by this load balancer.

Default:

false

fixed_response

object

optional

A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates.

name

string

optional

Name of this rule. Only used for human readability.

<= 200 characters

Example:

route the path /testing to testing datacenter.

overrides

object

optional

A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional.

priority

integer

optional

The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority.

Default:

terminates

boolean

optional

If this rule's condition is true, this causes rule evaluation to stop after processing this rule.

Default:

false

session_affinity

enum<string>

optional

The session_affinity specifies the type of session affinity the load balancer should use unless specified as "none" or ""(default). The supported types are "cookie" and "ip_cookie". "cookie" - On the first request to a proxied load balancer, a cookie is generated, encoding information of which origin the request will be forwarded to. Subsequent requests, by the same client to the same load balancer, will be sent to the origin server the cookie encodes, for the duration of the cookie and as long as the origin server remains healthy. If the cookie has expired or the origin server is unhealthy then a new origin server is calculated and used. "ip_cookie" behaves the same as "cookie" except the initial origin selection is stable and based on the client’s ip address.

Allowed values:

nonecookieip_cookie""

Default:

Example:

session_affinity_attributes

object (session_affinity_attributes)

optional

Configures cookie attributes for session affinity cookie.

session_affinity_ttl

number

optional

Time, in seconds, until this load balancer's session affinity cookie expires after being created. This parameter is ignored unless a supported session affinity policy is set. The current default of 23 hours will be used unless session_affinity_ttl is explicitly set. The accepted range of values is between [1800, 604800]. Once the expiry time has been reached, subsequent requests may get sent to a different origin server.

Example:

5000

steering_policy

enum<string>

optional

Steering Policy for this load balancer.

"off": Use default_pools.

"geo": Use region_pools/country_pools/pop_pools. For non-proxied requests, the country for country_pools is determined by location_strategy.

"random": Select a pool randomly.

"dynamic_latency": Use round trip time to select the closest pool in default_pools (requires pool health checks).

"proximity": Use the pools' latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by location_strategy for non-proxied requests.

"": Will map to "geo" if you use region_pools/country_pools/pop_pools otherwise "off".

Allowed values:

offgeorandomdynamic_latencyproximity""

Default:

Example:

dynamic_latency

ttl

number

optional

Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers.

Example:

Example

{
  "adaptive_routing": {
    "failover_across_pools": true
  },
  "country_pools": {
    "GB": [
      "abd90f38ced07c2e2f4df50b1f61d4194"
    ],
    "US": [
      "de90f38ced07c2e2f4df50b1f61d4194",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ]
  },
  "default_pools": [
    "17b5962d775c646f3f9725cbc7a53df4",
    "9290f38c5d07c2e2f4df57b1f61d4196",
    "00920f38ce07c2e2f4df50b1f61d4194"
  ],
  "description": "Load Balancer for www.example.com",
  "enabled": true,
  "fallback_pool": null,
  "location_strategy": {
    "mode": "resolver_ip",
    "prefer_ecs": "always"
  },
  "name": "www.example.com",
  "pop_pools": {
    "LAX": [
      "de90f38ced07c2e2f4df50b1f61d4194",
      "9290f38c5d07c2e2f4df57b1f61d4196"
    ],
    "LHR": [
      "abd90f38ced07c2e2f4df50b1f61d4194",
      "f9138c5d07c2e2f4df57b1f61d4196"
    ],
    "SJC": [
      "00920f38ce07c2e2f4df50b1f61d4194"
    ]
  },
  "proxied": true,
  "random_steering": {
    "default_weight": 0.2,
    "pool_weights": {
      "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
      "de90f38ced07c2e2f4df50b1f61d4194": 0.3
    }
  },
  "region_pools": {
    "ENAM": [
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "WNAM": [
      "de90f38ced07c2e2f4df50b1f61d4194",
      "9290f38c5d07c2e2f4df57b1f61d4196"
    ]
  },
  "rules": [
    {
      "condition": "http.request.uri.path contains \"/testing\"",
      "disabled": false,
      "fixed_response": {
        "content_type": "application/json",
        "location": "www.example.com",
        "message_body": "Testing Hello",
        "status_code": 0
      },
      "name": "route the path /testing to testing datacenter.",
      "overrides": {
        "adaptive_routing": {
          "failover_across_pools": true
        },
        "country_pools": {
          "GB": [
            "abd90f38ced07c2e2f4df50b1f61d4194"
          ],
          "US": [
            "de90f38ced07c2e2f4df50b1f61d4194",
            "00920f38ce07c2e2f4df50b1f61d4194"
          ]
        },
        "default_pools": [
          "17b5962d775c646f3f9725cbc7a53df4",
          "9290f38c5d07c2e2f4df57b1f61d4196",
          "00920f38ce07c2e2f4df50b1f61d4194"
        ],
        "fallback_pool": null,
        "location_strategy": {
          "mode": "resolver_ip",
          "prefer_ecs": "always"
        },
        "pop_pools": {
          "LAX": [
            "de90f38ced07c2e2f4df50b1f61d4194",
            "9290f38c5d07c2e2f4df57b1f61d4196"
          ],
          "LHR": [
            "abd90f38ced07c2e2f4df50b1f61d4194",
            "f9138c5d07c2e2f4df57b1f61d4196"
          ],
          "SJC": [
            "00920f38ce07c2e2f4df50b1f61d4194"
          ]
        },
        "random_steering": {
          "default_weight": 0.2,
          "pool_weights": {
            "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
            "de90f38ced07c2e2f4df50b1f61d4194": 0.3
          }
        },
        "region_pools": {
          "ENAM": [
            "00920f38ce07c2e2f4df50b1f61d4194"
          ],
          "WNAM": [
            "de90f38ced07c2e2f4df50b1f61d4194",
            "9290f38c5d07c2e2f4df57b1f61d4196"
          ]
        },
        "session_affinity": "cookie",
        "session_affinity_attributes": {
          "drain_duration": 100,
          "samesite": "Auto",
          "secure": "Auto",
          "zero_downtime_failover": "sticky"
        },
        "session_affinity_ttl": 5000,
        "steering_policy": "dynamic_latency",
        "ttl": 30
      },
      "priority": 0,
      "terminates": false
    }
  ],
  "session_affinity": "cookie",
  "session_affinity_attributes": {
    "drain_duration": 100,
    "samesite": "Auto",
    "secure": "Auto",
    "zero_downtime_failover": "sticky"
  },
  "session_affinity_ttl": 5000,
  "steering_policy": "dynamic_latency",
  "ttl": 30
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request PATCH 'https://api.cloudflare.com/client/v4/zones//load_balancers/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "adaptive_routing": {
        "failover_across_pools": true
    },
    "country_pools": {
        "GB": [
            "abd90f38ced07c2e2f4df50b1f61d4194"
        ],
        "US": [
            "de90f38ced07c2e2f4df50b1f61d4194",
            "00920f38ce07c2e2f4df50b1f61d4194"
        ]
    },
    "default_pools": [
        "17b5962d775c646f3f9725cbc7a53df4",
        "9290f38c5d07c2e2f4df57b1f61d4196",
        "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "description": "Load Balancer for www.example.com",
    "enabled": true,
    "fallback_pool": null,
    "location_strategy": {
        "mode": "resolver_ip",
        "prefer_ecs": "always"
    },
    "name": "www.example.com",
    "pop_pools": {
        "LAX": [
            "de90f38ced07c2e2f4df50b1f61d4194",
            "9290f38c5d07c2e2f4df57b1f61d4196"
        ],
        "LHR": [
            "abd90f38ced07c2e2f4df50b1f61d4194",
            "f9138c5d07c2e2f4df57b1f61d4196"
        ],
        "SJC": [
            "00920f38ce07c2e2f4df50b1f61d4194"
        ]
    },
    "proxied": true,
    "random_steering": {
        "default_weight": 0.2,
        "pool_weights": {
            "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
            "de90f38ced07c2e2f4df50b1f61d4194": 0.3
        }
    },
    "region_pools": {
        "ENAM": [
            "00920f38ce07c2e2f4df50b1f61d4194"
        ],
        "WNAM": [
            "de90f38ced07c2e2f4df50b1f61d4194",
            "9290f38c5d07c2e2f4df57b1f61d4196"
        ]
    },
    "rules": [
        {
            "condition": "http.request.uri.path contains \"/testing\"",
            "disabled": false,
            "fixed_response": {
                "content_type": "application/json",
                "location": "www.example.com",
                "message_body": "Testing Hello",
                "status_code": 0
            },
            "name": "route the path /testing to testing datacenter.",
            "overrides": {
                "adaptive_routing": {
                    "failover_across_pools": true
                },
                "country_pools": {
                    "GB": [
                        "abd90f38ced07c2e2f4df50b1f61d4194"
                    ],
                    "US": [
                        "de90f38ced07c2e2f4df50b1f61d4194",
                        "00920f38ce07c2e2f4df50b1f61d4194"
                    ]
                },
                "default_pools": [
                    "17b5962d775c646f3f9725cbc7a53df4",
                    "9290f38c5d07c2e2f4df57b1f61d4196",
                    "00920f38ce07c2e2f4df50b1f61d4194"
                ],
                "fallback_pool": null,
                "location_strategy": {
                    "mode": "resolver_ip",
                    "prefer_ecs": "always"
                },
                "pop_pools": {
                    "LAX": [
                        "de90f38ced07c2e2f4df50b1f61d4194",
                        "9290f38c5d07c2e2f4df57b1f61d4196"
                    ],
                    "LHR": [
                        "abd90f38ced07c2e2f4df50b1f61d4194",
                        "f9138c5d07c2e2f4df57b1f61d4196"
                    ],
                    "SJC": [
                        "00920f38ce07c2e2f4df50b1f61d4194"
                    ]
                },
                "random_steering": {
                    "default_weight": 0.2,
                    "pool_weights": {
                        "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
                        "de90f38ced07c2e2f4df50b1f61d4194": 0.3
                    }
                },
                "region_pools": {
                    "ENAM": [
                        "00920f38ce07c2e2f4df50b1f61d4194"
                    ],
                    "WNAM": [
                        "de90f38ced07c2e2f4df50b1f61d4194",
                        "9290f38c5d07c2e2f4df57b1f61d4196"
                    ]
                },
                "session_affinity": "cookie",
                "session_affinity_attributes": {
                    "drain_duration": 100,
                    "samesite": "Auto",
                    "secure": "Auto",
                    "zero_downtime_failover": "sticky"
                },
                "session_affinity_ttl": 5000,
                "steering_policy": "dynamic_latency",
                "ttl": 30
            },
            "priority": 0,
            "terminates": false
        }
    ],
    "session_affinity": "cookie",
    "session_affinity_attributes": {
        "drain_duration": 100,
        "samesite": "Auto",
        "secure": "Auto",
        "zero_downtime_failover": "sticky"
    },
    "session_affinity_ttl": 5000,
    "steering_policy": "dynamic_latency",
    "ttl": 30
}'

Responses

🟢200Patch Load Balancer 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 (load-balancer)

optional

Example

{
  "errors": [],
  "messages": [],
  "result": {
    "adaptive_routing": {
      "failover_across_pools": true
    },
    "country_pools": {
      "GB": [
        "abd90f38ced07c2e2f4df50b1f61d4194"
      ],
      "US": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "default_pools": [
      "17b5962d775c646f3f9725cbc7a53df4",
      "9290f38c5d07c2e2f4df57b1f61d4196",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "description": "Load Balancer for www.example.com",
    "enabled": true,
    "fallback_pool": null,
    "id": "699d98642c564d2e855e9661899b7252",
    "location_strategy": {
      "mode": "resolver_ip",
      "prefer_ecs": "always"
    },
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "www.example.com",
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "random_steering": {
      "default_weight": 0.2,
      "pool_weights": {
        "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
        "de90f38ced07c2e2f4df50b1f61d4194": 0.3
      }
    },
    "region_pools": {
      "ENAM": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ],
      "WNAM": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ]
    },
    "rules": [
      {
        "condition": "http.request.uri.path contains \"/testing\"",
        "disabled": false,
        "fixed_response": {
          "content_type": "application/json",
          "location": "www.example.com",
          "message_body": "Testing Hello",
          "status_code": 0
        },
        "name": "route the path /testing to testing datacenter.",
        "overrides": {
          "adaptive_routing": {
            "failover_across_pools": true
          },
          "country_pools": {
            "GB": [
              "abd90f38ced07c2e2f4df50b1f61d4194"
            ],
            "US": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "default_pools": [
            "17b5962d775c646f3f9725cbc7a53df4",
            "9290f38c5d07c2e2f4df57b1f61d4196",
            "00920f38ce07c2e2f4df50b1f61d4194"
          ],
          "fallback_pool": null,
          "location_strategy": {
            "mode": "resolver_ip",
            "prefer_ecs": "always"
          },
          "pop_pools": {
            "LAX": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "LHR": [
              "abd90f38ced07c2e2f4df50b1f61d4194",
              "f9138c5d07c2e2f4df57b1f61d4196"
            ],
            "SJC": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "random_steering": {
            "default_weight": 0.2,
            "pool_weights": {
              "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
              "de90f38ced07c2e2f4df50b1f61d4194": 0.3
            }
          },
          "region_pools": {
            "ENAM": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ],
            "WNAM": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ]
          },
          "session_affinity": "cookie",
          "session_affinity_attributes": {
            "drain_duration": 100,
            "samesite": "Auto",
            "secure": "Auto",
            "zero_downtime_failover": "sticky"
          },
          "session_affinity_ttl": 5000,
          "steering_policy": "dynamic_latency",
          "ttl": 30
        },
        "priority": 0,
        "terminates": false
      }
    ],
    "session_affinity": "cookie",
    "session_affinity_attributes": {
      "drain_duration": 100,
      "samesite": "Auto",
      "secure": "Auto",
      "zero_downtime_failover": "sticky"
    },
    "session_affinity_ttl": 5000,
    "steering_policy": "dynamic_latency",
    "ttl": 30
  },
  "success": true
}

🟢200Patch Load Balancer response failure