Quickstart

This guide walks you through installing minecraft-gateway and routing your first Minecraft connection.

Prerequisites

A Kubernetes cluster (1.27+)
kubectl configured to talk to your cluster
Cluster-admin permissions

Install Gateway API CRDs

minecraft-gateway builds on the Kubernetes Gateway API. Install the standard channel CRDs first:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

Install minecraft-gateway

Apply the minecraft-gateway install manifest, which includes the controller, CRDs, and RBAC:

kubectl apply --server-side -f https://github.com/minefleet/minecraft-gateway/releases/latest/download/install.yaml

Verify the controller is running:

kubectl get pods -n minecraft-gateway-system

NAME                                            READY   STATUS    RESTARTS   AGE
minecraft-gateway-controller-manager-...        1/1     Running   0          30s

Create a GatewayClass

A GatewayClass tells the controller which gateways it should manage.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: minecraft
spec:
  controllerName: minefleet.dev/gateway-controller

Apply it:

kubectl apply -f gatewayclass.yaml

Create a NetworkInfrastructure

NetworkInfrastructure configures how the gateway discovers your game servers and how the network proxy is deployed. Create it in the same namespace as your gateway:

apiVersion: gateway.networking.minefleet.dev/v1alpha1
kind: NetworkInfrastructure
metadata:
  name: my-infrastructure
  namespace: default
spec:
  discovery:
    namespaceSelector:
      from: Same
    labelSelector:
      matchLabels:
        minefleet.dev/gameserver: "true"

kubectl apply -f infrastructure.yaml

Create a Gateway

A Gateway represents your Minecraft entry point. It creates an Envoy edge proxy and a network proxy for each listener.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: minecraft
  infrastructure:
    parametersRef:
      group: gateway.networking.minefleet.dev
      kind: NetworkInfrastructure
      name: my-infrastructure
  listeners:
    - name: main
      port: 25565
      protocol: JAVA
      allowedRoutes:
        kinds:
          - group: gateway.networking.minefleet.dev
            kind: MinecraftJoinRoute
          - group: gateway.networking.minefleet.dev
            kind: MinecraftFallbackRoute

kubectl apply -f gateway.yaml

Label your game server Service

The controller discovers game servers by label. Add the label to your server’s Service:

kubectl label service my-gameserver minefleet.dev/gameserver=true

Your Service must expose port 25565 (or a port named minecraft).

Create a MinecraftJoinRoute

A MinecraftJoinRoute maps a hostname to a backend game server:

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
  backendRefs:
    - name: my-gameserver
      port: 25565
  filterRules:
    - type: any
      rules:
        - domain: play.example.com

kubectl apply -f route.yaml

Verify

Check that the route was accepted:

kubectl get minecraftjoinroute survival

Connect your Minecraft client (Java Edition) to play.example.com. The handshake hostname is matched by the edge proxy and your connection is forwarded to my-gameserver.

Next steps

Architecture overview — understand how the three layers work together
Domain routing guide — wildcards, priorities, and conflict handling
Service discovery guide — how backends are discovered
NetworkInfrastructure reference — full configuration options

Getting Started

Concepts

Guides

Reference

Prerequisites

Install Gateway API CRDs

Install minecraft-gateway

Create a GatewayClass

Create a NetworkInfrastructure

Create a Gateway

Label your game server Service

Create a MinecraftJoinRoute

Verify

Next steps

​Prerequisites

​Install Gateway API CRDs

​Install minecraft-gateway

​Create a GatewayClass

​Create a NetworkInfrastructure

​Create a Gateway

​Label your game server Service

​Create a MinecraftJoinRoute

​Verify

​Next steps

Prerequisites

Install Gateway API CRDs

Install minecraft-gateway

Create a GatewayClass

Create a NetworkInfrastructure

Create a Gateway

Label your game server Service

Create a MinecraftJoinRoute

Verify

Next steps