Skip to content

v0.2.2

Choose a tag to compare

@kitsumiko kitsumiko released this 28 Oct 17:44
· 330 commits to main since this release
098585b

The cluster has one image store, updates itself from the server, and stops and starts as a whole. This release also brings k3sm status top, metrics-server, LoadBalancer hosting on every node, and a LAN switch for the listeners.

This is the first published v0.2 release. v0.2.0 and v0.2.1 were tagged but never published: Go announced two advisories in its HTML package (GO-2026-6860, GO-2026-6866) while v0.2.0 was being signed, and release signing could not yet ship the control-plane version marker when v0.2.1 was. v0.2.2 is v0.2.0 with both fixes, so everything below ships in it.

Security

  • HTML parser fix. The control-plane binaries and the bundled helm are built against golang.org/x/net v0.62.0, which fixes GO-2026-6860 and GO-2026-6866 in the HTML parser and renderer.

Breaking

  • Upgrade the server before the agents. An agent on this release needs the datapath identity certificate, which only a server on this release issues; an agent upgraded before its server logs that and retries every half minute until the server is upgraded. Later releases roll workers first again, as k3sm update apply does.
  • k3sm status -o json is versioned. The report carries schemaVersion: 1, and the keys under version are lowerCamel. k3sm doctor --json carries the same field. See status JSON.
  • HA servers move to a request-header CA for the aggregation layer. The join bundle a server hands to another server changes shape: upgrade the server installed with --cluster-init first, then each joined server.
  • admissionregistration.k8s.io/v1beta1 is no longer served. The whole group returns 404 (MutatingAdmissionPolicy, ValidatingAdmissionPolicy and their bindings); the v1 group is unchanged.

Added

  • One image store. The server's registry, registry-k3sm:6450, serves HTTPS with a cluster-CA certificate and is the cluster's single image store. k3sm build, k3sm image load and import record there, each node keeps a pull cache, and a Pod can push with a projected ServiceAccount token in a namespace labelled with its own name. See the registry.
  • Managed updates. k3sm update check lists every node against the latest release; k3sm update apply rolls the cluster one node at a time, workers first, with status, cancel and abort. The server signs every update and a node installs only what the server signed.
  • sudo k3sm stop, start and restart. A stop takes the node down fully, Pods included, and holds across a reboot and across sudo k3sm install until you start it again.
  • k3sm status top. A live view of each node's CPU and memory against allocatable, then the pods sorted by CPU and memory.
  • kubectl top works. metrics-server ships as an add-on and every node reports host-wide CPU and memory, on a single-node install too.
  • LoadBalancer Services are hosted on every node, picked by the same node labels k3s uses, and --nodeport-addresses binds NodePorts to the networks you name.
  • sudo k3sm network lan on|off. One switch decides whether the NodePort, LoadBalancer and ingress listeners answer on the networks this Mac is attached to. New installs start with it off.
  • k3sm build ls, cancel, rm, logs and prune, with every build recorded under ~/.k3sm/builds.
  • Scheduled etcd snapshots and restore on HA servers, and k3sm snapshot save --compress in the format k3s uses.
  • The macOS app installs and updates through k3sm install --from-staging, a root-owned staging folder signed by one Developer ID, and opens with its window hidden after an install or start.
  • k3sm status gains dns, services, heartbeat and kubeconfig rows, reads what your account can without sudo, reports joined workers and the join target in JSON, and streams NDJSON with --watch -o json. Nodes report their images in status.images, servers carry the control-plane role label, and vm Pods keep running across a node daemon restart.

Experimental

  • Thunderbolt interconnect (alpha). k3sm interconnect enable arms a Thunderbolt cable between Macs as an opt-in network for Pods and sharded MLXModel placement.

Changed

  • The control plane runs Kubernetes v1.37.1. kine v0.17.2, etcd, zot v2.1.22 and buildx v0.38.0 ship in the release payload, so a node no longer builds them at boot.
  • A single-node server's apiserver certificate is signed by the cluster CA; the admin kubeconfig pins that CA and never skips verification.
  • MLXModel KV sizing follows the model's own geometry, and workers enforce NetworkPolicy.

Security

  • k3sm registry token caps --duration at 24 hours. The cluster sets no service-account token maximum, so the command enforces the ceiling itself beside the 10 minute floor, and a longer lifetime is refused before any token is requested.
  • The release binaries are built with Go 1.27.3 (GO-2026-6809).
  • Each node's datapath authenticates as its own identity, the kubelet API binds the node's own address only, and control-plane downloads, helm and the registry are verified against pinned digests and never re-signed.

Fixed

  • A pinned MLXModel answers to its spec.model name. With spec.revision set, the engine served the snapshot path as the only model and refused the request the quickstart shows. The engine is now told to serve the model under spec.model, pinned or not.
    Among the fixes: the single-node datastore's write-ahead log is checkpointed again (it could grow by gigabytes a day), cluster DNS recovers from a dead UDP socket and a failed TCP listener, a worker on lossy Wi-Fi keeps posting its status, a server killed with kill -9 starts again by itself, DaemonSets schedule without a hand-added toleration, and k3sm build works from an ordinary account on a root install. The MLX serving image keeps a rotating KV cache's attention sinks after a long prompt, refuses an over-length request on /v1/messages and /v1/responses, and lowers --max-kv-size for a model whose cache costs more per token than it was sized for (thanks to @robertcprice). The full list is in CHANGELOG.md.

Upgrade notes

  • Upgrade with sudo k3sm install, never by replacing the binary alone. On a multi-node cluster, upgrade the server first and then the agents.
  • Before upgrading a single-node server, back up its PKI directories: sudo cp -a /var/lib/k3sm/server/tls /var/lib/k3sm/server/apiserver-certs <backup-dir>.
  • Every namespace's kube-root-ca.crt becomes the cluster CA, so a Pod that read its ca.crt at start needs a restart. Copy every kubeconfig you took off the node again after the upgrade.
  • A node stopped with k3sm stop stays stopped across an upgrade; pass --start to start it.