Session affinity

Overview

Loading a website usually requires fetching multiple assets from a web server. Cloudflare Session Affinity minimizes redundant network requests by automatically directing requests from the same client to the same origin web server. Cloudflare sets a cookie on the initial response to the client. Using the cookie in subsequent client requests ensures those requests are sent to the same origin, unless the origin is unavailable.

When enabled, Cloudflare Session Affinity does the following:

  • When a client makes its first request, Cloudflare sets a CFLib cookie on the client. The cookie encodes the origin to which the request will be forwarded.
  • Subsequent requests by the same client are forwarded to that origin for the duration of the cookie and as long as the origin server remains healthy.
  • If the cookie expires or the origin server is unhealthy, Cloudflare sets a new cookie encoding the appropriate failover origin.

All sessions default to 23 hours unless a custom session TTL is specified (in seconds) between 30 minutes and 7 days. A Session Affinity Cookie is required to honor the TTL. The session cookie is secure when Always Use HTTPS is enabled. Additionally, HttpOnly is always enabled for the cookie to prevent cross-site scripting attacks.


Enabling Session Affinity from the Load Balancing dashboard

To enable Session Affinity, use the Session Affinity panel in the Load Balancing dashboard. Session Affinity with Client IP fallback is not officially supported for grey-clouded Load Balancers.

Configuring Session Affinity for a new load balancer

You can enable the Session Affinity option during the first stage of the Create a Load Balancer wizard, as shown below. Select the By Cloudflare cookie only radio button and set the toggle switch to the On position to enable session affinity. The Client IP fallback option behaves the same as the cookie option except client IP address is used as a fallback if no Session Affinity Cookie is provided.

Configuring Session Affinity for an existing load balancer

You can configure session affinity for an existing load balancer from the Load Balancing dashboard. Click the Edit button associated with the load balancer to open the Edit Load Balancer view and access the Session Affinity option.


Enabling Session Affinity via the Cloudflare API

Session affinity is a property of load balancers. Use the following endpoint to configure Session Affinity (see Create a load balancer with the API):

zones/:identifier/load_balancers

Set the session_affinity parameter to configure the feature. The default value is an empty string, which indicates that Session Affinity is disabled. To enable it, use the value “cookie” in your request.

Set the session_affinity_ttl parameter to configure the duration of session affinity cookies. Values are in seconds and must be in the range 1800–604800 (30 minutes to seven days). Unless session_affinity is explicitly set, the default value of 23 hours is used. This parameter is ignored when Session Affinity is disabled.

Configuring Session Affinity for a new load balancer

You can configure session affinity as part of your request to the Create Load Balancer command.

Request example (curl)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/load_balancers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '   "description":"Load Balancer for www.example.com",
   "name":"www.example.com",
   "ttl":30,
   "fallback_pool":"17b5962d775c646f3f9725cbc7a53df4",
   "default_pools":[
      "17b5962d775c646f3f9725cbc7a53df4",
      "9290f38c5d07c2e2f4df57b1f61d4196",
      "00920f38ce07c2e2f4df50b1f61d4194"
   ],
   "region_pools":{
      "WNAM":[
         "de90f38ced07c2e2f4df50b1f61d4194",
         "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "ENAM":[
         "00920f38ce07c2e2f4df50b1f61d4194"
      ]
   },
   "pop_pools":{
      "LAX":[
         "de90f38ced07c2e2f4df50b1f61d4194",
         "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR":[
         "abd90f38ced07c2e2f4df50b1f61d4194",
         "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC":[
         "00920f38ce07c2e2f4df50b1f61d4194"
      ]
   },
   "proxied":true,
   "steering_policy":"dynamic_latency",
   "session_affinity":"cookie",
   "session_affinity_ttl":5000
}''

Response

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Load Balancer for www.example.com",
    "name": "www.example.com",
    "enabled": true,
    "ttl": 30,
    "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
    "default_pools": [
      "17b5962d775c646f3f9725cbc7a53df4",
      "9290f38c5d07c2e2f4df57b1f61d4196",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "region_pools": {
      "WNAM": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "ENAM": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "steering_policy": "dynamic_latency",
    "session_affinity": "cookie",
    "session_affinity_ttl": 5000
  }
}

Configuring Session Affinity for an existing load balancer

Use the Update Load Balancer endpoint to configure session affinity for an existing load balancer:

PUT zones/:identifier/load_balancers/:identifier

Request example (curl)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/load_balancers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '   "description":"Load Balancer for www.example.com",
   "name":"www.example.com",
   "Enabled":true,
    "proxied":true,
   "steering_policy":"dynamic_latency",
   "session_affinity":"cookie",
   "session_affinity_ttl":5000
}''

Response

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Load Balancer for www.example.com",
    "name": "www.example.com",
    "enabled": true,
    "proxied": true,
    "steering_policy": "dynamic_latency",
    "session_affinity": "cookie",
    "session_affinity_ttl": 5000
  }
}