A MinecraftJoinRoute maps hostnames to backend game servers. The edge proxy uses the filterRules to build its hostname-to-cluster map. When a player connects, their server_address handshake field is matched against these rules and they are forwarded to the corresponding backend.
spec.hostnames declares which hostnames this route is available for. The edge proxy uses this to know which incoming connections this route can handle. filterRules[].rules[].domain defines the actual routing logic: which domain patterns map connections to this route’s backends.
API group: gateway.networking.minefleet.dev/v1alpha1
Example
apiVersion: gateway.networking.minefleet.dev/v1alpha1
kind: MinecraftJoinRoute
metadata:
name: survival
namespace: default
spec:
parentRefs:
- name: my-gateway
kind: Gateway
group: gateway.networking.k8s.io
hostnames:
- survival.example.com
- "*.survival.example.com"
backendRefs:
- name: survival-server
port: 25565
distributionStrategy:
type: least-players
filterRules:
- type: any
rules:
- domain: survival.example.com
- domain: "*.survival.example.com"
Spec fields
parentRefs
Which Gateway listeners this route attaches to. Uses the standard Gateway API ParentReference type.
parentRefs:
- name: my-gateway
namespace: default # optional, defaults to route's namespace
kind: Gateway
group: gateway.networking.k8s.io
sectionName: main # optional, targets a specific listener by name
hostnames
hostnames:
- play.example.com
- "*.example.com"
hostname is compatible.
- An exact hostname (e.g.
play.example.com) is compatible with a listener whose hostname is the same value or a wildcard that covers it (e.g. *.example.com).
- A wildcard hostname (e.g.
*.example.com) is compatible with a listener whose hostname matches or is itself a wildcard with the same suffix.
When hostnames is omitted, the route attaches to all listeners that allow it by allowedRoutes.
hostnames is about availability — signalling to the edge which hostnames this route handles. The actual routing logic (which domain patterns map to which backends, with what conditions) lives in filterRules. In practice, you will usually set both to the same values.
backendRefs
The game server backends to forward matching connections to.
| Field | Type | Description |
|---|
name | string | Service name. |
namespace | string | Service namespace. Defaults to the route’s namespace. |
port | int | Service port number. |
weight | int | Relative weight for load balancing. |
distributionStrategy.type | string | How players are distributed across backend instances. |
distributionStrategy.type values:
| Value | Description |
|---|
random | Pick a backend instance at random. |
least-players | Forward to the instance with the fewest current players. Requires the gateway.networking.minefleet.dev/current-players and gateway.networking.minefleet.dev/max-players pod annotations to be set. |
current-players >= max-players) are always excluded from selection. If all servers in a service are full, the service is treated as unavailable. See Server Capacity.
filterRules
A list of rule sets that define which hostnames this route matches. Each rule set has a type and a list of rules.
| Field | Type | Description |
|---|
type | string | any, all, or none. Controls how rules within the set are combined. |
rules | []MinecraftJoinFilterRule | The individual conditions. |
type values:
| Value | Description |
|---|
any | The connection matches if it satisfies at least one rule in the set. Each rule’s domain is added to the edge routing table. |
all | The connection matches only if it satisfies every rule in the set. Only the first rule’s domain is used for edge routing (since all conditions must match, the connection can only arrive on one hostname). |
none | The connection matches if it satisfies no rule in the set. |
MinecraftJoinFilterRule fields:
| Field | Type | Description |
|---|
domain | string | Exact hostname or wildcard pattern (e.g. play.example.com, *.example.com). |
permission | string | Permission node that the player must have. Evaluated by the network proxy. |
domain or permission must be set per rule.
priority
An integer used by the network dataplane to order routes. Higher values take precedence. When two routes could both match a connection, the higher-priority route is evaluated first. Defaults to 0.
Domain matching
Domains are matched by the edge proxy using two strategies, tried in order:
- Exact match —
play.example.com matches only play.example.com.
- Wildcard match —
*.example.com matches anything.example.com but not example.com itself.
When building the edge routing table, the controller deduplicates domains and removes exact entries that are already covered by a wildcard in the same rule set.
Status
The route’s status follows the standard Gateway API RouteStatus shape with a parents list. Each parent reports an Accepted condition indicating whether the route successfully attached to the listener.
kubectl get minecraftjoinroute survival -o yaml
Last modified on April 29, 2026
