Allow mc-router to scale a backend StatefulSet while routing traffic to a proxy via proxyServerName #511
Description
Allow mc-router to scale a backend StatefulSet while routing traffic to a proxy via proxyServerName
Problem Statement
mc-router currently couples the workload it scales with the Service it routes traffic to.
This prevents a common and well-understood production topology from working correctly:
Client
→ mc-router (hostname-based routing)
→ Proxy (Velocity / BungeeCord)
→ Backend StatefulSet (Forge / NeoForge / Fabric servers)
In this topology:
- mc-router receives the original client connection and hostname
- mc-router determines which backend server is being requested via
externalServerName - BUT mc-router can only scale the Service it routes traffic to
- Therefore it can only scale the proxy, not the backend server that must wake
As a result, scale-from-zero backend servers cannot be used when a proxy layer is required.
Real-world impact
This limitation blocks:
- Forge / NeoForge server fleets
- Proxy-based Minecraft networks
- Scale-to-zero modded servers
- Architectures where a proxy is mandatory for:
- authentication forwarding
- server switching
- shared lobbies
Users must currently choose between:
- mc-router autoscaling or
- proxy-based architectures
But not both.
Proposed Solution (mc-router–specific, minimal)
Introduce an optional annotation that allows traffic routing to be overridden without changing the scaling target.
Existing annotation (unchanged)
mc-router.itzg.me/externalServerName: atm-10.mc.example.net
New optional annotation
mc-router.itzg.me/proxyServerName: mc-proxy.minecraft.svc.cluster.local
Intended behavior
Given a Service annotated like:
metadata:
annotations:
mc-router.itzg.me/externalServerName: atm-10.mc.example.net
mc-router.itzg.me/proxyServerName: mc-proxy.minecraft.svc.cluster.local
mc-router would:
1. Receive a connection for atm-10.mc.example.net
2. Match the backend server using externalServerName (existing behavior)
3. Scale the backend StatefulSet associated with this Service (existing behavior)
4. Route traffic to the Service specified by proxyServerName instead of this Service while preserving hostname for additional routing.
Result:
• Scaling remains tied to the backend server
• Traffic flows through the proxy
• Proxy forwards traffic to the backend once it becomes available
Backward compatibility
• If proxyServerName is not present:
• behavior is identical to current mc-router behavior
• No changes to:
• hostname matching
• TCP handling
• protocol behavior
Existing installations remain unaffected.
⸻
Why this belongs in mc-router
Current workarounds require duplicating logic elsewhere:
• Velocity plugins
• external webhooks
• client-side pre-launch triggers
• custom controllers
These approaches:
• lose hostname context
• introduce extra latency and failure modes
• reimplement logic mc-router already owns
mc-router is uniquely positioned because it:
• sees the original client hostname
• already determines which server is requested
• already performs scale-from-zero actions
This proposal simply allows scaling and traffic routing to be decoupled in a controlled, explicit way.