Fallback routes redirect players to an alternative server when their primary destination is unreachable — for example, when a game server is offline, full, or being restarted. This is handled entirely by the network proxy; the edge layer is not involved.
When fallback routes activate
The network proxy activates a fallback route when:
- The primary backend server is offline (connection refused / timeout).
- The primary server is full (player count at maximum).
The network proxy evaluates MinecraftFallbackRoute rules in priority order after it finds the primary MinecraftJoinRoute backend unavailable.
Basic fallback route
This example sends players to the lobby server whenever a primary route fails:
apiVersion: gateway.networking.minefleet.dev/v1alpha1
kind: MinecraftFallbackRoute
metadata:
name: lobby-fallback
namespace: default
spec:
parentRefs:
- name: my-gateway
kind: Gateway
group: gateway.networking.k8s.io
backendRefs:
- name: lobby
port: 25565
filterRules:
- type: any
rules:
- domain: "*.example.com"
Using fallbackFor to target specific services
The fallbackFor field selects which services this fallback applies to using a label selector, without hardcoding service names. The controller resolves the selector against EndpointSlice labels at snapshot build time.
filterRules:
- type: any
rules:
- fallbackFor:
matchLabels:
minefleet.dev/type: gameserver
minefleet.dev/environment: production
kubernetes.io/service-name label on EndpointSlices to resolve the selector to concrete service references. When a matched service scales to zero replicas, its EndpointSlice becomes empty and the network proxy considers it unavailable.
Combining fallbackFor with domain filtering
You can narrow a fallback to only apply for specific hostnames:
filterRules:
- type: all
rules:
- domain: play.example.com
- fallbackFor:
matchLabels:
minefleet.dev/type: survival
type: all, both conditions must match. The fallback only activates when the player connected to play.example.com and a survival server is unavailable.
Fallback priority
When multiple fallback routes could apply, priority controls which is tried first. Higher values win.
# Try the regional lobby first (priority 10)
spec:
priority: 10
backendRefs:
- name: lobby-eu
port: 25565
---
# Fall back to the global lobby if regional is also unavailable (priority 1)
spec:
priority: 1
backendRefs:
- name: lobby-global
port: 25565
Difference from join routes
Fallback routes and join routes serve different purposes and are evaluated differently:
| MinecraftJoinRoute | MinecraftFallbackRoute |
|---|
| Purpose | Route the initial connection | Redirect when primary is unavailable |
| Edge hostname routing | Yes | No |
fallbackFor selector | No | Yes |
| Evaluated by | Edge proxy + network proxy | Network proxy only |
Last modified on April 19, 2026
