Repository navigation
v0.2.2
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 applydoes. k3sm status -o jsonis versioned. The report carriesschemaVersion: 1, and the keys underversionare lowerCamel.k3sm doctor --jsoncarries 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-initfirst, then each joined server. admissionregistration.k8s.io/v1beta1is 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 loadandimportrecord 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 checklists every node against the latest release;k3sm update applyrolls the cluster one node at a time, workers first, withstatus,cancelandabort. The server signs every update and a node installs only what the server signed. sudo k3sm stop,startandrestart. A stop takes the node down fully, Pods included, and holds across a reboot and acrosssudo k3sm installuntil 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 topworks. 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-addressesbinds 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,logsandprune, with every build recorded under~/.k3sm/builds.- Scheduled etcd snapshots and restore on HA servers, and
k3sm snapshot save --compressin 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 statusgainsdns,services,heartbeatandkubeconfigrows, reads what your account can withoutsudo, reports joined workers and the join target in JSON, and streams NDJSON with--watch -o json. Nodes report their images instatus.images, servers carry the control-plane role label, andvmPods keep running across a node daemon restart.
Experimental
- Thunderbolt interconnect (alpha).
k3sm interconnect enablearms a Thunderbolt cable between Macs as an opt-in network for Pods and shardedMLXModelplacement.
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.
MLXModelKV sizing follows the model's own geometry, and workers enforce NetworkPolicy.
Security
k3sm registry tokencaps--durationat 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
MLXModelanswers to itsspec.modelname. Withspec.revisionset, 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 underspec.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 withkill -9starts again by itself, DaemonSets schedule without a hand-added toleration, andk3sm buildworks 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/messagesand/v1/responses, and lowers--max-kv-sizefor 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.crtbecomes the cluster CA, so a Pod that read itsca.crtat start needs a restart. Copy every kubeconfig you took off the node again after the upgrade. - A node stopped with
k3sm stopstays stopped across an upgrade; pass--startto start it.