Cookie affinity configuration

Updated at:

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-Cookie header 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

  1. Log on to the Function Compute console.

  2. 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.
  3. On the function details page, click the Configuration tab.

  4. In the Advanced Settings section, find the Isolation & Affinity settings.

  5. Click Isolation & Affinity to expand the configuration panel.

  6. Enable the Session affinity switch.

Select the cookie affinity type

  1. In the Session affinity configuration area, select the cookie affinity radio button.

  2. 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:

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

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

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

  4. 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-id and a globally unique ID for the cookie value.

  • The cookie's Max-Age defaults 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:

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

  2. 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.run
    • Expected 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 the Set-Cookie header.

    • Record the X-Fc-Request-Id from the response. You can use this to analyze request routing.

  3. 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 of x-fc-cookie-session-id from the Set-Cookie header 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.run
    • Expected 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 -
  4. 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-Id to 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 –
  5. 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:

  1. The client fails to correctly parse the session ID from the Set-Cookie header of the initial request or include the ID in subsequent requests.

  2. The session was terminated because it exceeded its maximum lifetime or idle timeout.

  3. The session affinity configuration for the function was not deployed correctly.

Troubleshooting steps:

  1. Check whether the response header of the first request contains a Set-Cookie field with a session ID value.

  2. Check whether subsequent requests include the Cookie header.

  3. Verify that session affinity is enabled and deployed in the function's configuration.