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.
| Resource | Runs as | Also manages |
|---|---|---|
Server | StatefulSet with one replica | Service, RCON Secret, NetworkPolicy, and if configured a PersistentVolumeClaim, Route and TCPRoute |
Network | Deployment running Velocity | its managed Servers, Service, configuration, forwarding Secret, and if configured a Route and TCPRoute |
Router | Pods running mc-router | Service, and if configured a TCPRoute |
Backup, Restore | a Job per operation | |
Command, CommandGroup | nothing: the operator connects to RCON itself | |
Account | a Job per sign-in or refresh | the session Secret and a credentials Secret |
Bot | Deployment running Minecraft-Console-Client | a 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 by | Image |
|---|---|
Server | itzg/minecraft-server |
Router and the server sidecar | itzg/mc-router |
Network | itzg/mc-proxy |
| Online backups | itzg/mc-backup |
Account | ghcr.io/kobblestoneio/account-auth |
Bot | ghcr.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:
kubectl get servers,routers,backups -Astatus.phaseis the short answer:Running,Pending,Completed,Failedand so on, depending on the resource.status.messageexplains a phase that needs explaining, for example why aBackupis still waiting or why aBotwas disconnected.status.conditionslist 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.