Skip to content

Explain proxyrunner session-aware backend pod routing#710

Open
yrobla wants to merge 1 commit intomainfrom
issue-708
Open

Explain proxyrunner session-aware backend pod routing#710
yrobla wants to merge 1 commit intomainfrom
issue-708

Conversation

@yrobla
Copy link
Copy Markdown
Contributor

@yrobla yrobla commented Apr 14, 2026

Summary

run-mcp-k8s.mdx documented backendReplicas but gave no explanation of why Redis matters for backend scaling or how the proxy runner routes sessions to pods. Users could misconfigure or skip Redis when only scaling backends.

  • Adds a Session routing for backend replicas subsection explaining that the proxy runner stores a session-to-pod mapping in Redis, what happens on backend pod restart, and why client-IP affinity is unreliable behind NAT
  • Absorbs the previous standalone SessionStorageWarning note into the new subsection so the backendReplicas implication is explicit rather than buried
  • Updates the Redis link to point directly to #horizontal-scaling-session-storage (added in Add horizontal scaling Redis session storage guide #709)

Test plan

  • Section renders correctly in Docusaurus
  • Redis link resolves to the correct anchor in the session storage guide

Closes #708

🤖 Generated with Claude Code

Copilot AI review requested due to automatic review settings April 14, 2026 13:13
@vercel
Copy link
Copy Markdown

vercel bot commented Apr 14, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs-website Ready Ready Preview, Comment Apr 14, 2026 1:35pm

Request Review

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates the Kubernetes “run MCP” guide to clarify why Redis is important when scaling backend replicas by documenting how the proxy runner performs session-aware routing to backend pods.

Changes:

  • Added a “Session routing for backend replicas” subsection explaining Redis-backed session-to-pod routing, NAT pitfalls with client-IP affinity, and behavior on backend pod replacement.
  • Merged the previous standalone SessionStorageWarning note into the new routing explanation so the backendReplicas implications are explicit.
  • Updated the Redis session storage link to point at a specific in-page anchor.

Users scaling backendReplicas > 1 had no explanation of why Redis is
needed or how the proxy runner routes sessions to backend pods.

- Add a "Session routing for backend replicas" subsection explaining
  that the proxy runner uses Redis to store session-to-pod mappings,
  what happens when a backend pod restarts, and why client-IP affinity
  alone is unreliable behind NAT
- Absorb the standalone SessionStorageWarning note into the new
  subsection so the backendReplicas implication is explicit
- Update Redis link to point directly to the horizontal scaling anchor

Closes #708

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Copy link
Copy Markdown
Collaborator

@danbarr danbarr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the PR description you mentioned adding an anchor link to a new heading introduced in the unmerged #709. But the link is not actually present in this PR. Suggest making this one a draft dependent on 709, then add the anchor once it's present.

Comment on lines +467 to +468
table is invalidated and the next request reconnects to an available pod —
sessions are not automatically migrated between pods.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style: em dashes

Suggested change
table is invalidated and the next request reconnects to an available pod
sessions are not automatically migrated between pods.
table is invalidated and the next request reconnects to an available pod.
Sessions are not automatically migrated between pods.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: explain proxyrunner session-aware backend pod routing when using backendReplicas

4 participants