Joining a second Mac
Mint a join token, bring up a second Mac as an agent over the wireguard mesh, and see two nodes serving one cluster: cross-node NodePort, PVC persistence, and in-pod kubectl and DNS from the joined worker all work on two Macs.
Thirty minutes, for two machines. You come away with a second Mac joined to the first one’s cluster over the wireguard mesh, and a clear line around what the two-node path can and cannot do yet. Multi-node is experimental until it graduates in a later release.
The join flow, the bootstrap credentials, and the mesh peer model work on a pair of Macs. With two Macs you get two Ready nodes, a cross-node NodePort round trip, a PersistentVolumeClaim that keeps its data across a pod restart, and a pod on the joined worker resolving cluster DNS and completing an authenticated apiserver call against the server.
Mesh Model#
One Mac runs the control plane with k3sm server. Additional Macs join as agents running the
Virtual Kubelet node. Nodes are connected by a wireguard mesh, so Pod and Service traffic can cross
machines. Private keys never leave a node; the peer records held in the datastore carry public keys
only.
1. On the Server Mac#
Give the install its own mesh address so other nodes can join it:
sudo k3sm install --mesh-ip <this-macs-mesh-address>Then mint a join token:
sudo k3sm token createRun that one with sudo. The token pins the hash of the cluster CA, which lives in the
control-plane state root owned by the _k3sm service user. Without sudo the work directory
resolves to your own home and the command exits non-zero rather than inventing a CA there.
The control plane only starts accepting joins once its own mesh enrolment has finished, and that can take up to a minute after the install command returns. If step 2 reports that the control plane cannot be reached, wait a little and run it again.
2. On the Second Mac#
Put the token from step 1 in a file only root can read:
sudo sh -c 'umask 077; cat > /var/root/k3sm-join-token'Paste the token, then press Ctrl-D. Now install and join in one step:
sudo k3sm install --agent --server <server-lan-ip-or-name> --token-file /var/root/k3sm-join-token--server is the control-plane Mac’s own LAN address (an underlay IP or hostname, no scheme,
no port); the join dials it on 9345, before this Mac has any mesh to route over. --node-ip is
optional and, when given, is this Mac’s mesh address instead: the join assigns that address
itself, so pass --node-ip only to assert the value you expect. The token file must not be group-
or world-readable, and once the node shows Ready it is yours to delete. See
multi-node for predicting or asserting the mesh address a joining node will
get.
The agent presents the bootstrap token, receives its node credentials, and registers its wireguard public key as a mesh peer. The worker gets its own agent launchd daemon, starts at boot, and rejoins with its stored credential, no token needed. Uninstalling k3sm on it removes the node from the cluster.
3. Confirm#
From the server Mac:
k3sm kubectl get nodes -o wideBoth Macs appear as ready nodes, and a Service resolves to backends on either
one. If the join fails, re-mint the token (tokens expire) and confirm the agent can
reach the server on 9345. See troubleshooting.
What Changes Once There Are Two Nodes#
- Stateful Pods are pinned by their data. A local-path volume lives on one Mac’s disk, and the PV’s node affinity sends every future Pod for that claim back to the same machine. Plan placement around the data. See storage.
- Per-pod IP identity and headless or StatefulSet DNS records are present. Check cross-node resolution with your own workload before you depend on pod names.
- Upgrades are a node-by-node rolling restart of the launchd daemons, which opens a brief version-skew window between machines. See upgrade.
- Every node, the joined worker included, enforces NetworkPolicy for its own Pods, on Service-VIP
traffic only; direct pod-IP traffic bypasses it, and a
fromrule cannot match a Pod on another node. Do not use a second Mac as a tenancy boundary; see the vm RuntimeClass. - A
vmPod answers on its pod IP from every node, over TCP, on the ports it declares and the ports a Service targets on it, so Services reachvmPods across nodes. UDP to avmPod’s pod IP is not relayed.
High Availability#
A second Mac can share the control plane as an experimental feature. Run
sudo k3sm install --cluster-init on the first server to form an embedded etcd control plane, then
sudo k3sm install --server-join on the second. Two servers tolerate no server failure: losing
either one stops writes until it returns or the survivor runs sudo k3sm server --cluster-reset.
Workers stay attached to the server they joined through. high availability has the
flags and the recovery steps.
Next#
- linux workloads and the vm runtimeclass covers running a Pod inside its own VM.
- multi-node is the reference page.