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 zoneStorage
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 classWithout storage, all data is lost whenever the server pod is recreated, and backups and restores are not possible.
Warning: Removing
spec.storagedeletes the claim and the data in it. The same happens when you delete theServer.
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:
| Phase | Meaning |
|---|---|
Starting | The server is starting. The first start downloads the server software and can take a while. |
Running | The server is ready for players. |
Stopping | The server is shutting down. |
Stopped | The server is stopped. Its data is kept. |
Hibernating | Auto 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| Mode | Behavior |
|---|---|
Pause (default) | The server stops ticking while it is empty. Needs Minecraft 1.21.2 or later. |
Hibernate | The server is stopped completely while it is empty and starts again when a player connects through a Router. |
LegacyPause | The server process is paused, using the image’s autopause feature. For older versions. |
None | The 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.pngBesides 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 50Network 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.