Summary
In docs/toolhive/guides-k8s/run-mcp-k8s.mdx (lines 460–468), the current wording implies Redis is always used when backendReplicas > 1. The next paragraph then describes fallback behavior without Redis, which is confusing — it reads as if Redis is unconditional, then immediately contradicts itself.
Current text:
When backendReplicas > 1, the proxy runner uses Redis to store a session-to-pod mapping so every proxy runner replica knows which backend pod owns each session.
Without Redis, the proxy runner falls back to Kubernetes client-IP session affinity on the backend Service, which is unreliable behind NAT or shared egress IPs. If a backend pod is restarted or replaced, its entry in the Redis routing table is invalidated and the next request reconnects to an available pod — sessions are not automatically migrated between pods.
Proposed fix (from PR #710 review):
When backendReplicas > 1 and Redis session storage is configured, the proxy runner uses Redis to store a session-to-pod mapping so every proxy runner replica knows which backend pod owns each session.
Without Redis session storage, the proxy runner relies on Kubernetes client-IP session affinity on the backend Service, which is unreliable behind NAT or shared egress IPs. If a backend pod is restarted or replaced, its entry in the Redis routing table is invalidated and the next request reconnects to an available pod — sessions are not automatically migrated between pods.
Why
The original phrasing makes Redis sound mandatory for multi-replica deployments. Users who aren't using Redis may be misled into thinking their setup is unsupported or broken. Making the condition explicit ("and Redis session storage is configured") ensures readers understand both paths upfront.
References
Summary
In
docs/toolhive/guides-k8s/run-mcp-k8s.mdx(lines 460–468), the current wording implies Redis is always used whenbackendReplicas > 1. The next paragraph then describes fallback behavior without Redis, which is confusing — it reads as if Redis is unconditional, then immediately contradicts itself.Current text:
Proposed fix (from PR #710 review):
Why
The original phrasing makes Redis sound mandatory for multi-replica deployments. Users who aren't using Redis may be misled into thinking their setup is unsupported or broken. Making the condition explicit ("and Redis session storage is configured") ensures readers understand both paths upfront.
References