Apply changes to an existing load balancer, overwriting the supplied properties.
/zones/{identifier1}/load_balancers/{identifier}
patch
Load Balancers
load-balancers-patch-load-balancer
nullnull[
{
"in": "path",
"name": "identifier",
"required": true,
"schema": {
"example": "699d98642c564d2e855e9661899b7252",
"type": "string"
}
},
{
"in": "path",
"name": "identifier1",
"required": true,
"schema": {
"example": "699d98642c564d2e855e9661899b7252",
"type": "string"
}
}
]{
"content": {
"application/json": {
"schema": {
"properties": {
"adaptive_routing": {
"description": "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.",
"properties": {
"failover_across_pools": {
"default": false,
"description": "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.",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"country_pools": {
"description": "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"
]
},
"type": "object"
},
"default_pools": {
"description": "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"
],
"items": {
"description": "A pool ID.",
"type": "string"
},
"type": "array"
},
"description": {
"description": "Object description.",
"example": "Load Balancer for www.example.com",
"type": "string"
},
"enabled": {
"default": true,
"description": "Whether to enable (the default) this load balancer.",
"example": true,
"type": "boolean"
},
"fallback_pool": {
"description": "The pool ID to use when all other pools are detected as unhealthy."
},
"location_strategy": {
"description": "Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected.",
"properties": {
"mode": {
"default": "pop",
"description": "Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.\n- `\"pop\"`: Use the Cloudflare PoP location.\n- `\"resolver_ip\"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.",
"enum": [
"pop",
"resolver_ip"
],
"example": "resolver_ip",
"type": "string"
},
"prefer_ecs": {
"default": "proximity",
"description": "Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.\n- `\"always\"`: Always prefer ECS.\n- `\"never\"`: Never prefer ECS.\n- `\"proximity\"`: Prefer ECS only when `steering_policy=\"proximity\"`.\n- `\"geo\"`: Prefer ECS only when `steering_policy=\"geo\"`.",
"enum": [
"always",
"never",
"proximity",
"geo"
],
"example": "always",
"type": "string"
}
},
"type": "object"
},
"name": {
"description": "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",
"type": "string"
},
"pop_pools": {
"description": "(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"
]
},
"type": "object"
},
"proxied": {
"default": false,
"description": "Whether the hostname should be gray clouded (false) or orange clouded (true).",
"example": true,
"type": "boolean"
},
"random_steering": {
"description": "Configures pool weights.\n- `steering_policy=\"random\"`: A random pool is selected with probability proportional to pool weights.\n- `steering_policy=\"least_outstanding_requests\"`: Use pool weights to scale each pool's outstanding requests.\n- `steering_policy=\"least_connections\"`: Use pool weights to scale each pool's open connections.",
"properties": {
"default_weight": {
"default": 1,
"description": "The default weight for pools in the load balancer that are not specified in the pool_weights map.",
"example": 0.2,
"maximum": 1,
"minimum": 0,
"multipleOf": 0.1,
"type": "number"
},
"pool_weights": {
"description": "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
},
"type": "object"
}
},
"type": "object"
},
"region_pools": {
"description": "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"
]
},
"type": "object"
},
"rules": {
"description": "BETA Field Not General Access: A list of rules for this load balancer to execute.",
"items": {
"additionalProperties": false,
"description": "A rule object containing conditions and overrides for this load balancer to evaluate.",
"properties": {
"condition": {
"description": "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\"",
"type": "string"
},
"disabled": {
"default": false,
"description": "Disable this specific rule. It will no longer be evaluated by this load balancer.",
"type": "boolean"
},
"fixed_response": {
"description": "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.",
"properties": {
"content_type": {
"description": "The http 'Content-Type' header to include in the response.",
"example": "application/json",
"maxLength": 32,
"type": "string"
},
"location": {
"description": "The http 'Location' header to include in the response.",
"example": "www.example.com",
"maxLength": 2048,
"type": "string"
},
"message_body": {
"description": "Text to include as the http body.",
"example": "Testing Hello",
"maxLength": 1024,
"type": "string"
},
"status_code": {
"description": "The http status code to respond with.",
"type": "integer"
}
},
"type": "object"
},
"name": {
"description": "Name of this rule. Only used for human readability.",
"example": "route the path /testing to testing datacenter.",
"maxLength": 200,
"type": "string"
},
"overrides": {
"description": "A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional.",
"properties": {
"adaptive_routing": {
"description": "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.",
"properties": {
"failover_across_pools": {
"default": false,
"description": "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.",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"country_pools": {
"description": "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"
]
},
"type": "object"
},
"default_pools": {
"description": "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"
],
"items": {
"description": "A pool ID.",
"type": "string"
},
"type": "array"
},
"fallback_pool": {
"description": "The pool ID to use when all other pools are detected as unhealthy."
},
"location_strategy": {
"description": "Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected.",
"properties": {
"mode": {
"default": "pop",
"description": "Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.\n- `\"pop\"`: Use the Cloudflare PoP location.\n- `\"resolver_ip\"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.",
"enum": [
"pop",
"resolver_ip"
],
"example": "resolver_ip",
"type": "string"
},
"prefer_ecs": {
"default": "proximity",
"description": "Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.\n- `\"always\"`: Always prefer ECS.\n- `\"never\"`: Never prefer ECS.\n- `\"proximity\"`: Prefer ECS only when `steering_policy=\"proximity\"`.\n- `\"geo\"`: Prefer ECS only when `steering_policy=\"geo\"`.",
"enum": [
"always",
"never",
"proximity",
"geo"
],
"example": "always",
"type": "string"
}
},
"type": "object"
},
"pop_pools": {
"description": "(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"
]
},
"type": "object"
},
"random_steering": {
"description": "Configures pool weights.\n- `steering_policy=\"random\"`: A random pool is selected with probability proportional to pool weights.\n- `steering_policy=\"least_outstanding_requests\"`: Use pool weights to scale each pool's outstanding requests.\n- `steering_policy=\"least_connections\"`: Use pool weights to scale each pool's open connections.",
"properties": {
"default_weight": {
"default": 1,
"description": "The default weight for pools in the load balancer that are not specified in the pool_weights map.",
"example": 0.2,
"maximum": 1,
"minimum": 0,
"multipleOf": 0.1,
"type": "number"
},
"pool_weights": {
"description": "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
},
"type": "object"
}
},
"type": "object"
},
"region_pools": {
"description": "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"
]
},
"type": "object"
},
"session_affinity": {
"default": "\"\"",
"description": "Specifies the type of session affinity the load balancer should use unless specified as `\"none\"` or \"\" (default). The supported types are:\n- `\"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.\n- `\"ip_cookie\"`: Behaves the same as `\"cookie\"` except the initial origin selection is stable and based on the client's ip address.\n- `\"header\"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration.",
"enum": [
"none",
"cookie",
"ip_cookie",
"header",
"\"\""
],
"example": "cookie",
"type": "string"
},
"session_affinity_attributes": {
"description": "Configures attributes for session affinity.",
"properties": {
"drain_duration": {
"description": "Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.",
"example": 100,
"type": "number"
},
"headers": {
"default": "none",
"description": "Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `\"cookie:<cookie-name-1>,<cookie-name-2>\"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `\"cookie\"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans.",
"items": {
"description": "An HTTP header name.",
"maxLength": 100,
"minLength": 1,
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"type": "array",
"uniqueItems": true
},
"require_all_headers": {
"default": false,
"description": "When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are:\n- `\"true\"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.\n- `\"false\"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.",
"type": "boolean"
},
"samesite": {
"default": "Auto",
"description": "Configures the SameSite attribute on session affinity cookie. Value \"Auto\" will be translated to \"Lax\" or \"None\" depending if Always Use HTTPS is enabled. Note: when using value \"None\", the secure attribute can not be set to \"Never\".",
"enum": [
"Auto",
"Lax",
"None",
"Strict"
],
"example": "Auto",
"type": "string"
},
"secure": {
"default": "Auto",
"description": "Configures the Secure attribute on session affinity cookie. Value \"Always\" indicates the Secure attribute will be set in the Set-Cookie header, \"Never\" indicates the Secure attribute will not be set, and \"Auto\" will set the Secure attribute depending if Always Use HTTPS is enabled.",
"enum": [
"Auto",
"Always",
"Never"
],
"example": "Auto",
"type": "string"
},
"zero_downtime_failover": {
"default": "none",
"description": "Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are:\n- `\"none\"`: No failover takes place for sessions pinned to the origin (default).\n- `\"temporary\"`: Traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping.\n- `\"sticky\"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header.",
"enum": [
"none",
"temporary",
"sticky"
],
"example": "sticky",
"type": "string"
}
},
"type": "object"
},
"session_affinity_ttl": {
"description": "Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are:\n- `\"cookie\"` / `\"ip_cookie\"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. \n- `\"header\"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified.",
"example": 1800,
"type": "number"
},
"steering_policy": {
"default": "\"\"",
"description": "Steering Policy for this load balancer.\n- `\"off\"`: Use `default_pools`.\n- `\"geo\"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`.\n- `\"random\"`: Select a pool randomly.\n- `\"dynamic_latency\"`: Use round trip time to select the closest pool in default_pools (requires pool health checks).\n- `\"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.\n- `\"least_outstanding_requests\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.\n- `\"least_connections\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.\n- `\"\"`: Will map to `\"geo\"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `\"off\"`.",
"enum": [
"off",
"geo",
"random",
"dynamic_latency",
"proximity",
"least_outstanding_requests",
"least_connections",
"\"\""
],
"example": "dynamic_latency",
"type": "string"
},
"ttl": {
"description": "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": 30,
"type": "number"
}
},
"type": "object"
},
"priority": {
"default": 0,
"description": "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.",
"minimum": 0,
"type": "integer"
},
"terminates": {
"default": false,
"description": "If this rule's condition is true, this causes rule evaluation to stop after processing this rule.",
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
},
"session_affinity": {
"default": "\"\"",
"description": "Specifies the type of session affinity the load balancer should use unless specified as `\"none\"` or \"\" (default). The supported types are:\n- `\"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.\n- `\"ip_cookie\"`: Behaves the same as `\"cookie\"` except the initial origin selection is stable and based on the client's ip address.\n- `\"header\"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration.",
"enum": [
"none",
"cookie",
"ip_cookie",
"header",
"\"\""
],
"example": "cookie",
"type": "string"
},
"session_affinity_attributes": {
"description": "Configures attributes for session affinity.",
"properties": {
"drain_duration": {
"description": "Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.",
"example": 100,
"type": "number"
},
"headers": {
"default": "none",
"description": "Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `\"cookie:<cookie-name-1>,<cookie-name-2>\"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `\"cookie\"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans.",
"items": {
"description": "An HTTP header name.",
"maxLength": 100,
"minLength": 1,
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"type": "array",
"uniqueItems": true
},
"require_all_headers": {
"default": false,
"description": "When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are:\n- `\"true\"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.\n- `\"false\"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.",
"type": "boolean"
},
"samesite": {
"default": "Auto",
"description": "Configures the SameSite attribute on session affinity cookie. Value \"Auto\" will be translated to \"Lax\" or \"None\" depending if Always Use HTTPS is enabled. Note: when using value \"None\", the secure attribute can not be set to \"Never\".",
"enum": [
"Auto",
"Lax",
"None",
"Strict"
],
"example": "Auto",
"type": "string"
},
"secure": {
"default": "Auto",
"description": "Configures the Secure attribute on session affinity cookie. Value \"Always\" indicates the Secure attribute will be set in the Set-Cookie header, \"Never\" indicates the Secure attribute will not be set, and \"Auto\" will set the Secure attribute depending if Always Use HTTPS is enabled.",
"enum": [
"Auto",
"Always",
"Never"
],
"example": "Auto",
"type": "string"
},
"zero_downtime_failover": {
"default": "none",
"description": "Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are:\n- `\"none\"`: No failover takes place for sessions pinned to the origin (default).\n- `\"temporary\"`: Traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping.\n- `\"sticky\"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header.",
"enum": [
"none",
"temporary",
"sticky"
],
"example": "sticky",
"type": "string"
}
},
"type": "object"
},
"session_affinity_ttl": {
"description": "Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are:\n- `\"cookie\"` / `\"ip_cookie\"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. \n- `\"header\"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified.",
"example": 1800,
"type": "number"
},
"steering_policy": {
"default": "\"\"",
"description": "Steering Policy for this load balancer.\n- `\"off\"`: Use `default_pools`.\n- `\"geo\"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`.\n- `\"random\"`: Select a pool randomly.\n- `\"dynamic_latency\"`: Use round trip time to select the closest pool in default_pools (requires pool health checks).\n- `\"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.\n- `\"least_outstanding_requests\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.\n- `\"least_connections\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.\n- `\"\"`: Will map to `\"geo\"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `\"off\"`.",
"enum": [
"off",
"geo",
"random",
"dynamic_latency",
"proximity",
"least_outstanding_requests",
"least_connections",
"\"\""
],
"example": "dynamic_latency",
"type": "string"
},
"ttl": {
"description": "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": 30,
"type": "number"
}
}
}
}
},
"required": true
}{
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"properties": {
"errors": {
"example": [],
"items": {
"properties": {
"code": {
"minimum": 1000,
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"uniqueItems": true
},
"type": "array"
},
"messages": {
"example": [],
"items": {
"properties": {
"code": {
"minimum": 1000,
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"uniqueItems": true
},
"type": "array"
},
"result": {
"anyOf": [
{
"type": "object"
},
{
"items": {},
"type": "array"
},
{
"type": "string"
}
]
},
"success": {
"description": "Whether the API call was successful",
"enum": [
true
],
"example": true,
"type": "boolean"
}
},
"required": [
"success",
"errors",
"messages",
"result"
],
"type": "object"
},
{
"properties": {
"result": {
"anyOf": [
{
"nullable": true,
"type": "object"
},
{
"nullable": true,
"type": "string"
}
]
}
}
}
],
"type": "object"
},
{
"properties": {
"result": {
"properties": {
"adaptive_routing": {
"description": "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.",
"properties": {
"failover_across_pools": {
"default": false,
"description": "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.",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"country_pools": {
"description": "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"
]
},
"type": "object"
},
"created_on": {
"example": "2014-01-01T05:20:00.12345Z",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"default_pools": {
"description": "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"
],
"items": {
"description": "A pool ID.",
"type": "string"
},
"type": "array"
},
"description": {
"description": "Object description.",
"example": "Load Balancer for www.example.com",
"type": "string"
},
"enabled": {
"default": true,
"description": "Whether to enable (the default) this load balancer.",
"example": true,
"type": "boolean"
},
"fallback_pool": {
"description": "The pool ID to use when all other pools are detected as unhealthy."
},
"id": {
"example": "699d98642c564d2e855e9661899b7252",
"type": "string"
},
"location_strategy": {
"description": "Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected.",
"properties": {
"mode": {
"default": "pop",
"description": "Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.\n- `\"pop\"`: Use the Cloudflare PoP location.\n- `\"resolver_ip\"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.",
"enum": [
"pop",
"resolver_ip"
],
"example": "resolver_ip",
"type": "string"
},
"prefer_ecs": {
"default": "proximity",
"description": "Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.\n- `\"always\"`: Always prefer ECS.\n- `\"never\"`: Never prefer ECS.\n- `\"proximity\"`: Prefer ECS only when `steering_policy=\"proximity\"`.\n- `\"geo\"`: Prefer ECS only when `steering_policy=\"geo\"`.",
"enum": [
"always",
"never",
"proximity",
"geo"
],
"example": "always",
"type": "string"
}
},
"type": "object"
},
"modified_on": {
"example": "2014-01-01T05:20:00.12345Z",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"name": {
"description": "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",
"type": "string"
},
"pop_pools": {
"description": "(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"
]
},
"type": "object"
},
"proxied": {
"default": false,
"description": "Whether the hostname should be gray clouded (false) or orange clouded (true).",
"example": true,
"type": "boolean"
},
"random_steering": {
"description": "Configures pool weights.\n- `steering_policy=\"random\"`: A random pool is selected with probability proportional to pool weights.\n- `steering_policy=\"least_outstanding_requests\"`: Use pool weights to scale each pool's outstanding requests.\n- `steering_policy=\"least_connections\"`: Use pool weights to scale each pool's open connections.",
"properties": {
"default_weight": {
"default": 1,
"description": "The default weight for pools in the load balancer that are not specified in the pool_weights map.",
"example": 0.2,
"maximum": 1,
"minimum": 0,
"multipleOf": 0.1,
"type": "number"
},
"pool_weights": {
"description": "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
},
"type": "object"
}
},
"type": "object"
},
"region_pools": {
"description": "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"
]
},
"type": "object"
},
"rules": {
"description": "BETA Field Not General Access: A list of rules for this load balancer to execute.",
"items": {
"additionalProperties": false,
"description": "A rule object containing conditions and overrides for this load balancer to evaluate.",
"properties": {
"condition": {
"description": "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\"",
"type": "string"
},
"disabled": {
"default": false,
"description": "Disable this specific rule. It will no longer be evaluated by this load balancer.",
"type": "boolean"
},
"fixed_response": {
"description": "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.",
"properties": {
"content_type": {
"description": "The http 'Content-Type' header to include in the response.",
"example": "application/json",
"maxLength": 32,
"type": "string"
},
"location": {
"description": "The http 'Location' header to include in the response.",
"example": "www.example.com",
"maxLength": 2048,
"type": "string"
},
"message_body": {
"description": "Text to include as the http body.",
"example": "Testing Hello",
"maxLength": 1024,
"type": "string"
},
"status_code": {
"description": "The http status code to respond with.",
"type": "integer"
}
},
"type": "object"
},
"name": {
"description": "Name of this rule. Only used for human readability.",
"example": "route the path /testing to testing datacenter.",
"maxLength": 200,
"type": "string"
},
"overrides": {
"description": "A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional.",
"properties": {
"adaptive_routing": {
"description": "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.",
"properties": {
"failover_across_pools": {
"default": false,
"description": "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.",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"country_pools": {
"description": "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"
]
},
"type": "object"
},
"default_pools": {
"description": "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"
],
"items": {
"description": "A pool ID.",
"type": "string"
},
"type": "array"
},
"fallback_pool": {
"description": "The pool ID to use when all other pools are detected as unhealthy."
},
"location_strategy": {
"description": "Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected.",
"properties": {
"mode": {
"default": "pop",
"description": "Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.\n- `\"pop\"`: Use the Cloudflare PoP location.\n- `\"resolver_ip\"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.",
"enum": [
"pop",
"resolver_ip"
],
"example": "resolver_ip",
"type": "string"
},
"prefer_ecs": {
"default": "proximity",
"description": "Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.\n- `\"always\"`: Always prefer ECS.\n- `\"never\"`: Never prefer ECS.\n- `\"proximity\"`: Prefer ECS only when `steering_policy=\"proximity\"`.\n- `\"geo\"`: Prefer ECS only when `steering_policy=\"geo\"`.",
"enum": [
"always",
"never",
"proximity",
"geo"
],
"example": "always",
"type": "string"
}
},
"type": "object"
},
"pop_pools": {
"description": "(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"
]
},
"type": "object"
},
"random_steering": {
"description": "Configures pool weights.\n- `steering_policy=\"random\"`: A random pool is selected with probability proportional to pool weights.\n- `steering_policy=\"least_outstanding_requests\"`: Use pool weights to scale each pool's outstanding requests.\n- `steering_policy=\"least_connections\"`: Use pool weights to scale each pool's open connections.",
"properties": {
"default_weight": {
"default": 1,
"description": "The default weight for pools in the load balancer that are not specified in the pool_weights map.",
"example": 0.2,
"maximum": 1,
"minimum": 0,
"multipleOf": 0.1,
"type": "number"
},
"pool_weights": {
"description": "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
},
"type": "object"
}
},
"type": "object"
},
"region_pools": {
"description": "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"
]
},
"type": "object"
},
"session_affinity": {
"default": "\"\"",
"description": "Specifies the type of session affinity the load balancer should use unless specified as `\"none\"` or \"\" (default). The supported types are:\n- `\"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.\n- `\"ip_cookie\"`: Behaves the same as `\"cookie\"` except the initial origin selection is stable and based on the client's ip address.\n- `\"header\"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration.",
"enum": [
"none",
"cookie",
"ip_cookie",
"header",
"\"\""
],
"example": "cookie",
"type": "string"
},
"session_affinity_attributes": {
"description": "Configures attributes for session affinity.",
"properties": {
"drain_duration": {
"description": "Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.",
"example": 100,
"type": "number"
},
"headers": {
"default": "none",
"description": "Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `\"cookie:<cookie-name-1>,<cookie-name-2>\"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `\"cookie\"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans.",
"items": {
"description": "An HTTP header name.",
"maxLength": 100,
"minLength": 1,
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"type": "array",
"uniqueItems": true
},
"require_all_headers": {
"default": false,
"description": "When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are:\n- `\"true\"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.\n- `\"false\"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.",
"type": "boolean"
},
"samesite": {
"default": "Auto",
"description": "Configures the SameSite attribute on session affinity cookie. Value \"Auto\" will be translated to \"Lax\" or \"None\" depending if Always Use HTTPS is enabled. Note: when using value \"None\", the secure attribute can not be set to \"Never\".",
"enum": [
"Auto",
"Lax",
"None",
"Strict"
],
"example": "Auto",
"type": "string"
},
"secure": {
"default": "Auto",
"description": "Configures the Secure attribute on session affinity cookie. Value \"Always\" indicates the Secure attribute will be set in the Set-Cookie header, \"Never\" indicates the Secure attribute will not be set, and \"Auto\" will set the Secure attribute depending if Always Use HTTPS is enabled.",
"enum": [
"Auto",
"Always",
"Never"
],
"example": "Auto",
"type": "string"
},
"zero_downtime_failover": {
"default": "none",
"description": "Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are:\n- `\"none\"`: No failover takes place for sessions pinned to the origin (default).\n- `\"temporary\"`: Traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping.\n- `\"sticky\"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header.",
"enum": [
"none",
"temporary",
"sticky"
],
"example": "sticky",
"type": "string"
}
},
"type": "object"
},
"session_affinity_ttl": {
"description": "Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are:\n- `\"cookie\"` / `\"ip_cookie\"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. \n- `\"header\"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified.",
"example": 1800,
"type": "number"
},
"steering_policy": {
"default": "\"\"",
"description": "Steering Policy for this load balancer.\n- `\"off\"`: Use `default_pools`.\n- `\"geo\"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`.\n- `\"random\"`: Select a pool randomly.\n- `\"dynamic_latency\"`: Use round trip time to select the closest pool in default_pools (requires pool health checks).\n- `\"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.\n- `\"least_outstanding_requests\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.\n- `\"least_connections\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.\n- `\"\"`: Will map to `\"geo\"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `\"off\"`.",
"enum": [
"off",
"geo",
"random",
"dynamic_latency",
"proximity",
"least_outstanding_requests",
"least_connections",
"\"\""
],
"example": "dynamic_latency",
"type": "string"
},
"ttl": {
"description": "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": 30,
"type": "number"
}
},
"type": "object"
},
"priority": {
"default": 0,
"description": "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.",
"minimum": 0,
"type": "integer"
},
"terminates": {
"default": false,
"description": "If this rule's condition is true, this causes rule evaluation to stop after processing this rule.",
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
},
"session_affinity": {
"default": "\"\"",
"description": "Specifies the type of session affinity the load balancer should use unless specified as `\"none\"` or \"\" (default). The supported types are:\n- `\"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.\n- `\"ip_cookie\"`: Behaves the same as `\"cookie\"` except the initial origin selection is stable and based on the client's ip address.\n- `\"header\"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration.",
"enum": [
"none",
"cookie",
"ip_cookie",
"header",
"\"\""
],
"example": "cookie",
"type": "string"
},
"session_affinity_attributes": {
"description": "Configures attributes for session affinity.",
"properties": {
"drain_duration": {
"description": "Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.",
"example": 100,
"type": "number"
},
"headers": {
"default": "none",
"description": "Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `\"cookie:<cookie-name-1>,<cookie-name-2>\"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `\"cookie\"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans.",
"items": {
"description": "An HTTP header name.",
"maxLength": 100,
"minLength": 1,
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"type": "array",
"uniqueItems": true
},
"require_all_headers": {
"default": false,
"description": "When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are:\n- `\"true\"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.\n- `\"false\"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.",
"type": "boolean"
},
"samesite": {
"default": "Auto",
"description": "Configures the SameSite attribute on session affinity cookie. Value \"Auto\" will be translated to \"Lax\" or \"None\" depending if Always Use HTTPS is enabled. Note: when using value \"None\", the secure attribute can not be set to \"Never\".",
"enum": [
"Auto",
"Lax",
"None",
"Strict"
],
"example": "Auto",
"type": "string"
},
"secure": {
"default": "Auto",
"description": "Configures the Secure attribute on session affinity cookie. Value \"Always\" indicates the Secure attribute will be set in the Set-Cookie header, \"Never\" indicates the Secure attribute will not be set, and \"Auto\" will set the Secure attribute depending if Always Use HTTPS is enabled.",
"enum": [
"Auto",
"Always",
"Never"
],
"example": "Auto",
"type": "string"
},
"zero_downtime_failover": {
"default": "none",
"description": "Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are:\n- `\"none\"`: No failover takes place for sessions pinned to the origin (default).\n- `\"temporary\"`: Traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping.\n- `\"sticky\"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header.",
"enum": [
"none",
"temporary",
"sticky"
],
"example": "sticky",
"type": "string"
}
},
"type": "object"
},
"session_affinity_ttl": {
"description": "Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are:\n- `\"cookie\"` / `\"ip_cookie\"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. \n- `\"header\"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified.",
"example": 1800,
"type": "number"
},
"steering_policy": {
"default": "\"\"",
"description": "Steering Policy for this load balancer.\n- `\"off\"`: Use `default_pools`.\n- `\"geo\"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`.\n- `\"random\"`: Select a pool randomly.\n- `\"dynamic_latency\"`: Use round trip time to select the closest pool in default_pools (requires pool health checks).\n- `\"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.\n- `\"least_outstanding_requests\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.\n- `\"least_connections\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.\n- `\"\"`: Will map to `\"geo\"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `\"off\"`.",
"enum": [
"off",
"geo",
"random",
"dynamic_latency",
"proximity",
"least_outstanding_requests",
"least_connections",
"\"\""
],
"example": "dynamic_latency",
"type": "string"
},
"ttl": {
"description": "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": 30,
"type": "number"
}
},
"type": "object"
}
}
}
]
}
}
},
"description": "Patch Load Balancer response"
},
"4XX": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"properties": {
"errors": {
"example": [],
"items": {
"properties": {
"code": {
"minimum": 1000,
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"uniqueItems": true
},
"type": "array"
},
"messages": {
"example": [],
"items": {
"properties": {
"code": {
"minimum": 1000,
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"uniqueItems": true
},
"type": "array"
},
"result": {
"anyOf": [
{
"type": "object"
},
{
"items": {},
"type": "array"
},
{
"type": "string"
}
]
},
"success": {
"description": "Whether the API call was successful",
"enum": [
true
],
"example": true,
"type": "boolean"
}
},
"required": [
"success",
"errors",
"messages",
"result"
],
"type": "object"
},
{
"properties": {
"result": {
"anyOf": [
{
"nullable": true,
"type": "object"
},
{
"nullable": true,
"type": "string"
}
]
}
}
}
],
"type": "object"
},
{
"properties": {
"result": {
"properties": {
"adaptive_routing": {
"description": "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.",
"properties": {
"failover_across_pools": {
"default": false,
"description": "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.",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"country_pools": {
"description": "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"
]
},
"type": "object"
},
"created_on": {
"example": "2014-01-01T05:20:00.12345Z",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"default_pools": {
"description": "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"
],
"items": {
"description": "A pool ID.",
"type": "string"
},
"type": "array"
},
"description": {
"description": "Object description.",
"example": "Load Balancer for www.example.com",
"type": "string"
},
"enabled": {
"default": true,
"description": "Whether to enable (the default) this load balancer.",
"example": true,
"type": "boolean"
},
"fallback_pool": {
"description": "The pool ID to use when all other pools are detected as unhealthy."
},
"id": {
"example": "699d98642c564d2e855e9661899b7252",
"type": "string"
},
"location_strategy": {
"description": "Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected.",
"properties": {
"mode": {
"default": "pop",
"description": "Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.\n- `\"pop\"`: Use the Cloudflare PoP location.\n- `\"resolver_ip\"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.",
"enum": [
"pop",
"resolver_ip"
],
"example": "resolver_ip",
"type": "string"
},
"prefer_ecs": {
"default": "proximity",
"description": "Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.\n- `\"always\"`: Always prefer ECS.\n- `\"never\"`: Never prefer ECS.\n- `\"proximity\"`: Prefer ECS only when `steering_policy=\"proximity\"`.\n- `\"geo\"`: Prefer ECS only when `steering_policy=\"geo\"`.",
"enum": [
"always",
"never",
"proximity",
"geo"
],
"example": "always",
"type": "string"
}
},
"type": "object"
},
"modified_on": {
"example": "2014-01-01T05:20:00.12345Z",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"name": {
"description": "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",
"type": "string"
},
"pop_pools": {
"description": "(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"
]
},
"type": "object"
},
"proxied": {
"default": false,
"description": "Whether the hostname should be gray clouded (false) or orange clouded (true).",
"example": true,
"type": "boolean"
},
"random_steering": {
"description": "Configures pool weights.\n- `steering_policy=\"random\"`: A random pool is selected with probability proportional to pool weights.\n- `steering_policy=\"least_outstanding_requests\"`: Use pool weights to scale each pool's outstanding requests.\n- `steering_policy=\"least_connections\"`: Use pool weights to scale each pool's open connections.",
"properties": {
"default_weight": {
"default": 1,
"description": "The default weight for pools in the load balancer that are not specified in the pool_weights map.",
"example": 0.2,
"maximum": 1,
"minimum": 0,
"multipleOf": 0.1,
"type": "number"
},
"pool_weights": {
"description": "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
},
"type": "object"
}
},
"type": "object"
},
"region_pools": {
"description": "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"
]
},
"type": "object"
},
"rules": {
"description": "BETA Field Not General Access: A list of rules for this load balancer to execute.",
"items": {
"additionalProperties": false,
"description": "A rule object containing conditions and overrides for this load balancer to evaluate.",
"properties": {
"condition": {
"description": "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\"",
"type": "string"
},
"disabled": {
"default": false,
"description": "Disable this specific rule. It will no longer be evaluated by this load balancer.",
"type": "boolean"
},
"fixed_response": {
"description": "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.",
"properties": {
"content_type": {
"description": "The http 'Content-Type' header to include in the response.",
"example": "application/json",
"maxLength": 32,
"type": "string"
},
"location": {
"description": "The http 'Location' header to include in the response.",
"example": "www.example.com",
"maxLength": 2048,
"type": "string"
},
"message_body": {
"description": "Text to include as the http body.",
"example": "Testing Hello",
"maxLength": 1024,
"type": "string"
},
"status_code": {
"description": "The http status code to respond with.",
"type": "integer"
}
},
"type": "object"
},
"name": {
"description": "Name of this rule. Only used for human readability.",
"example": "route the path /testing to testing datacenter.",
"maxLength": 200,
"type": "string"
},
"overrides": {
"description": "A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional.",
"properties": {
"adaptive_routing": {
"description": "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.",
"properties": {
"failover_across_pools": {
"default": false,
"description": "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.",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"country_pools": {
"description": "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"
]
},
"type": "object"
},
"default_pools": {
"description": "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"
],
"items": {
"description": "A pool ID.",
"type": "string"
},
"type": "array"
},
"fallback_pool": {
"description": "The pool ID to use when all other pools are detected as unhealthy."
},
"location_strategy": {
"description": "Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected.",
"properties": {
"mode": {
"default": "pop",
"description": "Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.\n- `\"pop\"`: Use the Cloudflare PoP location.\n- `\"resolver_ip\"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.",
"enum": [
"pop",
"resolver_ip"
],
"example": "resolver_ip",
"type": "string"
},
"prefer_ecs": {
"default": "proximity",
"description": "Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.\n- `\"always\"`: Always prefer ECS.\n- `\"never\"`: Never prefer ECS.\n- `\"proximity\"`: Prefer ECS only when `steering_policy=\"proximity\"`.\n- `\"geo\"`: Prefer ECS only when `steering_policy=\"geo\"`.",
"enum": [
"always",
"never",
"proximity",
"geo"
],
"example": "always",
"type": "string"
}
},
"type": "object"
},
"pop_pools": {
"description": "(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"
]
},
"type": "object"
},
"random_steering": {
"description": "Configures pool weights.\n- `steering_policy=\"random\"`: A random pool is selected with probability proportional to pool weights.\n- `steering_policy=\"least_outstanding_requests\"`: Use pool weights to scale each pool's outstanding requests.\n- `steering_policy=\"least_connections\"`: Use pool weights to scale each pool's open connections.",
"properties": {
"default_weight": {
"default": 1,
"description": "The default weight for pools in the load balancer that are not specified in the pool_weights map.",
"example": 0.2,
"maximum": 1,
"minimum": 0,
"multipleOf": 0.1,
"type": "number"
},
"pool_weights": {
"description": "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
},
"type": "object"
}
},
"type": "object"
},
"region_pools": {
"description": "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"
]
},
"type": "object"
},
"session_affinity": {
"default": "\"\"",
"description": "Specifies the type of session affinity the load balancer should use unless specified as `\"none\"` or \"\" (default). The supported types are:\n- `\"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.\n- `\"ip_cookie\"`: Behaves the same as `\"cookie\"` except the initial origin selection is stable and based on the client's ip address.\n- `\"header\"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration.",
"enum": [
"none",
"cookie",
"ip_cookie",
"header",
"\"\""
],
"example": "cookie",
"type": "string"
},
"session_affinity_attributes": {
"description": "Configures attributes for session affinity.",
"properties": {
"drain_duration": {
"description": "Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.",
"example": 100,
"type": "number"
},
"headers": {
"default": "none",
"description": "Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `\"cookie:<cookie-name-1>,<cookie-name-2>\"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `\"cookie\"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans.",
"items": {
"description": "An HTTP header name.",
"maxLength": 100,
"minLength": 1,
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"type": "array",
"uniqueItems": true
},
"require_all_headers": {
"default": false,
"description": "When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are:\n- `\"true\"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.\n- `\"false\"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.",
"type": "boolean"
},
"samesite": {
"default": "Auto",
"description": "Configures the SameSite attribute on session affinity cookie. Value \"Auto\" will be translated to \"Lax\" or \"None\" depending if Always Use HTTPS is enabled. Note: when using value \"None\", the secure attribute can not be set to \"Never\".",
"enum": [
"Auto",
"Lax",
"None",
"Strict"
],
"example": "Auto",
"type": "string"
},
"secure": {
"default": "Auto",
"description": "Configures the Secure attribute on session affinity cookie. Value \"Always\" indicates the Secure attribute will be set in the Set-Cookie header, \"Never\" indicates the Secure attribute will not be set, and \"Auto\" will set the Secure attribute depending if Always Use HTTPS is enabled.",
"enum": [
"Auto",
"Always",
"Never"
],
"example": "Auto",
"type": "string"
},
"zero_downtime_failover": {
"default": "none",
"description": "Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are:\n- `\"none\"`: No failover takes place for sessions pinned to the origin (default).\n- `\"temporary\"`: Traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping.\n- `\"sticky\"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header.",
"enum": [
"none",
"temporary",
"sticky"
],
"example": "sticky",
"type": "string"
}
},
"type": "object"
},
"session_affinity_ttl": {
"description": "Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are:\n- `\"cookie\"` / `\"ip_cookie\"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. \n- `\"header\"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified.",
"example": 1800,
"type": "number"
},
"steering_policy": {
"default": "\"\"",
"description": "Steering Policy for this load balancer.\n- `\"off\"`: Use `default_pools`.\n- `\"geo\"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`.\n- `\"random\"`: Select a pool randomly.\n- `\"dynamic_latency\"`: Use round trip time to select the closest pool in default_pools (requires pool health checks).\n- `\"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.\n- `\"least_outstanding_requests\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.\n- `\"least_connections\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.\n- `\"\"`: Will map to `\"geo\"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `\"off\"`.",
"enum": [
"off",
"geo",
"random",
"dynamic_latency",
"proximity",
"least_outstanding_requests",
"least_connections",
"\"\""
],
"example": "dynamic_latency",
"type": "string"
},
"ttl": {
"description": "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": 30,
"type": "number"
}
},
"type": "object"
},
"priority": {
"default": 0,
"description": "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.",
"minimum": 0,
"type": "integer"
},
"terminates": {
"default": false,
"description": "If this rule's condition is true, this causes rule evaluation to stop after processing this rule.",
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
},
"session_affinity": {
"default": "\"\"",
"description": "Specifies the type of session affinity the load balancer should use unless specified as `\"none\"` or \"\" (default). The supported types are:\n- `\"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.\n- `\"ip_cookie\"`: Behaves the same as `\"cookie\"` except the initial origin selection is stable and based on the client's ip address.\n- `\"header\"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration.",
"enum": [
"none",
"cookie",
"ip_cookie",
"header",
"\"\""
],
"example": "cookie",
"type": "string"
},
"session_affinity_attributes": {
"description": "Configures attributes for session affinity.",
"properties": {
"drain_duration": {
"description": "Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.",
"example": 100,
"type": "number"
},
"headers": {
"default": "none",
"description": "Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `\"cookie:<cookie-name-1>,<cookie-name-2>\"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `\"cookie\"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans.",
"items": {
"description": "An HTTP header name.",
"maxLength": 100,
"minLength": 1,
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"type": "array",
"uniqueItems": true
},
"require_all_headers": {
"default": false,
"description": "When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are:\n- `\"true\"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.\n- `\"false\"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.",
"type": "boolean"
},
"samesite": {
"default": "Auto",
"description": "Configures the SameSite attribute on session affinity cookie. Value \"Auto\" will be translated to \"Lax\" or \"None\" depending if Always Use HTTPS is enabled. Note: when using value \"None\", the secure attribute can not be set to \"Never\".",
"enum": [
"Auto",
"Lax",
"None",
"Strict"
],
"example": "Auto",
"type": "string"
},
"secure": {
"default": "Auto",
"description": "Configures the Secure attribute on session affinity cookie. Value \"Always\" indicates the Secure attribute will be set in the Set-Cookie header, \"Never\" indicates the Secure attribute will not be set, and \"Auto\" will set the Secure attribute depending if Always Use HTTPS is enabled.",
"enum": [
"Auto",
"Always",
"Never"
],
"example": "Auto",
"type": "string"
},
"zero_downtime_failover": {
"default": "none",
"description": "Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are:\n- `\"none\"`: No failover takes place for sessions pinned to the origin (default).\n- `\"temporary\"`: Traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping.\n- `\"sticky\"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header.",
"enum": [
"none",
"temporary",
"sticky"
],
"example": "sticky",
"type": "string"
}
},
"type": "object"
},
"session_affinity_ttl": {
"description": "Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are:\n- `\"cookie\"` / `\"ip_cookie\"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. \n- `\"header\"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified.",
"example": 1800,
"type": "number"
},
"steering_policy": {
"default": "\"\"",
"description": "Steering Policy for this load balancer.\n- `\"off\"`: Use `default_pools`.\n- `\"geo\"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`.\n- `\"random\"`: Select a pool randomly.\n- `\"dynamic_latency\"`: Use round trip time to select the closest pool in default_pools (requires pool health checks).\n- `\"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.\n- `\"least_outstanding_requests\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.\n- `\"least_connections\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.\n- `\"\"`: Will map to `\"geo\"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `\"off\"`.",
"enum": [
"off",
"geo",
"random",
"dynamic_latency",
"proximity",
"least_outstanding_requests",
"least_connections",
"\"\""
],
"example": "dynamic_latency",
"type": "string"
},
"ttl": {
"description": "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": 30,
"type": "number"
}
},
"type": "object"
}
}
}
]
},
{
"properties": {
"errors": {
"allOf": [
{
"example": [],
"items": {
"properties": {
"code": {
"minimum": 1000,
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"uniqueItems": true
},
"type": "array"
}
],
"example": [
{
"code": 7003,
"message": "No route for the URI"
}
],
"minLength": 1
},
"messages": {
"allOf": [
{
"example": [],
"items": {
"properties": {
"code": {
"minimum": 1000,
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"uniqueItems": true
},
"type": "array"
}
],
"example": []
},
"result": {
"enum": [
null
],
"nullable": true,
"type": "object"
},
"success": {
"description": "Whether the API call was successful",
"enum": [
false
],
"example": false,
"type": "boolean"
}
},
"required": [
"success",
"errors",
"messages",
"result"
],
"type": "object"
}
]
}
}
},
"description": "Patch Load Balancer response failure"
}
}[
{
"api_email": [],
"api_key": []
}
]