Documentation
k3sm is a macOS-native Kubernetes distribution for Apple Silicon, the macOS/arm64 analog of k3s. Pods run as native Darwin processes (no Linux, no containers, no VM by default). This directory is the front door to the user-facing docs; read them roughly in the journey order below.
These pages describe user-visible behavior. The authoritative product design lives in the design document.
Experimental and Alpha#
Pages and features labeled experimental share one meaning. There is no upgrade-compatibility
promise between releases, so a release may change or drop the feature and its data. Keep datastore
backups (see Backup and restore) and do not use it for production. Alpha
marks an API version (v1alpha1) with the same terms. Where a page also says an alpha is not yet
run on hardware, that is an added caveat: nobody has exercised it on real Macs yet.
Read in Order#
- Quickstart brings up one node and runs your first Pod in a few minutes.
- Installation covers what
k3sm installdoes, the one-time admin step, and the_k3smposture. - Concepts explains how k3sm maps Kubernetes onto native Darwin processes.
- Cluster access walks through getting a kubeconfig and talking to the cluster.
- Supported workloads lists the OCI images k3sm runs, what it refuses, and the path from a Dockerfile to a running Pod.
- Images is the reference for both workload conventions,
k3sm build,image load/import/push, and every deliberate difference from thedockerverb of the same name. - The cluster registry covers the cluster’s one image store,
registry-k3sm:6450, where you push a locally built image and pull it back through the ordinary Kubernetes image path. - Storage covers local-path PVs, node affinity, and what is and isn’t supported.
- Version support names the Kubernetes version k3sm tracks and shows how to read the live pin.
- Upgrades walks through upgrading a node or cluster and the launchd restart model.
- Certificates covers the two CAs,
k3sm certificate rotate, and what it does not do. - Backup and restore covers the kine/SQLite datastore, with
k3sm snapshot save/restore, the automatic pre-migration copy, and the restore drill. - Multi-node clusters covers joining agents, the mesh, and its EXPERIMENTAL status.
- High availability covers the HA control plane and its EXPERIMENTAL status.
- Linux images describes the intended isolation boundary for untrusted
workloads; it boots
linux/arm64images per Pod today. - MLX serving walks through serving a model on the Mac’s GPU through an
/v1/chat/completionsendpoint. - A Linux server under the vm RuntimeClass runs a durable-execution
server’s
linux/arm64images in per-Pod micro-VMs and talks to it from a native client. - Interconnects covers a Thunderbolt cable between Macs as an opt-in network for Pods that ask for it, the MLX ranks of a sharded model above all.
- Limitations lists the gaps.
- Conformance profile is the self-assessment of what k3sm targets and why it
is not a CNCF
[Conformance]pass. - Troubleshooting covers the node’s own daemon logs, common failures, and recovery.
- Status JSON is the contract for
k3sm status -o jsonand the cheapk3sm status daemons -o jsonprobe: fields, enums, versioning and exit codes. - Container logs covers where a Pod’s output is written,
kubectl logsand its options, rotation, and how to ship logs off a node. - Stopping and starting covers
k3sm stop,startandrestart, what a stop does to pods and the cluster, and how a stop survives a reboot. - Building images covers
k3sm buildand the in-cluster build engine. - Helm charts covers installing releases with the
HelmChartobject. - FAQ gives short answers to the common questions.
- Privacy lists what the k3sm app’s update check sends and what it still reveals.
Before You Build Anything Real#
k3sm is not a drop-in replacement for a Linux Kubernetes cluster. Workloads must be adapted, and several standard behaviors diverge by design. Read Limitations first; it cites the canonical conformance registers, so nothing there is rosier than the truth.
MLX / Apple-GPU workloads (the MLXModel CRD and the mlx.k3sm.io/gpu extended resource) have
their own page; see MLX quickstart, item 16 above. The rest of these pages
describe the general workload path.
Quickstart
Bring up a single-node k3sm cluster on your Mac and run your first native Pod. This is the fastest path; Install explains what happens underneath. Requirements: Apple Silicon …
Installation
How k3sm installs, and why it needs admin rights only once. One-Time Admin Step# k3sm runs without per-command sudo. A single privileged install creates the accounts and daemons …
Cluster Access
Talking to a k3sm cluster with kubectl. Bundled Path# k3sm ships a kubectl passthrough that already knows how to reach the cluster: k3sm kubectl get nodes k3sm kubectl get pods …
Concepts
How k3sm maps Kubernetes onto macOS. The full design is in the design document; this is the user-facing mental model. Pods Are Native Darwin Processes# On the default path, k3sm …
Supported Workloads
k3sm runs OCI images two ways, and you pick per Pod: darwin/arm64 images run as native Mac processes. This is the default and the fastest path, with no VM, no kernel to boot, and …
Helm Charts
k3sm installs Helm charts the way k3s does. You describe a release with a HelmChart object, and the server keeps it installed by running helm in a Job. Delete the object and the …
Images
k3sm runs OCI images. It pulls them from registries, verifies their digests, unpacks their layers and honours their config. What it does not run is a Linux image: a k3sm Pod is a …
Cluster Registry
Every k3sm server runs a small OCI registry, the cluster’s one image store. You push a locally built image to it and a Pod pulls it back through the ordinary Kubernetes image …
Building Images
k3sm build builds any Dockerfile: k3sm build -t myapp:dev .The image is recorded in the cluster registry as registry-k3sm:6450/myapp:dev, ready for a Pod on any node to name it, …
Storage
Persistent storage in k3sm uses a local-path provisioner with node affinity. Storage Model# ConfigMaps and Secrets are served by the apiserver and materialized into the Pod by the …
Multi-Node Clusters
Joining more than one Mac into a single k3sm cluster. Status: EXPERIMENTAL (what that means: Experimental and alpha). See Limitations. Mesh Model# One Mac runs the control plane …
High Availability
Running the k3sm control plane so a single Mac is not a single point of failure. Status: EXPERIMENTAL (what that means: Experimental and alpha). k3sm install --cluster-init forms …
Linux Images
k3sm runs Pods as native Darwin processes under a single _k3sm user, so there is no per-pod uid isolation, and same-node Pods share one OS trust domain. The vm RuntimeClass is the …
MLX Serving
Serve a language model on your Mac’s GPU and call it from any client of the common /v1/chat/completions HTTP API. k3sm models the workload as an MLXModel object. You declare …
Interconnects
An interconnect is a Thunderbolt cable between two Macs in the cluster, used as an extra network beside the mesh. Control-plane traffic, Services, DNS and ordinary Pod traffic stay …
Upgrades
Moving a k3sm node or cluster to a new release. Checking for an Update# k3sm update check # or: k3sm update check -o jsonk3sm update check finds the latest release the way the …
Stopping and Starting k3sm
k3sm stop shuts k3sm down on a Mac completely and keeps it down across reboots. k3sm start brings it back. Use them for a maintenance window, to free the Mac for other work, or to …
Backup and Restore
k3sm keeps cluster state in an embedded kine datastore over SQLite (WAL), or, on an HA server, in an embedded etcd member. Backing it up and restoring it is how you protect and …
Certificates
k3sm mints its own PKI at first boot and re-issues the control plane’s leaf certificates on every boot. k3sm certificate rotate is the supported way to force that re-issue …
Privacy
What k3sm.app sends when it checks for an update, and what that still tells the server it asks. The App’s Update Check# A release build of k3sm.app checks for a newer app …
Version Support
Which Kubernetes version k3sm tracks, and how to read the live pin so this page cannot silently drift. Read the Live Pin# The authoritative version is what the binary reports and …
Conformance
⚠️ This is NOT a CNCF Certified-Kubernetes badge# k3sm has not run the upstream [Conformance] suite, and by design cannot pass it. That suite (CNCF Certified Kubernetes) assumes …
Limitations
k3sm runs Kubernetes Pods as native Darwin processes on Apple Silicon. That design buys a zero-Linux, zero-VM developer experience, but it also means several standard Kubernetes …
Troubleshooting
When a k3sm cluster does not behave. Start with k3sm status, then the common failure modes below. Start with k3sm status# k3sm status is one screen covering the two LaunchDaemons, …
Status JSON
k3sm status has two machine-readable shapes, and k3sm alerts a third cut from the first. All are versioned, and this page is their contract: what each field means, which values an …
Container Logs
kubectl logs on a k3sm node reads the same files, in the same format, with the same options and the same rotation policy a kubelet uses. If you already know where container logs …
Example: A Durable-Execution Server
The temporalio/temporal image (project site) is an open-source durable-execution service: a gRPC frontend, a history and matching engine, a worker service and a Web UI over a SQL …
FAQ
Is k3sm a Certified Kubernetes Distribution?# No. k3sm cannot pass the CNCF [Conformance] suite, which assumes Linux containers, cgroups, CNI, and network namespaces. k3sm has none …