The HeaderField affinity feature routes requests to the same function instance based on a specified field in the HTTP request header. You can use a client-provided session ID or have one generated by the server.
Core configuration
On the function's configuration page, navigate to Advanced Configuration > Isolation & Affinity. Turn on the Session Affinity switch, select HeaderField Affinity, and configure the Header Name (such as mySessionId), Concurrent Sessions per Instance, and Session Lifecycle Configuration. Click Deploy to enable the feature.
The client can include a custom session ID in the request header. Alternatively, the server can automatically generate a session ID and return it in the response header.
Scope
General limits: For more information, see General limits and principles of session affinity.
Session ID source:
If the client passes a session ID in the predefined header, this value is used as the session identity.
Length: 1 to 64 characters.
Must be a string that starts with a letter, digit, or underscore (_), followed by letters, digits, underscores (_), or hyphens (-).
If no ID is passed, the server generates a globally unique session ID. This ID is returned in the response header using the header field that you specified during function creation.
Header field definition: When you create a function, specify the header field name for passing the session ID in
SessionAffinityConfig.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 an 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 manage the session lifecycle, such as creating, updating, querying, and terminating sessions, using the SessionAPI.
Configure HeaderField affinity
Process overview
Configuring HeaderField affinity involves four steps: enabling session affinity, selecting the HeaderField type, configuring the header name, and configuring parameters before you deploy the function. You can perform this configuration when you create a function or add it to an existing function.
Enable session affinity
Log on to the Function Compute console.
In the function list, select the target function or create a function.
When you create a function, navigate to the Advanced Configuration section. Locate the Isolation & Affinity settings and configure them before you create the function.
On the function details page, click the Configuration tab.
In the Advanced Configuration section, locate the Isolation & Affinity settings.
Click Isolation & Affinity to expand the configuration panel.
Turn on the Session Affinity switch.
Select the HeaderField affinity type
In the session affinity configuration section, select the HeaderField Affinity radio button.
The configuration options for HeaderField affinity are automatically displayed.
Configure the Header Name
Purpose: Specify the name of the HTTP request header used to pass the session ID.
Procedure:
In the Header Name input box, enter a custom header name.
Naming conventions:
Must not start with the
x-fc-prefix.Must start with a letter.
Subsequent characters can include digits, hyphens, underscores, and letters.
Length: 5 to 40 characters.
Examples:
mySessionId,session-id, andcustomSessionId.Recommendation: Use a meaningful name for easy identification and maintenance.
Configure session parameters
Purpose: Configure the number of sessions, lifecycle duration, and idle time to control session attachment and resource usage.
Procedure:
Concurrent Sessions per Instance: Specify the maximum number of sessions that a single instance can process simultaneously.
Default value: 20.
Value range: 1 to 200.
Recommendation: Specify a smaller value, such as 10, for testing scenarios. Adjust the value for production environments as needed.
Session Lifecycle: Specify 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.
Session Idle Time: Specify the duration of inactivity after which a session is automatically destroyed.
Default value: 1,800 seconds (30 minutes).
Description: If an instance receives no requests during this period, the session becomes idle and is automatically destroyed.
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 a system default value and cannot be manually adjusted.
Do not modify the Header Name after it is configured. If you modify it, you must update the client accordingly.
Verify the HeaderField affinity feature
Purpose: Verify that requests with the same HeaderField value are routed to the same instance and that the instance auto-scaling mechanism works as expected.
You can view instance scaling changes on the function details page in the console.
Procedure:
Prepare the test environment
Ensure that the function is deployed and HeaderField affinity is configured. For example, specify
mySessionIdas the Header Name and set Concurrent Sessions per Instance to 2.On the function details page, click Triggers to obtain the function's HTTP trigger URL.
If the HTTP trigger uses signature authentication, you can change it to allow anonymous access for testing.
Test the server-generated mode
# First request, without a header. The server automatically generates a session ID.
curl -v http://your-function-url/your-pathExtract the value of the header name that you configured from the response header. This value is the server-generated session ID.
Record the instance ID from the response.
Verify that the same session is routed to the same instance
# Use the extracted session ID for subsequent requests.
curl -v -H "mySessionId: <Session ID extracted from the response>" http://your-function-url/your-pathVerification point: Multiple requests must be routed to the same instance. On the function details page, click the Instances button to check whether a new instance is created.
Test the client-provided mode
# The client actively provides a session ID.
curl -v -H "mySessionId: session-2" http://your-function-url/your-pathVerification point: If Concurrent Sessions per Instance is set to 2, the new session must be attached to the same instance.
Verify instance auto-scaling
# The client provides a new session ID.
curl -v -H "mySessionId: session-3" http://your-function-url/your-pathVerification point: When the number of sessions on the instance reaches the limit, the new session must be attached to a newly created instance.
Expected results:
Requests with the same HeaderField value are routed to the same instance.
Both client-provided and server-generated modes work as expected.
When the number of sessions on an instance reaches the limit, the system automatically creates a new instance.
FAQ
What is the difference between the client-provided and server-generated modes?
Differences:
Client-provided mode: The client actively controls the session ID. This is suitable for scenarios where you need to use custom session IDs.
Server-generated mode: The server automatically generates the session ID. The client only needs to extract the session ID from the response header and include this ID in subsequent requests. This is suitable for scenarios where you want to simplify the client-side implementation.
Recommendations:
Use the client-provided mode when you need custom session IDs or need to integrate with existing systems.
Use the server-generated mode when you want to simplify the client-side implementation.