:Session affinity configuration practices

Limits

• General limits

  • If you enable session isolation, the session affinity feature is automatically enabled and cannot be disabled. You must select one of the following affinity types: MCP SSE affinity, HeaderField affinity, or Cookie affinity.

  • If you enable request isolation, the session affinity feature is unavailable.

  • Session affinity is not supported for asynchronous task requests.

  • If you select a built-in runtime, the concurrency per instance is limited to 1. In this case, the number of concurrent sessions per instance is also limited to 1.

  • The number of concurrent sessions per instance cannot exceed the maximum number of concurrent requests per instance.

• Limits specific to MCP Streamable HTTP affinity

  • The Function Compute implementation of MCP Streamable HTTP affinity is based on MCP protocol versions 2025-03-26 and 2025-06-18. When you access a function with MCP Streamable HTTP affinity enabled, both the client and the MCP function must follow the transport protocol conventions of MCP version 2025-03-26 or 2025-06-18.

  • According to the backward compatibility rules for the MCP transport layer, a single web server can support both MCP HTTP with SSE and MCP Streamable HTTP transport modes. However, if a function supports both transport methods and is configured with MCP Streamable HTTP affinity, MCP calls made using MCP HTTP with SSE will fail because the session management mechanisms are incompatible.

    Therefore, a function that uses MCP HTTP with SSE transport cannot be called correctly if MCP Streamable HTTP affinity is enabled.

  • Functions with MCP Streamable HTTP affinity enabled can be accessed only through an HTTP trigger or a custom domain name.

  • When you use an HTTP trigger to access the function, the configured HTTP trigger must support at least the GET, POST, and DELETE request methods.

• Limits specific to MCP SSE affinity

  • When you create a function, MCP SSE affinity is not supported for built-in runtimes. If you select an MCP runtime, only MCP SSE affinity is supported.

  • You must use an official MCP client or SDK to access a function with MCP SSE affinity enabled.

• Limits specific to HeaderField affinity

  • Currently, HeaderField affinity supports only the HTTP protocol.

• Limits specific to Cookie affinity

  • Only the server-side cookie insertion mode is supported. This means that when a client accesses the function for the first time, Function Compute automatically inserts a cookie into the response.

Expected behavior of session affinity (affinity, throttling, and scheduling to a new instance)

After you select a session affinity type, the concurrency per instance is automatically set to a maximum of 200 and cannot be changed. Requests from multiple sessions share the maximum concurrency quota of 200 for a single instance. Requests that exceed the concurrency limit of a single instance are routed to other instances or throttled.

• Affinity

  The system ensures session affinity within the session lifecycle only if the total number of concurrent requests across all sessions on a single instance does not exceed the maximum concurrency quota of 200.

• Throttling

  If the total number of concurrent requests across all sessions on a single instance exceeds the maximum concurrency quota of 200, new requests for existing sessions are throttled and return a 429 error. New sessions are automatically scheduled to newly created function instances.

  For example, assume the number of concurrent sessions per instance is set to 30. If 20 active sessions are running on an instance and each session is processing 10 concurrent requests, the total number of concurrent requests on the instance reaches the maximum quota of 200 (20 × 10 = 200). In this case, any new requests for these 20 sessions are throttled. Requests for new sessions, such as the 21st session, are automatically scheduled to new function instances.

• Scheduling to a new instance

  If the configured number of concurrent sessions per instance is exceeded, new session requests are automatically scheduled to newly created function instances.

Parameter configuration guide

1. If you set the number of concurrent sessions per instance to a low value, the system creates more function instances, which increases costs. You can reduce costs by downgrading the function's resource specifications.

2. Resources are shared among multiple sessions on a single instance. You should evaluate whether resource sharing is acceptable for your use case. This can help improve resource utilization and reduce costs.

Procedure

1. Log on to the Function Compute console. In the left-side navigation pane, click Functions.

2. In the top navigation bar, select a region. On the Functions page, click Create Function.

3. In the dialog box that appears, select a function type. On the Create Function page, find the Isolation and Affinity section. Configure the parameters as described in the following steps, and then click Create.

   1. Instance Isolation

      Keep the instance isolation feature disabled.

   2. Session Affinity

   • MCP Streamable HTTP affinity

     Configuration item	Description	Example
     Session affinity type	Select MCP Streamable HTTP affinity. The system ensures that requests belonging to the same MCP Streamable HTTP session are always routed to the function instance that generated the session.	MCP Streamable HTTP affinity
     Number of concurrent sessions per instance	The maximum number of sessions that a single instance can process simultaneously. The default value is 20. The maximum number of concurrent sessions is 200.	20
     Single session lifecycle	The entire process from session creation and use to final destruction. If the single session lifecycle is exceeded, the server automatically destroys the session associated with MCP Streamable HTTP on the platform side and no longer ensures affinity for that MCP Streamable HTTP session.	21600 seconds
     Session idle duration	The session enters an idle state if the function instance receives no requests for a period of time. If the configured session idle duration is exceeded, the server automatically destroys the session associated with MCP Streamable HTTP on the platform side and no longer ensures affinity for that MCP Streamable HTTP session.	1800 seconds

   • MCP SSE affinity

     Configuration item	Description	Example
     Session affinity type	Select MCP SSE affinity. Based on the MCP SSE protocol specifications, the system ensures that client requests that carry the same session ID are always routed to the same instance to implement affinity behavior.	MCP SSE affinity
     SSE path	The path for initiating an SSE connection request.	/sse
     Number of concurrent sessions per instance	The maximum number of sessions that can be simultaneously processed by a single instance. The default value is 20. The maximum number of concurrent sessions is 200.	20

   • HeaderField affinity

     Configuration item	Description	Example
     Session affinity	Select HeaderField to implement session affinity based on the value of a specified field in the HTTP request header.	HeaderField affinity
     Header Name	The name of the header used to transmit the client ID for affinity. For example, if the affinity ID that you want to transmit is mySessionId and the Header Name is x-custom-affinity-header, you must transmit the following header and value when you use the HTTP protocol to make a call: x-custom-affinity-header:mySessionId.	x-custom-affinity-header
     Number of concurrent sessions per instance	The maximum number of sessions that can be simultaneously processed by a single instance. The default value is 20. The maximum number of concurrent sessions is 200.	20
     Single session lifecycle	The entire process from session creation and use to final destruction. If the single session lifecycle is exceeded, the server automatically destroys the session and no longer ensures affinity.	21600 seconds
     Session idle duration	The session enters an idle state if no operations are performed within a period of time. If the configured session idle duration is exceeded, the server automatically destroys the session and no longer ensures affinity.	1800 seconds

   • Cookie affinity

     Configuration item	Description	Example
     Session affinity	Select Cookie affinity to implement session affinity based on the attribute value in the HTTP cookie.	Cookie affinity
     Cookie processing method	Currently, only the cookie insertion method is supported. This means that when a client accesses the function for the first time, Function Compute automatically inserts a cookie into the response. Specifically, Set-Cookie:x-fc-cookie-session-id={CookieID} is inserted into the HTTP/HTTPS response message. When the client subsequently accesses the function with Cookie:x-fc-cookie-session-id={CookieID}, Function Compute forwards the request to the function instance where the first request was located.	Insert cookie
     Number of concurrent sessions per instance	The maximum number of sessions that can be simultaneously processed by a single instance. The default value is 20. The maximum number of concurrent sessions is 200.	20
     Single session lifecycle	The entire process from session creation and use to final destruction. If the single session lifecycle is exceeded, the server automatically destroys the session and no longer ensures affinity.	21600 seconds
     Session idle duration	The session enters an idle state if no operations are performed within a period of time. If the configured session idle duration is exceeded, the server automatically destroys the session and no longer ensures affinity.	1800 seconds

Verify the results

This section uses HeaderField affinity as an example. After you enable affinity, you can call the function by specifying an HTTP request header. Then, you can check whether requests for the same session are routed to the same function instance, provided that the configured number of concurrent sessions per instance is not exceeded.

1. Call the function multiple times with different HTTP request headers for testing. This topic uses a cURL command as an example.

   The following example shows the command. Replace `example` and `regionID` with your function URL. You can find the function URL in the Configuration Information column of the HTTP trigger on the Triggers tab of the function details page.

   curl -H "x-custom-affinity-header:mySessionId" https://example.{regionID}.fcapp.run

   If you select Cookie affinity, the format of the cURL command is as follows:

   curl -H "Cookie:x-fc-cookie-session-id={CookieID}" https://example.{regionID}.fcapp.run

2. On the function details page, click the Logs tab. You can see that requests with the same session ID are routed to the same function instance, provided that the configured number of concurrent sessions per instance is not exceeded.

FAQ