Concepts

How Kobblestone works

The operator, the objects it creates for each resource, and how to read their status.

Kobblestone is a Kubernetes operator. It extends the Kubernetes API with custom resources for Minecraft and runs a controller for each of them. Whenever you create, change or delete one of these resources, its controller compares what you asked for with what exists in the cluster and creates, updates or removes the underlying objects until both match.

You never have to manage those underlying objects yourself. Changes made to them directly are overwritten the next time the operator reconciles the owning resource.

What gets created

Each resource is backed by ordinary Kubernetes objects. They live in the same namespace, usually carry the resource’s name, and are owned by it: deleting the resource deletes them too.

ResourceRuns asAlso manages
ServerStatefulSet with one replicaService, RCON Secret, NetworkPolicy, and if configured a PersistentVolumeClaim, Route and TCPRoute
NetworkDeployment running Velocityits managed Servers, Service, configuration, forwarding Secret, and if configured a Route and TCPRoute
RouterPods running mc-routerService, and if configured a TCPRoute
Backup, Restorea Job per operation
Command, CommandGroupnothing: the operator connects to RCON itself
Accounta Job per sign-in or refreshthe session Secret and a credentials Secret
BotDeployment running Minecraft-Console-Clienta ConfigMap with its configuration

A server pod runs two containers: server, the Minecraft server itself, and proxy, a small mc-router sidecar that sits in front of the server’s Minecraft port.

The images behind it

Kobblestone builds on proven open source images instead of reinventing them:

Used byImage
Serveritzg/minecraft-server
Router and the server sidecaritzg/mc-router
Networkitzg/mc-proxy
Online backupsitzg/mc-backup
Accountghcr.io/kobblestoneio/account-auth
Botghcr.io/kobblestoneio/bot-runner, bundling Minecraft-Console-Client

Most resources let you override the image in their pod or job settings, for example to pin a version.

The server image in particular has many more options than the Server spec covers. Any of its environment variables can be set through spec.pod.env.

Reading the status

Every resource reports what is going on in its status, and kubectl get shows the most important parts as columns:

Terminal window
kubectl get servers,routers,backups -A
  • status.phase is the short answer: Running, Pending, Completed, Failed and so on, depending on the resource.
  • status.message explains a phase that needs explaining, for example why a Backup is still waiting or why a Bot was disconnected.
  • status.conditions list individual aspects, for example whether a server’s RCON is available or a backup is in progress.
  • Events record what the operator did and why it could not continue. They show up at the bottom of kubectl describe.

When something does not behave as expected, kubectl describe <kind> <name> is almost always the first step. See troubleshooting for more.

References between resources

Resources refer to each other by name, for example a Backup names its Server and BackupRepo in targetRef and repoRef. References point into the same namespace unless a field explicitly allows a different one. If a referenced resource does not exist yet, the operator does not fail: it reports what it is waiting for and tries again, so you can apply resources in any order.