Concepts

Servers

Server types and versions, storage, starting and stopping, auto sleep, content and access.

A Server runs a single Minecraft server, based on the itzg/minecraft-server image.

Type and version

spec.type picks the server software. It defaults to Vanilla and supports Paper, Purpur, Folia, Pufferfish, Spigot, Bukkit, Fabric, Quilt, Forge and more; see the image’s list of server types. spec.version sets the Minecraft version: a version number, LATEST for the latest release or SNAPSHOT for the latest snapshot.

The server does not start until spec.eula is true, which means you accept the Minecraft EULA.

Additional server.properties entries go into spec.properties:

spec:
properties:
difficulty: hard
max-players: "20"
motd: Welcome to the cobble zone

Storage

spec.storage gives the server a PersistentVolumeClaim for its worlds and configuration:

spec:
storage:
size: 10Gi
storageClassName: longhorn # optional, defaults to the cluster's default class

Without storage, all data is lost whenever the server pod is recreated, and backups and restores are not possible.

Warning: Removing spec.storage deletes the claim and the data in it. The same happens when you delete the Server.

Increasing size later works if the storage class supports volume expansion. The storage class is only applied when the claim is created.

Memory and Java

The server’s memory comes from its container limits in spec.resources. By default, 75% of it is reserved for the Java heap; the rest is left for the JVM itself. If servers with little memory get killed for running out of it, lower spec.jvm.memory.heapPercentage.

spec.jvm.version picks the Java version of the image, java25 by default. Older Minecraft versions may need an older one.

Starting and stopping

spec.state is Running by default. Set it to Stopped to shut the server down while keeping its data. The current state shows in status.phase:

PhaseMeaning
StartingThe server is starting. The first start downloads the server software and can take a while.
RunningThe server is ready for players.
StoppingThe server is shutting down.
StoppedThe server is stopped. Its data is kept.
HibernatingAuto sleep stopped the server. It starts again when a player connects.

While a Restore or an offline Backup of a server runs, the server is kept stopped, even if spec.state is Running.

Rolling out changes

By default, changes to the spec are rolled out immediately, which restarts the server: change spec.version and the server restarts on the new version. To decide yourself when that happens, set spec.lifecycle.rolloutPolicy: Manual. Changes are then applied the next time the server pod is recreated, for example when you stop and start the server.

Auto sleep

Empty servers do not need to burn CPU. spec.autoSleep controls what happens when no players are online:

spec:
autoSleep:
mode: Hibernate
timeoutSeconds: 300
ModeBehavior
Pause (default)The server stops ticking while it is empty. Needs Minecraft 1.21.2 or later.
HibernateThe server is stopped completely while it is empty and starts again when a player connects through a Router.
LegacyPauseThe server process is paused, using the image’s autopause feature. For older versions.
NoneThe server never sleeps.

timeoutSeconds is how long a server has to be empty before it goes to sleep, 60 seconds by default.

Plugins, mods and modpacks

spec.content installs content when the server starts:

spec:
type: Paper
content:
plugins:
- url: https://example.com/plugins/my-plugin.jar
modrinth:
projects:
- luckperms
iconUrl: https://example.com/icon.png

Besides plugin and mod URLs, it supports Modrinth projects, CurseForge files and modpacks (with an API key in a Secret), packwiz packs, Spigot resources, modpack ZIPs, a server icon and a resource pack players are prompted to download.

Whitelist and operators

spec.access manages the whitelist and operator permissions, by username or UUID:

spec:
access:
whitelist:
users: [Notch, jeb_]
enforce: true
ops:
users: [Notch]

Both lists are synchronized: players that are not listed are removed from the whitelist or lose their operator permissions. With enforce: true, players who are online but no longer whitelisted are kicked.

RCON

RCON is Minecraft’s remote console. Kobblestone enables it by default with a random password stored in the server’s Secret, and uses it for commands, spec.autoCommands and online backups. You can set spec.rcon.disabled: true, but all of these stop working then.

spec.autoCommands runs commands on certain events, for example onStartup, onFirstConnect or onLastDisconnect:

spec:
autoCommands:
onStartup:
- gamerule playersSleepingPercentage 50

Network policy

Each server gets a NetworkPolicy. By default it only allows Minecraft traffic from Routers, Networks and Bots, RCON traffic from backups, and all traffic to the server’s Service if it is of type LoadBalancer. Add your own rules in spec.networkPolicy.extraIngressRules, or turn the policy off with spec.networkPolicy.disabled: true.