All Products
Search

This Product

    Function Compute:Configure cookie affinity

    Document Center

    Function Compute:Configure cookie affinity

    Last Updated:Dec 31, 2025

    In a distributed Function Compute scenario, requests may be routed to different instances, which can prevent the session state from being maintained. The cookie affinity feature ensures session consistency by automatically inserting a cookie on the server-side. This routes requests that have the same cookie value to the same function instance.

    Core configuration

    On the function configuration page, navigate to Advanced Configuration > Isolation and Affinity. Turn on the Session Affinity switch, select Cookie Affinity, configure Concurrent Sessions per Instance and Session Lifecycle, and then click Deploy to enable the feature.

    For the first request, the system automatically inserts a cookie into the response header. Subsequent client requests that include this cookie are routed to the same instance.

    Scope

    • General limits: For more information, see General limits and principles of session affinity.

    • Server-side cookie insertion only: When a client makes its first request, Function Compute automatically inserts a cookie into the response using the Set-Cookie header. The client must parse and save this cookie, and include it in subsequent requests.

    • Request limits:

      • A single instance can process multiple sessions simultaneously. The default value is 20 and the maximum value is 200. When the number of sessions attached to a single instance reaches the limit, the system automatically creates a new instance.

      • Multiple sessions share the instance's concurrency quota of 200.

    • SessionAPI management support: You can use the SessionAPI to manage the session lifecycle, such as creating, updating, querying, and stopping sessions.

    Configure cookie affinity

    Flow overview

    Configuring cookie affinity involves three steps: enabling session affinity, selecting the cookie type, and configuring the parameters and deploying the function. You can configure these settings when you create a function or update an existing function.

    Enable session affinity

    1. Log on to the Function Compute console.

    2. Go to the function list and select the target function or create a function.

      When creating a function, in the Advanced Configuration section, find the Isolation and Affinity settings and complete the following configuration steps.

    3. On the function details page, click the Configuration tab.

    4. In the Advanced Configuration section, you can find the Isolation and Affinity settings.

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

    6. Enable Session Affinity.

    Select the cookie affinity type

    1. In the Session Affinity section, select the Cookie Affinity radio button.

    2. The configuration options for cookie affinity are automatically displayed.

    Configure session parameters

    Objective: Set the number of sessions, lifecycle, and idle duration to control session binding and resource usage.

    Procedure:

    1. Concurrent Sessions Per Instance: Specifies the maximum number of sessions that a single instance can process concurrently.

      • Default value: 20

      • Value range: 1 to 200

      • Suggestion: Set a smaller value, such as 10, for staging environments. Adjust the value for production environments as needed.

    2. Single Session Lifecycle: Sets the maximum duration of a session from creation to destruction.

      • Default value: 21,600 seconds (6 hours)

      • Description: After this period, the system automatically destroys the session, and affinity is no longer guaranteed.

    3. Session Idle Duration: Specifies how long a session can be idle before it is automatically destroyed.

      • Default value: 1,800 seconds (30 minutes)

      • Description: If a session receives no requests for this duration, it enters an idle state and is automatically destroyed.

    4. Click the Deploy button to save the configuration.

    Important:

    • After you enable session affinity, the system automatically sets the Concurrency per Instance to 200. This is the system default and cannot be manually adjusted.

    • If you configure session affinity when you create a function, the configuration is created with the function. If you configure session affinity for an existing function, you must deploy the configuration separately.

    • The cookie name is automatically generated by the system in the format x-fc-cookie-session-id. The cookie value is an automatically generated globally unique ID (GUID).

    • The Max-Age of the cookie defaults to 21,600 seconds (6 hours), which is consistent with the session lifecycle.

    Verify the cookie affinity feature

    Objective: Verify that requests with the same cookie value are routed to the same instance and that the automatic instance scale-out mechanism works.

    • Requests with the same cookie value are routed to the same instance.

    • When the number of sessions for an instance reaches the limit, the system automatically creates a new instance.

    • All requests return a success status code (200).

    You can observe instance scale-out changes on the function details page in the console.

    Procedure:

    1. Prepare the staging environment

      • Make sure the function is deployed and cookie affinity is configured. We recommend that you set Concurrent Sessions per Instance to 2 for testing.

      • Obtain the URL of the function's HTTP trigger.

      • For testing, you can change the authentication method of the HTTP trigger from signature authentication to anonymous access:

        • Go to the Triggers tab on the function details page.

        • Click the Edit button for the trigger.

        • Set Authentication Method to Anonymous Access.

        • Save the configuration.

    2. First request: Without a cookie, the system automatically inserts a cookie

      • Send the first request: curl -i http://your-function-url/

        On the function details page, click the HTTP trigger to obtain 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 header, extract the cookie value (x-fc-cookie-session-id) from Set-Cookie.

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

    3. Second request: Send a request with 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 that 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!%

      • Verify affinity: On the function details page in the console, click Instances > Instance Logs. The logs show that both requests were processed by the same instance, which you can verify by checking the X-Fc-Request-Id.

    4. Third request: Without a cookie, the system generates a new cookie

      • 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!%

      • Verify affinity: If Concurrent Sessions per Instance is set to 2, the new session should be attached to the same instance. You can check this on the function details page in the console by clicking Instances > Instance Logs. You can verify this by checking the X-Fc-Request-Id.

    5. Fourth request: Without a cookie, verify automatic instance scale-out

      • Send a request without a cookie to generate a new session. Because the number of sessions on the instance has reached the limit, the new session is attached to a newly created 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!%

      • Verify affinity: On the function details page in the console, click Instances. You can see the new instance.

    FAQ

    Why is cookie affinity not working?

    Possible causes:

    1. The client did not correctly parse the session ID from the Set-Cookie header of the first request and did not include this ID in subsequent requests.

    2. The session was destroyed because it exceeded its lifecycle or idle duration.

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

    Troubleshooting steps:

    1. Verify that the response header of the first request contains a Set-Cookie field and that the field contains a session ID value.

    2. Verify that subsequent requests include the Cookie header.

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