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

Load balancers


A Cloudflare load balancer is identified by the DNS hostname whose traffic you want to balance (, for example). The load balancer defines which origin server pools to use, the order in which they should be used, and how to geographically distribute traffic among pools.

Common configurations

Active - Passive Failover

An active-passive failover sends traffic to the servers in your active pool until a failure threshold (configurable) is reached. At the point of failure, your load balancer then redirects traffic to the passive pool.

This setup ensures uninterrupted service and helps with planned outtages, but it might lead to slower traffic overall.

To set up a load balancer with active-passive failover:

  1. Create a load balancer with two origin pools (primary and secondary).
  2. In the list of origin pools, set the following order:
    1. primary
    2. secondary
  3. For Traffic Steering, select Off.

With this setup, your load balancer will direct all traffic to primary until primary has fewer available origins than specified in its Health Threshold. Only then will your load balancer direct traffic to secondary.

In the event that all pools are marked down, Cloudflare uses the fallback pool, which is the option of last resort for successfully sending traffic to an origin. Since the fallback pool is a last resort, its health is not taken into account, and Cloudflare reports its status as No Health. You can select the fallback pool via the API or in the Cloudflare dashboard. For more on working with fallback pools, see Traffic steering.

Active - Active Failover

An active-active failover (or round-robin approach) distributes traffic to servers in the same pool until the pool reaches its failure threshold (configurable). At the point of failure, your load balancer would then re-direct traffic to the fallback pool.

This setup speeds up overall requests, but is more vulnerable to planned or unplanned outtages.

To set up a load balancer with active-active failover, either:

  • Create a load balancer with a single origin pool (primary) with multiple origins (origin-1 and origin-2) and set the same Weight for each origin.
  • Create a load balancer with two origin pools (primary and secondary) and — for Traffic Steering — select Random.

Important notes

Load balancing and existing DNS records

Adding a Load Balancer does not create a DNS record or SSL certificate. To generate an SSL certificate, create a proxied DNS record for the Load Balancer. The Load Balancer record takes precedence over a DNS record for the same host name.

When you create a load balancer on Cloudflare, you can either:

  • Use a unique hostname with no existing DNS record, or
  • Use a hostname that has an existing DNS record, either as an A, AAAA, or CNAME record.

If a chosen hostname has an existing DNS record, the load balancer will supersede the DNS record if the DNS record is an A, AAAA, or canonical name (CNAME) record. It will not supersede other record types.

If the load balancer is disabled, preexisting DNS records will be served.

If there is no preexisting DNS record with the same name, disabling the load balancer will prevent clients from resolving the host, and requests will fail.

If a Load Balancer is manually disabled, traffic is not served to the associated origins or the fallback. If all pools in a Load Balancer are manually disabled or unhealthy, traffic goes to the fallback pool. No health checks run on the fallback pool and it will return the same HTTP status as your origin.

If the pool serving as your fallback pool is also disabled:

  • If Cloudflare proxies your hostname, you will see a 530 HTTP/1016 Origin DNS failure.
  • If Cloudflare does not proxy your hostname, you will see the SOA record.

HTTP keep-alive (persistent HTTP connection)

Cloudflare maintains keep-alive connections to improve performance and reduce cost of recurring TCP connects in the request transaction as Cloudflare proxies customer traffic from its edge network to the site's origin.

Ensure HTTP Keep-Alive connections are enabled on your origin. Cloudflare reuses open TCP connections for up to 15 minutes (900 seconds) after the last HTTP request. Origin web servers close TCP connections if too many are open. HTTP Keep-Alive helps avoid premature reset of connections for requests proxied by Cloudflare.

Session cookies

When using HTTP cookies to track and bind user sessions to a specific server, configure Session Affinity to parse HTTP requests by cookie header. Doing so directs each request to the correct application server even when HTTP requests share the same TCP connection due to keep-alive.

For example, F5 BIG-IP load balancers set a session cookie at the beginning of a TCP connection (if none exists) and then ignore all cookies from subsequent HTTP requests on the same TCP connection. This tends to break session affinity because Cloudflare sends multiple HTTP sessions on the same TCP connection. Configuring the load balancer to parse HTTP requests by cookie headers avoids this issue.

Railgun (wide area network optimization)

Railgun is a web proxy system built for Cloudflare, that allows dynamic content for a website to be cached while also allowing changes to the site to take effect almost instantly. Railgun is currently available to customers with a Business or Enterprise plan, or via one of Cloudflare’s Optimised Partners.

Railgun compresses web objects, even rapidly changing pages like news sites or personalized content. Using Railgun in conjunction with Cloudflare Load Balancing speeds up connections between Cloudflare datacenters and DNS origin servers so that uncacheable requests have minimal latency.

Set up a Railgun listener in front of the load balancer so that the load balancer can handle HTTP connections normally. Load balancing long-lived TLS connections between the sender and listener is very difficult.

Use the same load balancer settings as if Railgun were not in place — for example, HTTP keep-alive connections should be enabled and set to a 90-second timeout, since Railgun is working as an HTTP reverse proxy.

If Railgun is placed behind the load balancer, observe the following guidelines to avoid interruptions with site traffic:

  1. Use the railgun-nat.conf configuration file to set the internal addresses of the hosts Railgun will be optimizing (localhost:8080, for example). This is important to avoid looping the request outbound to the internet and back to the load balancer only to be forwarded to the origin.
  2. Ensure no firewall rules are in place that will interfere with traffic between the listener and the origin server.
  3. Ensure port 2408 is open and passed through the load balancer so that it does not interfere with the TLS connection between the listener and sender.

For additional guidance and diagrams, see Best practices for Railgun with a Load Balancer.


Cloudflare Load Balancer objects have the following properties:

Name / typeDescription / exampleConstraints
string (date-time)
The creation timestamp for the load balancer.

A list of Pool IDs ordered by failover priority. Cloudflare steers traffic to the first pool in the list, failing over to the next healthy pool and so on down the list.

Pools defined here are used by default, or when region_pools is not configured for a given region.

[  "17b5962d775c646f3f9725cbc7a53df4",  "9290f38c5d07c2e2f4df57b1f61d4196",  "00920f38ce07c2e2f4df50b1f61d4194"]
A user-supplied description of the load balancer
"Load Balancer for"
Enables the load balancer when set to
Default value: true
Valid values: (true,false)
The Pool ID for the “pool of last resort,” the pool the load balancer should direct traffic to if all other pools are unhealthy. In most configurations, this is the secondary/passive pool.
Max. length: 32
The load balancer ID
Max. length: 32
string (date-time)
Timestamp of the last modification to the load balancer configuration
The public DNS hostname of your Cloudflare load balancer.

If you have an existing DNS record with the same name as your load balancer, the load balancer will have precedence. The pre-existing DNS record is not used unless you delete the Cloudflare load balancer.

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

{  "LAX": [    "de90f38ced07c2e2f4df50b1f61d4194",    "9290f38c5d07c2e2f4df57b1f61d4196"  ],  "LHR": [    "abd90f38ced07c2e2f4df50b1f61d4194",    "f9138c5d07c2e2f4df57b1f61d4196"  ],  "SJC": [    "00920f38ce07c2e2f4df50b1f61d4194"  ]}
When set to true, HTTP Proxy mode is enabled; when false, DNS-only mode.
Default value: false
Valid values: (true,false)
A mapping of region/country 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.

{  "WNAM": [    "de90f38ced07c2e2f4df50b1f61d4194",    "9290f38c5d07c2e2f4df57b1f61d4196"  ],  "ENAM": [    "00920f38ce07c2e2f4df50b1f61d4194"  ]}
Specifies the type of session affinity the load balancer should use. The default value is "", which disables session affinity (as does "none").
The supported session affinity types are "cookie" and "ip_cookie".

When set to "cookie", the first request to a proxied load balancer generates a cookie encoding the origin to which the request will be forwarded.

Subsequent requests by the same client to the same load balancer will be sent to the origin server encoded by the cookie.

If the cookie has expired or the origin server is unhealthy, a new origin server is identified and a new cookie generated. The "ip_cookie" option behaves the same as "cookie", except the initial origin selection is stable and based on the client’s IP address.
Default value: ""
Valid values: none, cookie, ip_cookie, ""
Sets the time to live for this load balancer’s session affinity cookies.

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 and 604800. Once the expiry time has been reached, subsequent requests may get sent to a different origin server.
The traffic steering policy for this load balancer
The constraint values have the following effect on traffic steering:
  • "off": enables standard failover
  • "geo": enables Geo Steering
  • "random": selects an available pool at random on failover
  • "dynamic_latency": enables Dynamic Steering
  • "": enables Geo Steering if region_pools and/or pop_pools is configured; otherwise uses standard failover
Default value: ""
Valid values: off, geo, random, dynamic_latency, ""
The time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to load balancers where the proxy mode is DNS-only.


Managing load balancers via the Cloudflare API


The endpoint for managing load balancers is



The Cloudflare API supports the following commands for load balancers. (Examples are given for the user-level endpoint but apply to the account-level endpoint as well.) For detailed instruction, see Cloudflare API v4: Load Balancers.

Create Load BalancerGET/zones/:identifier/load_balancers
Delete Load BalancerDELETE/zones/:identifier/load_balancers/:identifier
List Load BalancersGET/zones/:identifier/load_balancers
Load Balancer DetailsPOST/zones/:identifier/load_balancers/:identifier
Update Load BalancerPUT/zones/:identifier/load_balancers/:identifier