Create worker-affinity.mdx

docs.json

@@ -155,7 +155,8 @@
                 "pages": [
                   "serverless/load-balancing/overview",
                   "serverless/load-balancing/build-a-worker",
-                  "serverless/load-balancing/vllm-worker"
+                  "serverless/load-balancing/vllm-worker",
+                  "serverless/load-balancing/worker-affinity"
                 ]
               },
               {

release-notes.mdx

@@ -17,6 +17,10 @@ rss: true
 
 <h4><Badge color="green">New Release</Badge> [Scale Instant Clusters - BETA](/instant-clusters/scale-clusters) </h4> You can now add pods to a running Instant Cluster to increase GPU capacity without recreating it. New pods join the cluster's private network automatically, matching the existing GPU type, template, and network storage. Currently in beta for eligible accounts.
 
+**July 14, 2026**
+
+<h4><Badge color="green">New Release</Badge> [Worker affinity for Serverless load balancer endpoints](/serverless/load-balancing/worker-affinity) </h4> You can now pin follow-up requests to the same worker using the `X-Runpod-Worker-Id` response header. Send the header back on subsequent requests to choose from three modes: soft (prefer the worker, fall back to normal selection if unavailable), strict (route only to that worker, wait if at capacity), or strict-resume (same as strict, but automatically resumes a scaled-down worker). Useful for stateful workloads where session state is held in worker memory and re-routing would require reloading it.
+
   **July 1, 2026**
 
   <h4><Badge color="blue">Improvement</Badge> [Updated Serverless endpoint creation flow](https://docs.runpod.io/serverless/endpoints/overview) </h4> The endpoint creation flow now offers six deployment paths — Hello World, Hugging Face LLM, Docker, GitHub, Flash, and Hub (which replaces the previous "Ready-to-Deploy Repos" option). Each path walks you through the   right setup for your use case.

serverless/load-balancing/worker-affinity.mdx

@@ -0,0 +1,76 @@
+---
+title: "Worker affinity"
+sidebarTitle: "Worker affinity"
+description: "Pin follow-up requests to a specific worker using the X-Runpod-Worker-Id header."
+---
+
+Worker affinity lets clients route follow-up requests to the same worker that served an earlier request. This is useful for stateful workloads where a worker holds session state in memory and re-routing to a different worker would require reloading it.
+
+## How it works
+
+Every response from the load balancer includes an `X-Runpod-Worker-Id` header that identifies the worker that handled the request:
+
+```
+X-Runpod-Worker-Id: <worker-id>
+```
+
+To pin a subsequent request to that worker, send the header back with one of the following values:
+
+| Header value                | Behavior                                                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| *(omitted or empty)*        | Normal routing — normal worker selection, no preference                                                                   |
+| `<worker-id>`               | **Soft affinity**: prefer the specified worker; fall back to normal worker selection if the worker is unavailable or at capacity |
+| `strict <worker-id>`        | **Strict affinity**: only use the specified worker; wait if the worker is at capacity, return `404` if the worker is gone |
+| `strict-resume <worker-id>` | **Strict-resume affinity**: same as strict, but also resumes the worker pod if it has been scaled down                    |
+
+## Affinity modes
+
+### Soft affinity
+
+```
+X-Runpod-Worker-Id: pod-abc123
+```
+
+- Routes to the specified worker if available.
+- Falls back to normal worker selection if the worker is unavailable, at capacity, or not found.
+- Never fails a request due to affinity — this mode is best-effort.
+
+### Strict affinity
+
+```
+X-Runpod-Worker-Id: strict pod-abc123
+```
+
+- Routes only to the specified worker.
+- If the worker is at capacity, the request waits up to ~5 minutes.
+- If the worker does not free up in time, returns `400` with reason `timed out waiting for worker`.
+- If the worker is gone, returns `404` with reason `affinity_worker_gone`.
+- Use this mode when falling back to a different worker would produce incorrect results.
+
+### Strict-resume affinity
+
+```
+X-Runpod-Worker-Id: strict-resume pod-abc123
+```
+
+- Same as strict, but also resumes a scaled-down worker before routing.
+- If the resume cannot complete immediately, it keeps retrying while the request waits.
+- Returns `400` on timeout, or `404` if the pod is truly gone (terminated or redeployed under a new ID).
+- Cross-endpoint access is not possible.
+
+`strict-resume` keeps a worker running as long as requests keep coming in. Workers scale down after being idle (no requests) for a set period. If your client sends a request before that idle period expires, the timer resets and the worker stays up. This means a worker receiving regular traffic, with or without strict-resume, will never scale down.
+
+<Note>
+  When your session is done, send your next request without the `X-Runpod-Worker-Id` header so the worker is no longer pinned and can go idle.
+</Note>
+
+## Worker ID on responses
+
+The load balancer always sets `X-Runpod-Worker-Id` on the response to reflect the worker that actually served the request. Use the value from the response header for pinning rather than tracking it separately.
+
+## Error reference
+
+| Status | Reason                 | Description                                                                                          |
+| ------ | ---------------------- | ---------------------------------------------------------------------------------------------------- |
+| `404`  | `affinity_worker_gone` | Strict or strict-resume: the requested worker is not in the active worker set                        |
+| `400`  | `worker_timeout`       | Strict or strict-resume: the pinned worker did not become available within the request timeout (~5 minutes) |