Getting started

Installation

Install the Kobblestone operator and its custom resources with Helm.

Requirements

  • A Kubernetes cluster, version 1.29 or later, and kubectl configured to talk to it.
  • Helm 3.8 or later.
  • A default StorageClass, or a StorageClass you can name, if your servers should keep their data. Without storage, a server loses its world whenever its pod is recreated.
  • Optional: Gateway API v1.6.0 or later with TCPRoute support, if you want to expose servers through your Gateways.

Install with Helm

Add the Kobblestone chart repository and install the chart:

Terminal window
helm repo add kobblestone https://kobblestoneio.github.io/charts
helm repo update
helm install kobblestone kobblestone/kobblestone \
--namespace kobblestone-system --create-namespace

The chart is also published as an OCI artifact, so you can install it without adding the repository:

Terminal window
helm install kobblestone oci://ghcr.io/kobblestoneio/charts/kobblestone \
--namespace kobblestone-system --create-namespace

The chart installs:

  • the custom resource definitions in the API group kobblestone.io,
  • the operator Deployment, its ServiceAccount and the cluster-wide RBAC permissions it needs,
  • a Service for the operator’s HTTP endpoint, which serves the auto sleep webhook.

Check that it is running

Terminal window
kubectl -n kobblestone-system get pods
kubectl get crds | grep kobblestone.io

Once the operator pod is ready, it watches all namespaces for Kobblestone resources. Continue with your first server.

Configuration

The defaults work for most clusters. These values are the ones you are most likely to change:

ValueDefaultDescription
replicaCount1Number of operator pods. Only the elected leader works, additional pods are hot standbys.
image.tagthe chart’s app versionOperator version to run. image.digest takes precedence if set.
crds.installtrueInstall and upgrade the CRDs with the release.
crds.keeptrueKeep the CRDs, and with them all Kobblestone resources, when the release is uninstalled.
resources50m CPU / 64Mi requestedResources of the operator pod.

Node selectors, tolerations, affinity, extra environment variables and volumes can be set as well. Run helm show values kobblestone/kobblestone for the full list, and pass your own values with --values my-values.yaml or --set.

Upgrading

Before upgrading, read the upgrade notes of the new release in the changelog: while Kobblestone is in alpha, releases can contain breaking changes that need manual steps, for example letting running backups finish first. Then upgrade the release:

Terminal window
helm repo update
helm upgrade kobblestone kobblestone/kobblestone --namespace kobblestone-system

With crds.install: true, the CRDs are upgraded together with the operator.

Uninstalling

Delete your Kobblestone resources first, so the operator can clean up after them. Some resources use finalizers, for example a Backup with retainPolicy: RequireDelete, and get stuck in deletion when the operator is already gone. Then remove the release:

Terminal window
helm uninstall kobblestone --namespace kobblestone-system

By default the CRDs stay in the cluster (crds.keep: true), so an accidental uninstall doesn’t take your servers with it. To remove Kobblestone completely, delete the CRDs afterwards:

Terminal window
kubectl get crds -o name | grep kobblestone.io | xargs kubectl delete

Note: Deleting a Server, or the CRDs, also deletes the servers’ volumes, and with them the worlds. Create a Backup first if you want to keep them.

Without Helm

Each release also comes with a plain manifest that contains everything in one file:

Terminal window
kubectl apply -f https://get.kobblestone.io/v0.3.0/kobblestone.yaml

It installs the same components into the namespace kobblestone-system. To upgrade, apply the manifest of the new release; to uninstall, kubectl delete -f the manifest you installed.