Repository navigation
v0.2.0
Kobblestone now has a website! Feel free to check it out: https://kobblestone.io
Upgrade Notes
- Let all running
Backups andRestores finish before upgrading. Jobs created by previous versions are not considered when serializing backups and restores. - Apply the complete manifest of this release. The operator requires additional RBAC permissions (listing
Backups,Restores andJobs, readingPersistentVolumeClaims, managingLeases, and patchingSecrets, which it grants to the authJobs ofAccounts). - The operator now uses leader election via a
Leasein its own namespace. After a restart or rollout, a new operator Pod waits until the lease of the previous Pod has been released or has expired (at most 15 seconds) before it starts reconciling. - A
Serveris now kept stopped while aRestoreor an offlineBackupof it is running, even ifspec.stateisRunningor the server is woken up from hibernation. It is started as soon as the operation has finished. - The auto-sleep webhook now requests hibernation by setting the annotation
kobblestone.io/hibernate: "true"on theServerinstead of writing its status. The operator records the request in theHibernatingcondition and removes the annotation, as it already did forkobblestone.io/wake-up. status.addressofServers now contains the IP address of the server'sServiceinstead of its cluster-internal DNS name and port (<name>.<namespace>.svc.cluster.local:<port>). It is shown in the newAddresscolumn. TheHostcolumn (the hostname ofspec.route) was removed fromServers andNetworks.BackupRepos of typePersistentVolumeClaimnow create their claim with the name fromspec.persistentVolumeClaim.name. Previously, the claim was named after theBackupRepo. If those names differed, a new claim is created on upgrade. The old claim (and the snapshots in it) is left untouched and can be migrated or deleted manually.Bots are now based on Minecraft-Console-Client (MCC) instead of Mineflayer. TheBotBehaviorresource was removed; delete allBotBehaviors and the CRD (kubectl delete crd botbehaviors.kobblestone.io).spec.behaviors,spec.viewer,spec.serviceandspec.auth.enableChatSigningofBots were removed: rewrite behaviors as MCC configuration (spec.config) and scripts (spec.scripts), and usespec.auth.signChat. The<bot>Serviceand<bot>-viewerHTTPRouteof existingBots are no longer managed and can be deleted.Accounts have to be authorized again once. Their sessionSecretis replaced by one of typekobblestone.io/minecraft-sessionin a new, client independent format (seedocs/design/0001-accounts-and-bots-on-mcc.md); the refresh token moved to the new<account>-credentialsSecret. Workloads that read the oldSecretkeys (prismarine-auth caches) have to be adapted.
Changes by Kind
Feature
- New
Bots: aBotis a single Minecraft-Console-Client instance connected to oneServer,Networkor host. It is programmed with MCC's TOML configuration (spec.config.inlineand keys ofConfigMaps/Secrets inspec.config.from) and MCC command or C# scripts (spec.scripts, inline or fromConfigMaps/Secrets, optionally run on every login). Additional volumes (e.g.PersistentVolumeClaims with data files) can be mounted viaspec.pod.volumes/spec.pod.volumeMounts. Bots report their state instatus.phase(Pending,Inactive,Connected,Disconnected),status.message(e.g. the kick reason), the resolvedstatus.address,status.username,status.restartsand aConnectedcondition. Disconnected bots are restarted with backoff.Bots referencing anAccountstay scaled down until theAccountis authorized and restart with the new session whenever theAccountrefreshed it.- New
Kobblestone.AccountAuth(imageghcr.io/kobblestoneio/account-auth), replacing the Node.js implementation: performs the Microsoft device code flow and session refreshes and writes only theAccount'sSecrets. TheAccountstatus is derived by the operator from theseSecrets and the authJob; theJobno longer needs permissions onAccounts. It is configured with command line arguments orAUTH_-prefixed environment variables (see--help) and can also be run locally against a kubeconfig. Accountsessions are stored in a standard format (Secrettypekobblestone.io/minecraft-session, libraryKobblestone.Sessions) with the username, UUID, access token, expiry and optional chat signing key pair, so they can be mounted by any workload, not only byBots.- Failed
Accountauthorizations (e.g. an expired device code) are retried after 10 minutes, with the reason (e.g. no Minecraft profile, Xbox account restrictions) instatus.message. Finished authJobs are kept for one hour. - New
Kobblestone.BotRunner(imageghcr.io/kobblestoneio/bot-runner), replacing the Node.js bot runner: merges the configuration layers, hands the session over to MCC and runs it. LikeKobblestone.AccountAuth, it is configured with command line arguments orBOT_-prefixed environment variables (see--help). Backups andRestores of the sameServerare queued and run one after another, in the order they were created. Waiting requests do not get aJobuntil they can run. The runningJobs are the single source of truth, so a failed or deletedJobcan no longer leave aServerlocked.Backups,Restores and snapshot cleanups using aBackupRepoof typePersistentVolumeClaimrun one at a time per volume, unless the claim supportsReadWriteMany. This prevents Multi-Attach errors when multiple operations would run on different nodes.- Online backups of running servers are scheduled on the node of the
ServerPod. Offline backups of stopped servers can run on any node. - The
ServerconditionsBackupInProgressandRestoreInProgressnow reflect the runningJobs and correct themselves on every reconcile. - Reasons why a resource cannot be reconciled yet (e.g. a missing
BackupRepo, aServerthat is not stopped or busy, an unknownRouter) are now reported as Kubernetes events and, forBackups andRestores, instatus.message. The resource is retried periodically instead of failing the reconciliation. Backups andRestores are marked asFailedif theirJobis deleted before it finished.- Leader election is enabled, so the operator can safely run with multiple replicas.
- Every resource's status is now written only by its own controller. Controllers watching child resources (Jobs, StatefulSets, Services,
Commands) queue the owning resource for reconciliation instead of updating its status, which prevents conflicting and lost status updates. Routers,Servers andNetworks report the IP address of theirServiceinstatus.address(shown in theAddresscolumn), preferring external addresses: the IP assigned by a load balancer, then the first ofspec.externalIPs, then the cluster IP. The address is updated as soon as theServicechanges, e.g. when a load balancer assigned an IP.- All fields of all resources are now documented in the CRDs (shown by
kubectl explainand in the CRD reference docs). Backups andRestores have a new status fieldstartedAt, the time theirJobwas created.
Bug or Regression
- Fix
Routes being deleted right after their creation when aServerorNetworkwithoutspec.routehas the same name.Servers andNetworks now only update or delete theRoutethey created forspec.route. - Fix two pending
Backups of the sameServerblocking each other forever. - Fix
Restores not waiting for runningBackups or otherRestores of the sameServer. - Fix online backups failing with Multi-Attach errors when the backup Pod was scheduled on a different node than the
Server. - Fix backup Pods being blocked from accessing RCON by the
NetworkPolicyof theServer. - Fix reconciliation errors for
Backups andRestores whoseJobalready existed (e.g. after an operator restart). - Fix a stale
BackupInProgresscondition blocking the deletion of aServerforever. - Fix
Routes not being retried when theirRouterdid not exist yet. - Fix
Commands not being retried when the RCON password secret did not exist yet. - Fix
BackupRepos of typePersistentVolumeClaimcreating their claim with the name of theBackupRepoinstead ofspec.persistentVolumeClaim.name. - Fix
Restores ignoringspec.job.image. - Fix
Networks ignoringspec.proxy.offline. If set totrue, the proxy now runs withonline-mode = false. - Fix the documentation of
Serverspec.lifecycle.rolloutPolicy, which listedOnRestartinstead of the actual valueManual. - Fix
Routers reporting their cluster IP when the first load balancer ingress entry had a hostname instead of an IP. - Fix the auto-sleep webhook never hibernating a
Server(namespace and name were swapped when looking up the server). - Fix
Servers never hibernating again after being woken up, because thekobblestone.io/wake-upannotation was never removed. - Fix
Backups withretainPolicy: RequireDeletenever retrying a failed cleanup. Deleting the failed cleanupJobnow starts a new one.
Dependency
- Bump KubeOps to
13.3.3. - Bump
KubernetesCRDModelGen.Models.gateway.networking.k8s.ioto1.57.0. - Bump
itzg/mc-backupto2026.10.0forBackups. - Pin
itzg/mc-proxytojava25-2026.10.0forNetworks. - Bump
itzg/mc-routerto1.48.0forRouters andServersidecars. WithautoSleep.mode: Hibernate, only player logins reset the scale-down timer now, so server list pings no longer keep a server awake. - Bump
itzg/minecraft-serverto2026.10.0forServers. - Bump
amazon/aws-clito2.37.13forBackups,Restores and snapshot cleanups using S3 repos. Checksums are only sent when required, to stay compatible with S3-compatible providers. - Bump
ubuntuto26.04(from the end-of-life25.04) forBackups,Restores and snapshot cleanups. - Replace the Node.js images
account-authandbot-runner(Mineflayer, prismarine-auth) by .NET images in version0.2.0. The bot image bundles an unmodified Minecraft-Console-Client release (20260929-519, CDDL-1.0).