k3sm apache-2.0 (DCO)

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.

Read in Order#

  1. Quickstart brings up one node and runs your first Pod in a few minutes.
  2. Installation covers what k3sm install does, the one-time admin step, and the _k3sm posture.
  3. Concepts explains how k3sm maps Kubernetes onto native Darwin processes.
  4. Cluster access walks through getting a kubeconfig and talking to the cluster.
  5. Supported workloads lists the OCI images k3sm runs, what it refuses, and the path from a Dockerfile to a running Pod.
  6. Images is the reference for both workload conventions, k3sm build, image load/import/push, and every deliberate difference from the docker verb of the same name.
  7. Node-local registry covers the loopback OCI registry, where you push a locally built image and pull it back through the ordinary Kubernetes image path.
  8. Storage covers local-path PVs, node affinity, and what is and isn’t supported.
  9. Version support names the Kubernetes version k3sm tracks and shows how to read the live pin.
  10. Upgrades walks through upgrading a node or cluster and the launchd restart model.
  11. Certificates covers the two CAs, k3sm certificate rotate, and what it does not do.
  12. Backup and restore covers the kine/SQLite datastore, with k3sm snapshot save/restore, the automatic pre-migration copy, and the restore drill.
  13. Multi-node clusters covers joining agents, the mesh, and its EXPERIMENTAL status.
  14. High availability covers the HA control plane and its EXPERIMENTAL status.
  15. Linux images describes the intended isolation boundary for untrusted workloads; it boots linux/arm64 images per Pod today.
  16. MLX serving walks through serving a model on the Mac’s GPU through an /v1/chat/completions endpoint.
  17. Limitations lists the gaps.
  18. Troubleshooting covers the node’s own daemon logs, common failures, and recovery.
  19. Container logs covers where a Pod’s output is written, kubectl logs and its options, rotation, and how to ship logs off a node.
  20. FAQ gives short answers to the common questions.

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.