Concepts

Networks

Connect several servers behind a Velocity proxy.

A Network runs a Velocity proxy together with the servers behind it. Players connect to the proxy once and can move between servers, for example with /server <name>, without reconnecting.

The network manages its servers: it creates them as ordinary Server resources from a shared template and keeps them compatible with the proxy. You don’t have to set up forwarding, offline mode or secrets on the servers yourself.

apiVersion: kobblestone.io/v1alpha1
kind: Network
metadata:
name: my-network
spec:
serverTemplate:
eula: true
type: Paper
version: "26.2"
storage:
size: 2Gi
resources:
limits:
memory: 2Gi
servers:
- name: lobby
spec:
properties:
level-type: minecraft:flat
- name: survival
hostname: survival.example.com
try: false
spec:
storage:
size: 20Gi
route:
parentRef:
name: my-router
hostname: play.example.com

This creates the Servers my-network-lobby and my-network-survival. Players joining play.example.com land in the lobby, and /server survival or connecting to survival.example.com takes them to the survival server.

Server template

spec.serverTemplate defines what all servers of the network share: the server type, the Minecraft version and the accepted eula, which are required. All other settings of a Server (storage, resources, properties, plugins, auto sleep, …) can be set here as defaults.

Only server types that can trust a Velocity proxy are supported: Paper, Pufferfish, Purpur and Folia, which support it built in, and Fabric and Quilt, for which Kobblestone installs FabricProxy-Lite and Fabric API.

Servers

Each entry of spec.servers is one server of the network. Its name is the name players see in Velocity, and the Server resource is named <network>-<name>. The entry’s spec is merged onto the template: objects are merged field by field, all other values replace the template’s value. type, version and eula can only be set in the template.

The order of the list matters: players joining the network land on the first available server with try enabled (the default). Servers with try: false are only reachable with /server or their hostname. With hostname, an entry becomes a forced host: players connecting with that hostname go straight to that server.

The network owns its servers’ configuration. It sets up forwarding with its secret, runs them in offline mode (the proxy verifies the players) and keeps them reachable only through the proxy, so there are no route, tcpRoute or service settings for them. Changes made directly to a managed Server are reverted; change the network instead. autoSleep.mode: Hibernate is not supported for managed servers, because nothing would wake them up again. Use Pause instead.

Joining existing servers

An existing Server joins the network, keeping its data, if you name it in serverName:

servers:
- name: creative
serverName: my-creative-server

Its spec is replaced by the rendered one, so make sure the template and the entry’s spec contain everything it needs, in particular storage. A server whose storage would be removed by joining is rejected.

Removing servers

spec.serverDeletionPolicy decides what happens to a server that is removed from the list, or when the network is deleted. With Retain, the default, the server and its data are kept and it runs as a standalone server again. With Delete, the server is deleted, including its world.

Unmanaged servers

To put a server behind the proxy without letting the network manage it, mark the entry unmanaged and reference the target, a Server or another Network:

servers:
- name: legacy
unmanaged: true
targetRef:
kind: Server
name: some-other-server

The network only forwards players to it. You have to configure the target to trust the proxy yourself, for example with spec.forwarding on a Server and the network’s forwarding secret.

Proxy

spec.proxy sets the Velocity version, the number of replicas (0 stops the proxy), resources, plugins and the server icon. spec.proxy.config takes a custom velocity.toml; Kobblestone always manages servers, forced-hosts, the forwarding mode and secret, and overrides those parts.

Velocity reads its configuration only on startup, so the proxy is restarted when the configuration changes: when servers are added, removed, renamed or reordered, or a hostname or try changes. Players connected to the proxy are disconnected then. Servers that are created, deleted or restarted do not restart the proxy.

To stop all servers of a network at once, set state: Stopped in serverTemplate. Servers that set their own state in their spec keep it.

Player forwarding

Velocity forwards player information, such as names and skins, to the servers with modern forwarding and a shared secret. Kobblestone generates that secret and stores it in the network’s Secret, or uses your own via spec.proxy.forwardingSecretRef, and configures the managed servers with it.

For Paper-based servers, Kobblestone manages config/paper-global.yml, which is replaced on every start of the server. Changes to that file on the server’s volume are lost.

Status

kubectl get networks shows how many proxy replicas and servers are ready, for example 1/1 and 2/2, and status contains the same as numbers. status.servers lists the phase of each server, and problems with server entries appear in status.message and as events.

Exposing a network

A network is exposed like a server: with spec.service, spec.tcpRoute or, as in the example above, spec.route on a Router. Only the proxy is exposed, its servers stay cluster-internal.