HeaderField affinity routes HTTP requests to the same function instance based on a value in a specified request header. Use it to maintain stateful sessions for workloads like WebSocket connections, AI inference services that reuse model instances, or game sessions where requests from a single client must always land on the same instance.
Session ID modes
Choose how the session ID is sourced before you begin configuration:
| Mode | How it works | When to use |
|---|---|---|
| Client-provided | The client sets the session ID in the request header on every request | You need custom session IDs or integration with an existing session system |
| Server-generated | Function Compute generates a unique session ID and returns it in the response header; the client reads it and includes it in subsequent requests | You want to simplify client-side implementation |
How it works
Enable session affinity on a function and specify a header name (for example,
mySessionId).On the first request, Function Compute reads the value of the specified header. If no value is present, it generates a globally unique session ID and returns it in the response header under the same header name.
On subsequent requests, Function Compute routes traffic with the same header value to the same instance.
When the number of sessions attached to an instance reaches the Concurrent sessions per instance limit, Function Compute automatically creates a new instance for incoming sessions.
Enable HeaderField affinity
Step 1: Open the configuration panel
Log in to the Function Compute console.
In the function list, select the target function or create a function.
When creating a new function, find the Isolation & Affinity settings in the Advanced Configuration section and configure session affinity before you finish creating the function.
On the function details page, click the Configuration tab.
In the Advanced Configuration section, click Isolation & Affinity to expand the panel.
Turn on the Session Affinity switch.
Select the HeaderField Affinity radio button.
Step 2: Set the header name
In the Header Name field, enter a custom header name to carry the session ID. When creating a function, this header field name is specified in SessionAffinityConfig.
Naming rules:
| Rule | Details |
|---|---|
| Length | 5–40 characters |
| Allowed characters | Letters, digits, hyphens, and underscores |
| First character | Must be a letter |
| Prefix restriction | Must not start with x-fc- |
Examples: mySessionId, session-id, customSessionId
Do not change the header name after the function is deployed. If you do, update all clients to use the new name.
Step 3: Configure session parameters
The following table summarizes all session parameters. Configure them before clicking Deploy.
| Parameter | Default | Range | Description |
|---|---|---|---|
| Concurrent sessions per instance | 20 | 1–200 | Maximum sessions a single instance handles simultaneously. When the limit is reached, Function Compute creates a new instance. |
| Session lifecycle | 21,600 s (6 hours) | — | Maximum duration from session creation to destruction. After this period, the session is destroyed and affinity is no longer guaranteed. |
| Session idle time | 1,800 s (30 minutes) | — | If an instance receives no requests during this period, the session is automatically destroyed. |
For testing, set Concurrent sessions per instance to a small value such as 2 or 10 to make instance scaling easier to observe.
After you enable session affinity, Function Compute automatically sets Concurrency per instance to 200. This value cannot be manually adjusted. Multiple sessions on an instance share this concurrency quota of 200.
Step 4: Deploy
Click Deploy to apply the configuration.
Session ID constraints
Client-provided session ID
| Constraint | Details |
|---|---|
| Length | 1–64 characters |
| First character | A letter, digit, or underscore (_) |
| Remaining characters | Letters, digits, underscores (_), or hyphens (-) |
Server-generated session ID
Function Compute generates a globally unique session ID when no value is found in the specified request header. The ID is returned in the response header using the header name you configured.
Manage sessions with SessionAPI
Use SessionAPI to manage the session lifecycle programmatically, including creating, updating, querying, and terminating sessions.
For shared limits and general principles, see General limits and principles of session affinity.
Verify HeaderField affinity
Use the following procedure to confirm that requests with the same header value land on the same instance and that instance scaling triggers correctly.
Before you begin: Deploy the function with HeaderField affinity enabled. For this walkthrough, set Header Name to mySessionId and Concurrent sessions per instance to 2. If your HTTP trigger uses signature authentication, temporarily switch it to anonymous access for testing.
Get your function's HTTP trigger URL from the Triggers tab on the function details page.
Test server-generated mode
Send a request without the session header. Function Compute generates a session ID and returns it in the response header.
# First request — no session header. The server generates a session ID.
curl -v http://<your-function-url>/<your-path>Extract the value of the header name you configured (mySessionId) from the response header. This value is the server-generated session ID. On the function details page, click Instances to record the instance that handled the request.
Test session stickiness
Send subsequent requests with the session ID from the previous response. All requests with the same mySessionId value must route to the same instance.
# Use the session ID from the previous response.
curl -v -H "mySessionId: <session ID extracted from the response>" http://<your-function-url>/<your-path>On the function details page, click Instances to verify that no new instance was created.
Test client-provided mode
Send a request with a custom session ID.
# Client provides a session ID directly.
curl -v -H "mySessionId: session-2" http://<your-function-url>/<your-path>With Concurrent sessions per instance set to 2, this second session attaches to the same instance as the first.
Test instance scaling
Send a request with a third session ID.
# A third session ID that exceeds the per-instance limit.
curl -v -H "mySessionId: session-3" http://<your-function-url>/<your-path>On the function details page, click Instances to verify that a new instance was created.
Expected results:
Requests with the same header value route to the same instance.
Both client-provided and server-generated modes work correctly.
When the session count on an instance reaches the limit, new sessions are assigned to a new instance.
FAQ
What is the difference between client-provided and server-generated modes?
In client-provided mode, the client controls the session ID — it sets the value in the request header on every request. In server-generated mode, the client sends the first request without a header, reads the session ID from the response header, and includes it in all subsequent requests. Server-generated mode is simpler to implement on the client side; client-provided mode is useful when you need to integrate with an existing session management system or enforce specific session ID formats.