Concepts

Exposing servers

Make servers reachable for players with a LoadBalancer, the Gateway API or a Router.

By default, a server is only reachable inside the cluster, through its Service of type ClusterIP. There are three ways to let players in. They work the same for Servers, Networks and Routers.

OptionGood forWatch out for
LoadBalancer ServiceOne or two servers, quick setupsEvery server gets its own external IP. In the cloud, each one usually costs money.
Gateway APIClusters that already run a GatewayNeeds Gateway API v1.6.0 or later with TCPRoute support.
RouterMany servers behind one address, routed by hostnamePlayers connect by hostname, so you need DNS entries.

LoadBalancer Service

Switch the server’s Service to LoadBalancer:

spec:
service:
type: LoadBalancer
annotations: {} # load balancer settings, e.g. a MetalLB address pool
rcon:
disabled: true

Warning: With a LoadBalancer, the RCON port is reachable from the outside as well. RCON is password protected but unencrypted, so disable it if the address is reachable from the internet. Note that commands and online backups need RCON.

Once the load balancer has assigned an address, it shows up in status.address and in the Address column of kubectl get servers.

Gateway API

If your cluster runs a Gateway with a TCP listener, attach the server to it. Kobblestone creates and manages the TCPRoute:

spec:
tcpRoute:
parentRefs:
- name: my-gateway
sectionName: minecraft # a TCP listener on your Gateway

A TCP listener can’t tell servers apart by hostname. Each server needs its own listener, or you attach a single Router instead and let it do the hostname routing.

Routers and Routes

A Router is a lightweight proxy for the edge of your Minecraft infrastructure. Minecraft clients send the address they connect to in their first packet, and the Router uses it to forward each player to the right backend. Only the Router needs to be exposed; all servers stay internal.

apiVersion: kobblestone.io/v1alpha1
kind: Router
metadata:
name: my-router
spec:
replicas: 2
hostnames:
- "*.example.com"
service:
type: LoadBalancer

Note: hostnames lists the hostnames the Router accepts, and wildcards are supported. An empty list does not mean “accept everything”, it accepts nothing. Use "*" to accept any hostname.

Routers scale horizontally with replicas and can themselves be exposed with a LoadBalancer or the Gateway API, as described above.

Giving a server a hostname

The easiest way to put a server behind a Router is spec.route on the server. Kobblestone creates the matching Route for you:

spec:
route:
parentRef:
name: my-router
hostname: survival.example.com

Point a DNS record for survival.example.com at the Router’s address, and players can join with that hostname.

Routes

A standalone Route maps a hostname on a Router to any backend: a Server (the default), a Network, another Router or any Service:

apiVersion: kobblestone.io/v1alpha1
kind: Route
metadata:
name: survival
spec:
parentRef:
name: my-router
hostname: survival.example.com
backendRef:
kind: Server
name: survival

kubectl get routes shows which Router each Route is attached to and the backend address it resolved. For backends outside of Kubernetes, a Router also accepts staticRoutes with a fixed address.

Networking options

spec.networking on a Router tunes how it handles connections:

spec:
networking:
maxConnectionsPerSecond: 10 # default: 1
backendDialTimeout: 5s
allowAddresses: ["0.0.0.0/0"]
denyAddresses: ["203.0.113.7"]
proxyProtocol:
receive: true
trustedProxies: ["10.0.0.0/8"]
send: true
  • maxConnectionsPerSecond limits how many new connections the Router accepts per second. The default is 1, so raise it if many players join at the same time.
  • allowAddresses and denyAddresses filter clients by IP or CIDR range.
  • proxyProtocol keeps the real player IPs. receive accepts the PROXY protocol from a load balancer in front of the Router, limited to trustedProxies if set. send passes it on to the backends. Only enable send if your backends expect it, such as a Velocity proxy with haproxy-protocol enabled. Backends that don’t expect it can’t make sense of these connections.