Repository navigation
Releases
Releases · kobblestoneio/kobblestone
v0.3.0
v0.3.0
Upgrade Notes
- Upgrade with the complete manifest of this release or the Helm chart: the operator needs additional permissions (managing
Servers forNetworks,ConfigMaps for the forwarding configuration ofServers, and watchingDeployments). Networks were reworked and are not compatible with previous versions. Recreate yourNetworks; there is no automatic migration:servers[]entries are now managed by default: the network creates and configures theServers itself, rendered from the newserverTemplateand each entry'sspec. To keep an existingServerand its data, name it inservers[].serverName; it joins the network. Its spec is replaced by the rendered one, so put everything it needs (includingstorage) intoserverTemplateor the entry'sspec.servers[].targetRefis only allowed together with the newunmanaged: true, which keeps the previous behavior: the proxy forwards players to the target without configuring it.serverTemplaterequirestype,versionandeula, which all servers of the network share;servers[].speccannot override them. Both contain the other settings ofServer, except those the network owns: managed servers have noforwarding,offline,route,tcpRouteorservicesettings and are only reachable through the proxy.autoSleep.mode: Hibernateis not supported for managed servers.
- Paper-based servers with forwarding (all Paper, Pufferfish, Purpur and Folia servers managed by a
Network) get aconfig/paper-global.ymlmanaged by Kobblestone, which replaces the server's file on every start. Other Paper settings in that file fall back to their defaults; changes to it on the server's volume are lost. - The
NetworkPolicyofServers allows RCON from the operator's namespace, which the operator reads from itsPOD_NAMESPACEenvironment variable (set by the manifest and the Helm chart). Without it,Commands andCommandGroups cannot reach servers in clusters that enforceNetworkPolicys. - The proxy now always uses Velocity's modern forwarding (
player-info-forwarding-mode = "modern"). Unmanaged servers have to be configured with the network's forwarding secret (keyforwarding.secretin the network'sSecret), or with the newServerfieldspec.forwarding.
Changes by Kind
Feature
Networks manage their servers: each entry ofserversis aServercreated and kept compatible by the network (forwarding with the network's secret, offline mode, only reachable through the proxy). Shared settings go intoserverTemplate, per-server settings intoservers[].spec, which is merged onto the template (objects field by field, other values replace the template's). Manual changes to managedServers are reverted.- Existing
Servers can join aNetworkby naming them inservers[].serverName, keeping their data. A server that would lose itsstorageby joining is rejected instead. serverDeletionPolicydecides what happens to managedServers that are removed fromserversor whoseNetworkis deleted:Retain(default) keeps them with their data as standalone servers,Deletedeletes them.- The proxy of a
Networkis restarted when its configuration changes, so changes ofservers(added, removed, renamed or reordered servers, hostnames,try) andproxy.configtake effect. Players connected to the proxy are disconnected. Servers that do not exist (yet) are part of the configuration as well, so their creation does not restart the proxy. servers[].tryexcludes a server from the servers players join first; it stays reachable via/serverand its forced host.Networks report the readiness of the proxy (status.proxyReadyReplicasofstatus.proxyReplicas,Proxycolumn) and of their servers (status.readyServersofstatus.serverCount,Serverscolumn), each server's phase instatus.servers, and problems with server entries instatus.messageand as warning events. The proxy has a readiness probe, so it only counts as ready once it accepts connections.- New
Serverfieldspec.forwarding: configures a server to accept players forwarded by a Velocity proxy. Supported for Paper, Pufferfish, Purpur and Folia (built in) and for Fabric and Quilt (installs FabricProxy-Lite and Fabric API from Modrinth). Managed servers of aNetworkget it automatically.
Bug or Regression
- Fix Velocity migrating the generated
velocity.tomlon every start and warning about a deprecated configuration version: the config now setsconfig-version(2.7), unlessproxy.configcontains one. - Fix
Commands andCommandGroups not reaching servers in clusters that enforceNetworkPolicys: the server'sNetworkPolicyonly allowed RCON fromBackups. It now also allows RCON from the operator's namespace. - Fix the server's
NetworkPolicyblocking Minecraft and RCON traffic whenservice.portorrcon.portwas changed: it used theseServiceports instead of the ports in thePod. - Fix
Networks not using player information forwarding: the generatedvelocity.tomldid not setplayer-info-forwarding-mode, so the forwarding secret was not used unless it was set inspec.proxy.config.
v0.2.1
Changes by Kind
Bug or Regression
- Fix
Bots whosespec.pod.volumescontain a volume namedconfig,scripts,dataorsessionfailing to deploy with a duplicate volume error. The volumes Kobblestone adds to the botPodare now namedkobblestone-config,kobblestone-scripts,kobblestone-dataandkobblestone-session, which rolls out thePods of existingBots once. Bots now report invalidspec.podsettings instatus.messageand as a warning event instead of failing to reconcile: volume names starting with the reserved prefixkobblestone-, duplicate volume names, and volume mounts on paths managed by Kobblestone (/dataand the configuration, script and session directories). Mount additional volumes below/datainstead, e.g. at/data/files.- Fix
Bots not being able to write to their additional volumes (e.g. aPersistentVolumeClaimmounted below/data), because the bot container runs as a non-root user. BotPods now setfsGroupto the group of that user. - Auth
Jobs ofAccounts and botPods no longer reference the image pullSecretdockerconfig, which does not exist in most clusters.
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,Restore...
v0.1.0
This is the first public release of Kobblestone. Expect heavy bug-fixing, breaking-changes and new features to come.
Have fun.
PS: Welcome into world, Kobblestone!
Full Changelog: https://github.com/kobblestoneio/kobblestone/commits/v0.1.0