Skip to content

Commit ccf21fb

Browse files
yroblaclaude
andcommitted
Clarify Redis session routing is conditional on Redis being configured
When backendReplicas > 1, the proxy runner only uses Redis for session-to-pod routing when Redis session storage is actually configured. The previous wording implied Redis was always used, then contradicted itself in the next paragraph. Closes #727 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 81c5e7d commit ccf21fb

1 file changed

Lines changed: 23 additions & 0 deletions

File tree

docs/toolhive/guides-k8s/run-mcp-k8s.mdx

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -453,6 +453,29 @@ The proxy runner handles authentication, MCP protocol framing, and session
453453
management; it is stateless with respect to tool execution. The backend runs the
454454
actual MCP server and executes tools.
455455

456+
### Session routing for backend replicas
457+
458+
MCP connections are stateful: once a client establishes a session with a
459+
specific backend pod, all subsequent requests in that session must reach the
460+
same pod. When `backendReplicas > 1` and Redis session storage is configured,
461+
the proxy runner uses Redis to store a session-to-pod mapping so every proxy
462+
runner replica knows which backend pod owns each session.
463+
464+
Without Redis session storage, the proxy runner relies on Kubernetes client-IP
465+
session affinity on the backend Service, which is unreliable behind NAT or
466+
shared egress IPs. If a backend pod is restarted or replaced, its entry in the
467+
Redis routing table is invalidated and the next request reconnects to an
468+
available pod — sessions are not automatically migrated between pods.
469+
470+
:::note
471+
472+
The `SessionStorageWarning` condition only fires when `spec.replicas > 1`
473+
(multiple proxy runner pods). It does not fire when only `backendReplicas > 1`,
474+
but Redis session storage is still strongly recommended in that case to ensure
475+
reliable per-session pod routing.
476+
477+
:::
478+
456479
Common configurations:
457480

458481
- **Scale only the proxy** (`replicas: N`, omit `backendReplicas`): useful when

0 commit comments

Comments
 (0)