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 that everything after it runs under:
sudo k3sm installThe install script cannot pass extra flags, so if you want the data root on its own size-capped
APFS volume, run sudo k3sm install --data-volume after the script, or in place of it if you
already have the binary. See The Data Volume.
That step:
- creates the dedicated unprivileged
_k3smuser, - installs the minimal root networking helper (
k3sm-netd, theio.k3sm.netdLaunchDaemon) and the_k3smLaunchDaemon that runs the node:io.k3sm.serveron the control-plane Mac, orio.k3sm.agenton a worker installed with--agent(RunAtLoad/KeepAlive, boot-surviving), - with
--data-volume, installs the rootio.k3sm.datavolLaunchDaemon, which mounts the data volume at boot, - links
/usr/local/bin/k3smsok3smis a command your shell can find, - writes an admin kubeconfig to the invoking user’s home directory.
After install, k3sm kubectl … and Pod lifecycle run as you / _k3sm with no sudo.
The privilege model documents the full trust model. It is the same
privileged-helper pattern the desktop container tools and Linux VM managers use, applied to k3sm,
and one residual limitation remains (no per-pod uid isolation).
What Gets Installed Where#
- The
k3smbinary in/Library/k3sm(root:wheel), whichever channel delivered it (with the script, pinK3SM_INSTALL_VERSIONto reinstall a prior release, since the assets stay on GitHub Releases). - The launcher, a symlink
/usr/local/bin/k3sm→/Library/k3sm/k3sm./usr/local/binis the first entry in/etc/paths, so every terminal opened after the install findsk3smwith no profile edit; a terminal that was already open may needhash -ror simply a new window. Because it is a symlink rather than a copy, the daemons and your shell always run the same binary. If something other than a symlink already sits at that path, install refuses to replace it and says so. The directory holding the launcher must be owned byrootand not writable by anyone else, because root’s PATH searches it: anyone who can write there could leave ak3smof their own for a latersudo k3sm …to run. A Mac whose Homebrew uses the x86_64/usr/localprefix usually has a/usr/local/binowned by the user who installed Homebrew, so install stops before writing anything and prints the exactchown/chmodto run (sudo chown root:wheel /usr/local/bin && sudo chmod 755 /usr/local/bin). - LaunchDaemons under the
io.k3sm.*reverse-DNS labels. The control plane’s plist is0600(root-only), since the arguments it carries can include a credential in a flag you added. - The cluster admin token in
/var/lib/k3sm/server/token, mode0600and owned by the_k3smservice account. The daemon is told where its token is, never what it is, so the token does not appear in the plist, inps, or inlaunchctl print.k3sm uninstallremoves it. Because that plist is0600,k3sm statusrun withoutsudoreports the server’s launchd arguments row as unreadable as this user, which never changes the verdict, andsudo k3sm statusshows it. - The kine/SQLite datastore under the server work directory (see Backup & restore).
- An empty auto-deploy manifest directory,
/var/lib/k3sm/manifests, owned byroot:wheel, mode0755(see below).
Auto-Deploy Manifests#
Like k3s’s server/manifests, the server applies every manifest you drop into
/var/lib/k3sm/manifests, on start and whenever the directory changes (with a sweep every
60 seconds as a backstop). Unlike k3s, the directory sits outside the server’s work directory and
belongs to root, because every pod on a k3sm node runs as the same service user and could otherwise
write into it.
- Ownership. The directory and every file in it must be owned by
rootand must not be writable by group or others. Anything else is skipped with a log line. Write files withsudo, for examplesudo install -m 0644 addon.yaml /var/lib/k3sm/manifests/. - What is read. Files ending in
.yaml,.ymlor.json. A name starting with.or_is ignored, which is how you park a file without deleting it. Symlinks are ignored. Several documents in one file are fine, and akind: Listor a top-level JSON array is applied item by item (the List’s own metadata is ignored). - Apply-only. Objects are applied with server-side apply under the field manager
k3sm-manifest-dir, never forced. When a field in the file is owned by another manager (for example, one you changed withkubectl edit), that object is not applied and the server records a Warning Event with reasonManifestFieldConflicton it, naming the file and the other manager. The file is not retried until you change it. Nothing is ever deleted: removing a file, or removing an object from a file, leaves the object in the cluster until you delete it withkubectl. - Refused kinds. RBAC objects (
rbac.authorization.k8s.io: Roles, ClusterRoles, bindings), admission objects (admissionregistration.k8s.io: webhooks, admission policies), Secrets and ServiceAccounts are refused and logged; the rest of the file still applies. Create Secrets and ServiceAccounts withkubectl. The server applies manifests as thekube-system/k3sm-manifestsServiceAccount, which may only create and patch common workload and configuration kinds (Deployments, DaemonSets, StatefulSets, Jobs, CronJobs, Pods, Services, ConfigMaps, PVCs, Ingresses, NetworkPolicies, StorageClasses, HPAs, PDBs, MLXModels), plus HelmCharts and HelmChartConfigs through a separate ClusterRole (see Helm charts). A Pod may run as any existing ServiceAccount in its namespace, the standard ceiling for anything that can create workloads. It cannot create namespaces, so create one first withkubectl. Nothing is ever deleted, so remove a mistaken object withkubectl. - Change tracking. Every applied object carries the annotation
manifests.k3sm.io/sha256, the checksum of the file it came from. An unchanged file is not applied again. - Adapt stock manifests. A manifest written for Linux has no
kubernetes.io/os: darwinnodeSelector and no toleration for thek3sm.io/providertaint. It still applies, but its pods are refused or never scheduled. The server records a Warning Event with reasonManifestNeedsDarwinSchedulingon such an object, naming both fields; add them to the pod template.
k3sm uninstall keeps the directory and its contents with the rest of your cluster data.
Install Channels#
k3sm ships through two channels:
The install script:
curl -fsSL https://k3sm.io/install.sh | shThe script preflights (Apple silicon, macOS 26+), downloads the release tarball and its checksums from GitHub Releases, verifies the sha256, prints exactly what it is about to do, and then runs
sudo k3sm install. The verification checks same-origin integrity, meaning the tarball matches the checksums published beside it. The script does not check publisher identity, but the programs in the tarball are Developer ID signed and notarized, andcodesign --verify --strict /Library/k3sm/k3smchecks that after install. Environment variables set the options.K3SM_INSTALL_VERSIONpins a release, and it is also the repair path, since an unpinned re-run jumps to latest. The variable must reachsh, so it goes after the pipe:curl -fsSL https://k3sm.io/install.sh | K3SM_INSTALL_VERSION=v0.2.3 sh(v0.2.3 is the release you are on today, so a repair pins the newest tag and never an older one; the releases page lists every version you can pin).K3SM_INSTALL_DOWNLOAD_ONLY=1downloads and verifies into the current directory without ever runningsudo, so you can inspect first. Re-running the one-liner upgrades in place, and both daemons restart briefly (see Upgrade).The k3sm app, a signed, notarized download from k3sm.io (see Installing From k3sm.app).
Both channels manage the same /Library/k3sm. Run
sudo k3sm install after switching from one to the other so the daemons run the newly delivered binary, or run
sudo k3sm uninstall first for a clean cutover.
Installing From k3sm.app#
k3sm.app is built from its own public repository, k3sm-io/app,
a separate SwiftPM package. The command-line install needs nothing from the app. The app runs the
same k3sm install with the same defaults as install.sh, adding --from-staging and --user
(and, to join a cluster, --agent, --server and --token-file), and it installs the release it carries, which can be older than the newest release the
script picks.
When the app is installed in /Applications, k3sm install, k3sm start and
k3sm restart --start open it for the user logged in at the screen once the node is up, with its
window hidden, so its menu bar icon appears at once. They skip it when nobody is logged in at the
screen, when it already runs, or when its signature does not match the running k3sm.
The k3sm app installs, updates and uninstalls with the same /Library/k3sm. Each of those
actions asks for an administrator password once. That step copies the app’s bundled files into a
root-owned staging folder, checks the copy, and then runs the install from that copy. It never runs k3sm
from its own bundle as root: it copies the bundle into a new directory under
/Library/k3sm.staging, checks the copy’s signature, and runs
k3sm install --from-staging <dir> from that copy. The install refuses to run unless:
- the directory sits directly inside
/Library/k3sm.staging, both are owned byroot:wheelwith mode0700, and no part of the path is a symlink; - every file in the directory is owned by
root, writable by nobody else, and none is a symlink, a special file, or setuid or setgid; - the running
k3smand every file it installs come from that directory; - a
--token-filesits directly inside the directory, owned byrootwith mode600and one link (it is removed as soon as it is read); - the version is a release version no older than the installed one;
- the programs in the directory are signed the way the installed
k3smallows:- a first install needs every program signed with a Developer ID Application certificate from one team;
- an install signed by a Developer ID team takes only programs signed by that same team, never ad-hoc signed ones;
- an ad-hoc signed install takes programs signed by one Developer ID team, or programs that are all ad-hoc signed.
Pass --allow-downgrade to install an older version on purpose (or over an install whose version
cannot be read). Pass --require-team-signature to refuse any program without a Developer ID team
signature, whatever the installed k3sm is signed with.
Without --agent, --server-join or --token-file, k3sm install --from-staging <dir> updates
whatever is installed, in place. It reads the role from the installed daemon and keeps every
argument it was configured with. A worker keeps the server it joined and rejoins with its stored
node credential. A server rewrites the admin kubeconfig for --user, or without it for the owner of
the kubeconfig the last install wrote. With nothing installed and no --user, it refuses: there is
nothing to update in place. A plain sudo k3sm install makes none of these checks and is unchanged.
The app also updates itself and the cluster. It checks for a newer k3sm.app, and it can move the
cluster to the k3sm release it carries, bound to that release’s checksum with --pin-sha256.
Upgrade describes both beside the command-line path, which is
unchanged, and Privacy lists what the check sends.
To remove an install made from the app, run sudo k3sm uninstall, or use Uninstall k3sm… in the
app’s Settings > Advanced, which keeps the cluster’s data unless you tick Also delete k3sm’s
data. Dragging the app to the Trash does not remove k3sm: the cluster keeps running.
Developer mode#
Developer mode is for a build from source. It turns the signature checks off on this Mac, so a build you made yourself can be installed, and so a developer build of k3sm.app can install, update, stop and start it.
Contributors. Run
sudo <tree>/k3sm install --developer-mode onwith the binary you built. An ad-hoc signed build may then replace a team-signed one, and a developer build of the app can install, update, stop and start that k3sm. The downgrade rule still applies: pass--allow-downgradeto install an older version on purpose.Turned on by mistake. Run
sudo <tree>/k3sm install --developer-mode offfrom any tree, or install a Developer ID signed k3sm, which turns developer mode off:- a plain
sudo k3sm installturns it off when thek3smdoing the install carries a Developer ID Application signature of any team, not only the team that signs k3sm releases. The team is not compared with the installed one, and the other programs the install lays down are not checked. The log line names the Developer ID team that signed thek3smdoing the install, not a check against the release team. The signature is read from that program’s path, not from the bytes later copied into the install root, so a swap of the program between the check and the copy is not seen; a wrong reading can only turn developer mode off, or leave it on with the reason logged. This check only turns developer mode off, which turns the signature checks back on. A plain install turns it off only when the marker exists, valid or not (an invalid marker is removed too). An ad-hoc signed build from source, or one signed for Apple Development, leaves it on, because neither is a Developer ID signature; - an update through k3sm.app turns it off only when every program in the update carries a Developer ID Application signature of one team, and that team is the installed k3sm’s when the installed k3sm has one. That is the same team the signature checks require of an update when the mode is off. The log line names the Developer ID team every staged program shares.
An install that leaves the mode on says why.
- a plain
Auditing a Mac. The record is the marker
/Library/k3sm.developer-mode: a root-owned file, and its presence is the whole record.k3sm statusshows adeveloper-moderow at severitywarnwhile it is there, with the stateonfor a valid marker andinvalidfor anything else at that path (a symlink, a file that is not root-owned, a file others can write, or one with an ACL), or for a marker under a/or/Librarythat is not a root-owned real directory that neither group nor others can write, with no ACL. An invalid marker is ignored and the checks stay on. The statusverdictstaysokwhile the mode is on, and only thedeveloper-moderow warns, so automation that audits a Mac reads that row rather than the verdict. A release build of the app never uses the mode.k3sm uninstallremoves the marker.How long it lasts. The marker sits outside the install root, so it survives reboots and ordinary updates.
--developer-mode onwrites it before anything else the install changes, and an install that fails after that leaves it in place, so the checks stay off.Given up while it is on. The signature of the k3sm that runs as root is not compared with the installed one. A corrupt copy is still refused, as are the staging directory checks and
--require-team-signature.Without the flag, the mode stays as it is, except for the signed installs described above.
--developer-modeis accepted on every install shape. If the marker changes while an install is running, the install refuses and asks to be run again.
See Status JSON for the row.
Secrets Encryption at Rest#
Secrets are stored unencrypted in the datastore by default. To encrypt them at rest, ask for it on the install that creates the cluster:
sudo k3sm install --secrets-encryptionThe install generates a random 32-byte key on this Mac and writes two files before the control
plane first starts, both owned by _k3sm with mode 0600 in a 0700 directory:
/var/lib/k3sm/server/cred/encryption-config.yaml, the API server’s encryption configuration, which holds the key,/var/lib/k3sm/server/cred/encryption-config.sha256, a fingerprint of that key.
The API server then encrypts every Secret it writes with the secretbox provider
(XSalsa20-Poly1305). k3s offers secretbox too; its default is aescbc, which the Kubernetes
documentation no longer recommends. The configuration lists no plaintext (identity) provider, so
the API server does not read or write unencrypted Secrets. Other resources, such as ConfigMaps, are
not encrypted.
Check the state at any time:
sudo k3sm secrets-encrypt statusIt prints enabled, disabled, or refused with the reason, the provider, the configuration
path and its mode. It never prints the key. It exits non-zero when the files are in a state that
stops the control plane from starting.
Back up the key with the datastore. Copy /var/lib/k3sm/server/cred every time you back up
state.db or take a snapshot, and keep the two copies together.
- Losing the key makes every Secret unreadable, including node passwords and bootstrap tokens.
- A snapshot does not contain the key.
- Restoring a snapshot taken under another key, or before encryption was enabled, leaves Secrets unreadable.
There is no way back. An older k3sm, or this one with the files removed, cannot read the encrypted Secrets. This release has no key rotation and no command to decrypt the datastore.
Refusals. The install stops, before it changes anything, when:
- this data root already holds a datastore (an existing cluster cannot be switched over in this release; encryption is for a fresh install only),
- the server’s carried arguments include
--cluster-initor--server-join(every server would need the same key, and k3sm does not distribute one), - the install is a worker (
--agent).
A later sudo k3sm install without the option keeps the key and the encryption. Passing the
option again once the cluster has started is refused. To enable encryption on a cluster that has
never held workloads, remove the data root and reinstall with the option. The .bak copies k3sm
keeps beside state.db hold encrypted Secrets and are useless without the key. The control
plane refuses to start, and stays parked until the files are fixed, when the configuration is
present without its fingerprint, when the fingerprint is present without the configuration, or
when the two do not match. Restore both files from the backup taken with state.db. k3sm uninstall keeps both files with the rest of your cluster data.
Network Exposure#
Every listener a node opens, and the addresses it binds:
| Listener | Port | Binds |
|---|---|---|
| kubelet API (logs, exec, metrics) | 10250 (--kubelet-port on a server) | the node’s own address only: its mesh address once joined, its pod-range address on a single node, 127.0.0.1 on a single node under --network none |
| NodePort Services | 30000-32767 | follows LAN access: every interface (or the --nodeport-addresses set) when on, 127.0.0.1 and the node’s own address when off |
| LoadBalancer Services | each Service’s port | follows LAN access: every interface when on, 127.0.0.1 and the node’s own address when off |
| Ingress host (server) | 80, 443 (--ingress-http-port, --ingress-https-port) | follows LAN access: every interface when on, the node’s own address when off |
| wireguard mesh | 51820/udp | every interface; it answers only peers holding a cluster key |
| apiserver (server) | 6444 (--api-port) | 127.0.0.1 on a single server; the mesh address only on a server with --mesh-ip |
worker join (server with --mesh-ip) | 9345 | every interface, because a joining worker has no mesh yet; every request needs the cluster join token |
| embedded etcd peer (HA servers) | --etcd-peer-port | the --etcd-peer-ip address you name; peers need a peer certificate |
image registry (on by default; --registry-port, 0 turns it off) | 6450, or the chosen port | 127.0.0.1, plus an HTTPS relay on the mesh address and the vm NAT gateway |
| cluster DNS and ClusterIP Services | Service ports | their virtual IPs, aliased on lo0 |
| datastore, scheduler, controller-manager (server) | their own ports | 127.0.0.1 |
The kubelet API binds exactly the address the node registers as its InternalIP, never every
interface. If that address is missing when the node starts (a joined worker under --network none, for example), the node refuses to start and names the address. The standalone k3sm node
command is the exception: its --listen address is the operator’s choice and may still be the
wildcard.
LAN access#
One switch decides whether the workload listeners (NodePort, LoadBalancer and the ingress host) answer on the networks this Mac is attached to:
sudo k3sm network lan off # only this Mac and the cluster mesh
sudo k3sm network lan on # every network this Mac is on
k3sm network lan status # the setting, what it covers, what it does notWith LAN access off, those listeners bind 127.0.0.1 and the node’s own address (its mesh address
once joined, its pod-range address on a single node), so other nodes reach them over the mesh and
nothing on your Wi-Fi or Ethernet does. With it on, they bind every interface.
- New installs start with LAN access off. An existing install keeps LAN access on across an upgrade,
so nothing it serves stops answering.
sudo k3sm install --lan onor--lan offsets it at install time. - The change applies live, without restarting pods (a restart of the daemon itself keeps pods running,
vmpods included, and only a binary upgrade recreates them; see what survives a restart): the node daemon binds the new addresses first and only then closes the old ones. Connections already open finish; new connections from the LAN are refused. The command then checks the node daemon’s listening sockets itself (withlsof, as root) rather than taking the daemon’s word for it. If any listener cannot move, or the sockets do not match, the previous setting is restored and checked the same way, and the command says why. If even the restore fails, it says so and exits4. If the node daemon does not apply it live, the command restarts the daemon in place instead (pods keep running,vmpods included, and a binary upgrade recreates every pod, see what survives a restart) and says so. k3sm network lan statusandk3sm statusshow the recorded setting and, run as root, the state the node daemon reports serving, and say when the two differ. With no setting recorded they say that LAN access is on because nothing is recorded.- The record must be a regular file owned by root and writable by no one else. Anything else is treated as unusable, and the node daemon serves LAN access off until it is set again.
- On a stopped node the setting is recorded and applies at
sudo k3sm start. - Every LoadBalancer listener below 1024 binds through the root network helper. With LAN access on,
every node serves such a port on every interface, whether or not it is listed. With LAN access
off, it is served on the node’s own address and on
127.0.0.1only when it is in the node’s--lb-privileged-portslist, ak3sm serverandk3sm agentflag recorded with the install arguments that defaults to80,443; an unlisted port is not served until LAN access is back on. The list decides only those node-address binds. The ingress host still serves80and443on the node’s own address, but not on127.0.0.1. - The ingress host’s ports belong to it: a LoadBalancer Service on one of them is not served on any
node while the ingress host declares the port, with LAN access on or off. The default list
therefore serves a LoadBalancer on
80or443only where the ingress host is disabled or moved to other ports. - A listed port’s
127.0.0.1socket is held by the root network helper on the node daemon’s behalf, so any local process can connect to it, the same as to the node’s own address. - A LoadBalancer bound on a port before the node has seen the ingress host’s Service declare it is taken down at the next reconcile, within one resync.
- The helper serves a listed port only on the node’s own address,
127.0.0.1and the addresses of the Mac’seninterfaces, so a node address on a Thunderbolt bridge is not served below 1024. - The switch does not cover the apiserver (loopback, or the mesh address), the wireguard mesh port (it answers only cluster peers) or the worker join port. A new worker joins over the LAN, so the join port stays reachable with LAN access off, and every request to it needs the cluster join token.
- The setting is kept in
/Library/Preferences/io.k3sm.network.json, beside the other install arguments, and survives a reinstall and an uninstall.k3sm statusshows it, andk3sm status -o jsoncarries it asnetwork(see Status JSON).
NodePort addresses#
With LAN access on, NodePorts follow upstream and bind every interface unless
--nodeport-addresses narrows them. With LAN access off, NodePorts bind 127.0.0.1 and the node’s
own address whatever --nodeport-addresses says.
sudo k3sm install --nodeport-addresses local
sudo k3sm install --agent --server <control-plane> --token-file <file> --nodeport-addresses locallocal is loopback (127.0.0.1) plus the node’s own address, the same set LAN access off uses.
The value can also be a comma-separated list of IPv4 CIDRs, the kube-proxy --nodeport-addresses
shape, mixed with local if you like (local,10.0.0.0/8). Each NodePort then binds every matching
address of this Mac, or none of them if any bind fails. See Limitations for the
reserved ports and the other networking caveats.
- The setting is IPv4 only. An IPv6 range is refused.
- It needs the node datapath. A non-empty value beside
--network noneis refused, onk3sm install,k3sm serverandk3sm agentalike. - It is resolved when the daemon starts and again at every LAN access change, against the addresses this Mac has then. A value that matches no address refuses the start. An address that appears later (a new network) is used after the next restart or LAN access change.
- It is recorded with the other install arguments and kept across a reinstall and an uninstall.
Surrounding spaces are ignored.
sudo k3sm install --nodeport-addresses ""(or a value of only spaces) returns to every interface. k3sm serverandk3sm agenttake the same flag directly.
Uninstalling#
sudo k3sm uninstallIt stops and removes the k3sm LaunchDaemons (the data-volume daemon too, when there is one), removes /Library/k3sm, and removes the
/usr/local/bin/k3sm launcher, but only that link, and only while it still points at
/Library/k3sm/k3sm. A file you put there yourself, or a link you re-pointed at something else, is
left exactly as it is. It also flushes the pf anchor an older release loaded for the mesh (k3sm itself
loads no pf rule). Your cluster data, the _k3sm user, and your kubeconfig are kept, so a
reinstall picks up where you left off; to remove those too, see
Remove Everything. The server’s admin token is removed, because a reinstall
mints a new one, and so are the records the node writes for k3sm status (in the server’s work directory
and in /var/lib/k3sm/status/), because they describe a node that no longer runs. The command prints the full list of what it kept. If you
installed a data volume, it stays mounted and declared; the command prints sudo k3sm install --data-volume to reinstall onto it and sudo k3sm datavol delete --yes to remove it for good.
Uninstall also removes the developer-mode marker /Library/k3sm.developer-mode, if there is one (see
Developer mode).
Uninstall also removes /Library/k3sm.staging, the directory the k3sm app copies itself into, and
refuses to run while the app is in the middle of an install.
If an upgrade by an older version of k3sm was interrupted, it can leave a /Library/k3sm.staging
directory behind. Install never uses or removes it; sudo k3sm uninstall (no --purge needed)
clears it, and a reinstall afterwards keeps your cluster data.
Server Flags Across A Reinstall#
Any flag you added to the server daemon yourself, such as --mesh-ip or --registry-port, is
carried into the plist every install renders. Install reads them from the installed daemon, and
records them in /Library/Preferences/io.k3sm.server-args.json, so they survive an uninstall too.
That file is root-owned and root-readable only, because a flag can carry a credential. k3sm status
shows what the installed server is running with, on the server-args row.
--tls-san, the extra names for the apiserver certificate, is recorded
the same way. Passing it on an install replaces the recorded list, and leaving it off keeps that
list. See Multi-node.
The record is written at install time. A flag you edit directly into the daemon’s plist is picked up
by the next sudo k3sm install, and until then it exists only in the plist, so an uninstall before
that install loses it. Running sudo k3sm install after an edit is what makes it durable.
The installed daemon wins while it is there, so a reset means clearing both sources:
sudo k3sm uninstall # removes the daemon and its flags
sudo rm /Library/Preferences/io.k3sm.server-args.json # discards the recorded ones
sudo k3sm install # renders the stock templateThat discards the flags the file lists, and nothing else. Your cluster data is untouched. An
install refuses a carried --datastore-endpoint or --datastore-endpoint-file, because v0.1.6
removed external-datastore HA. The experimental two-server control plane uses embedded etcd
instead; see High availability.
Install warns when it finds neither source on a data root that already holds cluster state, which is what a Mac uninstalled by an older version looks like. The flags are gone on such a Mac, and install says so rather than starting single-node in silence.
Remove Everything#
sudo k3sm uninstall --purge --yesThis runs the uninstall above and then removes what it keeps:
- the cluster data in
/var/lib/k3sm: the datastore, images, and volumes - the data volume, if you installed one, together with its keychain item, its
/etc/fstabline, and/Library/Preferences/io.k3sm.datavol.json - the daemon logs in
/var/log/k3sm - the recorded arguments in
/Library/Preferences/io.k3sm.server-args.jsonorio.k3sm.agent-args.json - the
k3smcontext in your~/.kube/config, and the cluster and user entries only that context used; every other entry in the file is kept - the
_k3smuser, if macOS allows it (see below)
macOS asks a person at the screen to approve deleting a user account, so the purge may not be able
to delete _k3sm by itself. It removes everything else first, then leaves the account disabled
(hidden, no login shell, no home directory) and prints the command that finishes the job: run
sudo dscl . -delete Users/_k3sm in Terminal and click Allow when macOS asks to administer your
computer. A leftover account is harmless, and running the purge again tries the deletion again.
It cannot be undone. Without --yes the command changes nothing and lists what it would delete.
k3s’s k3s-uninstall.sh removes everything with no prompt; k3sm asks for --yes on purpose,
because this deletes a user account and the cluster’s datastore.
The purge learns whose ~/.kube/config to clean from sudo. When there is no sudo environment, name the account with --user <name>; it wins over sudo’s own record, and root, system and service accounts are refused.
Run it before removing the k3sm binary: the binary is what performs the purge.
Before deleting anything it checks that the data directories are the ones install created, and it
stops without removing anything if a check fails. Install marks each directory with a
.k3sm-dataroot file; a Mac installed by an older version has no marker, so run
sudo k3sm install once (it writes the markers) and then the purge. It never deletes into a
mounted filesystem, and it stops if any k3sm daemon or _k3sm process is still running after it
tries to stop them.
Copies outside these paths, such as Time Machine backups or APFS snapshots, are not touched.
Verifying#
k3sm version # prints the k3sm version + the Kubernetes control-plane pin (see the Version Support page)
k3sm status # what is running: daemons, apiserver, node, workloads, data root
k3sm kubectl get nodesNext#
- Stopping and starting covers
k3sm stopandstart, and how a reinstall treats a stopped node. - Quickstart runs your first Pod.
- kubectl access covers kubeconfig details.
- Upgrade explains how upgrades restart the daemon.
- Read Limitations before relying on k3sm.