Cookie affinity configuration
In a distributed Function Compute environment, different requests can be routed to different instances, which prevents maintaining session state. The cookie affinity feature resolves this by automatically injecting a cookie on the server side. This ensures that requests with the same cookie value are routed to the same function instance, maintaining session consistency.
Core configuration
On the function configuration page, go to advanced settings > Isolation and Affinity. Enable the session affinity switch, select cookie affinity, configure the number of concurrent sessions per instance and Session Lifetime, and then click Deploy to enable the feature.
The system automatically injects a cookie into the response header of the first request. The client must include this cookie in all subsequent requests so the system routes them to the same instance.
Applicability
General limitations: Before you begin, review the general limitations and principles of session affinity.
Server-side cookie injection only: When a client makes its first request, Function Compute automatically injects a cookie using the
Set-Cookieheader in the response. The client must parse and save this cookie, and include it in all subsequent requests.Request limitations:
A single instance can handle multiple concurrent sessions (20 by default, up to a maximum of 200). When the number of sessions bound to an instance reaches this limit, the system automatically creates a new instance.
Multiple sessions share the instance's concurrency quota of 200.
Session API management support: You can use the Session API to manage the session lifecycle, including creating, updating, querying, and terminating sessions.
Configure cookie affinity
Procedure overview
Configuring cookie affinity involves three steps: enabling session affinity, selecting the cookie type, and configuring parameters before deploying. You can configure these settings when you create a function or update them for an existing function.
Enable session affinity
Log on to the Function Compute console.
Go to the function list and either select your target function or create a new function.
When you create a function, you can find the Isolation & Affinity settings in the Advanced Settings section and configure them directly.
On the function details page, click the Configuration tab.
In the Advanced Settings section, find the Isolation & Affinity settings.
Click Isolation & Affinity to expand the configuration panel.
Enable the Session affinity switch.
Select the cookie affinity type
In the Session affinity configuration area, select the cookie affinity radio button.
The system automatically displays the configuration options for cookie affinity.
Configure session parameters
Goal: Control session binding and resource usage by setting the number of sessions, their lifecycle, and idle timeout.
Procedure:
number of concurrent sessions per instance: Set the maximum number of sessions that a single instance can process simultaneously.
Default: 20
Range: 1 to 200
Recommendation: For testing, use a smaller value such as 10. For production environments, adjust the value based on your business requirements.
Session Lifetime: Set the maximum duration of a session, from creation to termination.
Default: 21,600 seconds (6 hours)
Description: After this period, the system automatically terminates the session, and affinity is no longer guaranteed.
Session Idle Timeout: Set the duration of inactivity after which a session is automatically terminated.
Default: 1,800 seconds (30 minutes)
Description: If an instance receives no requests for longer than this duration, the session becomes idle and is automatically terminated.
Click the Deploy button to save the configuration.
Important:
When you enable session affinity, the system automatically sets the concurrency per instance to 200. This is a system default and cannot be changed manually.
If you configure session affinity when creating a function, the settings are applied upon creation. If you configure it for an existing function, you must deploy the configuration separately.
The system automatically generates the cookie name in the format
x-fc-cookie-session-idand a globally unique ID for the cookie value.The cookie's
Max-Agedefaults to 21,600 seconds (6 hours), which matches the session lifetime.
Verify cookie affinity
Goal: Verify that requests with the same cookie are routed to the same instance and that the automatic instance scale-out mechanism works as expected.
Requests with the same cookie value are routed to the same instance.
When the number of sessions on an instance reaches its limit, the system automatically creates a new instance.
All requests return a successful response (status code 200).
You can monitor instance scaling changes on the function details page in the console.
Procedure:
Prepare your test environment
Ensure your function is deployed with cookie affinity configured. For easier testing, we recommend setting number of concurrent sessions per instance to 2.
Get the URL of the function's HTTP trigger.
For testing purposes, you can change the HTTP trigger's authentication from signature authentication to anonymous access:
On the function details page, go to the Triggers tab.
Click the Edit button for the trigger.
Change the authentication method to anonymous access.
Save the configuration.
First request: Without a cookie, the system injects one automatically
Send the first request:
curl -i http://your-function-url/On the function details page, you can click the HTTP trigger to get a temporary URL for verification.
Example:
curl -i https://test-cookies-b*******v.cn-hangzhou.fcapp.runExpected result:
Content-Length: 13 Content-Type: text/html; charset=utf-8 Set-Cookie: x-fc-cookie-session-id=3******a-c**5-4**0-a**4-e**********4; Max-Age=21600 X-Fc-Request-Id: 1-******e8-******c9-e**********8 Date: Tue, 30 Dec 2025 11:47:53 GMT Hello, World!%From the response headers, extract the cookie value (
x-fc-cookie-session-id) from theSet-Cookieheader.Record the
X-Fc-Request-Idfrom the response. You can use this to analyze request routing.
Second request: Use the extracted cookie value
Verify that the same session is routed to the same instance. Replace
<first-x-fc-cookie-session-id>with the value ofx-fc-cookie-session-idfrom theSet-Cookieheader you extracted in the previous step.curl -i -b "x-fc-cookie-session-id=<first-x-fc-cookie-session-id>" https://your-function-url/Example:
curl -i -b "x-fc-cookie-session-id=3******a-c**5-4**0-a**4-e**********4" https://test-cookies-b********v.cn-hangzhou.fcapp.runExpected result:
HTTP/1.1 200 OK Content-Length: 13 Content-Type: text/html; charset=utf-8 X-Fc-Request-Id: 1-******cb-******16-e**********2 Date: Tue, 30 Dec 2025 12:12:59 GMT Hello, World!%Affinity verification: On the function details page in the console, click instances > instance logs. You can observe that both requests were processed by the same instance by checking the
X-Fc-Request-Id.The second request includes the cookie obtained from the first request. The logs for the same instance show the following output.
2025-12-30 20:19:41 FC Invoke Start RequestId: 1-695xxx08d1309db 2025-12-30 20:19:41 FC Invoke End RequestId: 1-69xxx1309db 2025-12-30 20:19:42 * Serving Flask app 'app' * Debug mode: off WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead. * Running on all addresses (0.0.0.0) * Running on hxxx * Running on hxxx Press CTRL+C to quit Path: Data: b'' 21.0.X.X - - [30/Dec/2025 12:19:41] "GET / HTTP/1.1" 200 - 2025-12-30 20:22:18 FC Invoke Start RequestId: 1-695xxxa15fef9d 2025-12-30 20:22:18 FC Invoke End RequestId: 1-695xxxa15fef9d 2025-12-30 20:22:19 Path: Data: b'' xxx - - [30/Dec/2025 12:22:18] "GET / HTTP/1.1" 200 -
Third request: Without a cookie, the system generates a new one
Send a new request:
curl -i https://your-function-url/Example:
curl -i http://test-cookies-o********j.cn-hangzhou.fcapp.run/Expected result: The system generates a different cookie value for the new session.
Access-Control-Expose-Headers: Date,x-fc-request-id Content-Disposition: attachment Content-Length: 13 Content-Type: text/html; charset=utf-8 Set-Cookie: x-fc-cookie-session-id=d******e-***3-4**5-a**2-3**********d; Max-Age=21600 X-Fc-Request-Id: 1-******cb-******16-1**********a Date: Tue, 30 Dec 2025 12:31:00 GMT Hello, World!%Affinity verification: If number of concurrent sessions per instance is set to 2, the new session should be bound to the same instance. Check the instances > instance logs on the function details page in the console, using the
X-Fc-Request-Idto confirm.Instance log verification (Instance specs: 0.35 vCPU / 512 MB memory, Function: test-cookies, custom runtime: Debian 10): The first two requests used the same cookie value, while the third request used a new cookie value, confirming that session affinity is working.
2025-12-30 20:26:41 * Serving Flask app 'app' * Debug mode: off WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead. * Running on all addresses (0.0.0.0) * Running on xxx * Running on xxx Press CTRL+C to quit 2025-12-30 20:31:00 FC Invoke Start RequestId: 1-6xxx60a # Same cookie value 2025-12-30 20:31:00 FC Invoke End RequestId: 1-6xxx1760a 2025-12-30 20:31:01 Path: Data: b'' 2xxx -- [30/Dec/2025 12:31:00] "GET / HTTP/1.1" 200 – 2025-12-30 20:33:03 FC Invoke Start RequestId: 1-6xxxe69 # Same cookie value 2025-12-30 20:33:03 FC Invoke End RequestId: 1-6xxxe69 2025-12-30 20:33:04 Path: Data: b'' 2xxx -- [30/Dec/2025 12:33:03] "GET / HTTP/1.1" 200 – 2025-12-30 20:33:48 FC Invoke Start RequestId: 1-6xxx385d # New cookie value 2025-12-30 20:33:48 FC Invoke End RequestId: 1-6xxx385d 2025-12-30 20:33:49 Path: Data: b'' 2xxx -- [30/Dec/2025 12:33:48] "GET / HTTP/1.1" 200 –
Fourth request: Without a cookie, verify automatic instance scaling
Send a request without a cookie to generate a new cookie value. When an instance reaches its session limit, the system binds the new session to a new instance.
curl -i http://your-function-url/Example:
curl -i http://test-cookies-o********j.cn-hangzhou.fcapp.run/Expected result:
HTTP/1.1 200 OK Access-Control-Expose-Headers: Date,x-fc-request-id Content-Disposition: attachment Content-Length: 13 Content-Type: text/html; charset=utf-8 X-Fc-Request-Id: 1-6******c-1******2-**********5d Date: Tue, 30 Dec 2025 12:33:48 GMT Hello, World!%Affinity verification: On the function details page in the console, click instances to see the new instance.
The instance list shows two instances with a status of running, both at version LATEST. This confirms that a new instance was created to handle the additional session.
FAQ
Why is cookie affinity not working?
Possible causes:
The client fails to correctly parse the session ID from the
Set-Cookieheader of the initial request or include the ID in subsequent requests.The session was terminated because it exceeded its maximum lifetime or idle timeout.
The session affinity configuration for the function was not deployed correctly.
Troubleshooting steps:
Check whether the response header of the first request contains a
Set-Cookiefield with a session ID value.Check whether subsequent requests include the Cookie header.
Verify that session affinity is enabled and deployed in the function's configuration.