diff --git a/runbooks/client-enrollment.md b/runbooks/client-enrollment.md index 341bc64..7de5e4a 100644 --- a/runbooks/client-enrollment.md +++ b/runbooks/client-enrollment.md @@ -8,16 +8,24 @@ docs_update_checklist: [hosts_narrative_page_if_lxc_or_vm] # Client enrollment -Goal: bring a new host (workstation, LXC, VM) into the mesh, inventory, -and secrets model. This wraps the existing `homelab client add` flow — -see [operations/agent-enrollment.md](../operations/agent-enrollment.md) -for the full walkthrough; this runbook is the risk/lifecycle framing. +Goal: bring a new host (workstation, LXC, VM) into inventory and the +secrets model, with mesh membership only where it's actually needed. +This wraps the existing `homelab client add` flow — see +[operations/agent-enrollment.md](../operations/agent-enrollment.md) for +the full walkthrough; this runbook is the risk/lifecycle framing. 1. On any enrolled client: `homelab client add ` — appends a `hosts.:` block to `inventory.yaml` (lifecycle `state: planned` → `provisioning`, per [oikos/ontology.yaml](../oikos/ontology.yaml)), commits + pushes. -2. Join the new host to Netbird (out-of-band, console or setup key). +2. Netbird join is **optional, not a required step** — only needed for + hosts that must be reachable off-LAN (workstations that roam, e.g. + `republic-laptop`, `mac-mini`). A node reachable on the household LAN + (192.168.8.0/24 — most LXCs/VMs) doesn't need it: it's already + reachable directly, and off-LAN clients reach it too via hubris's + routed `192.168.8.0/24` Netbird network resource. Skip this step for + LAN-only nodes; do it (out-of-band, console or setup key) only for + hosts that need independent off-LAN reachability. 3. On the new host: run `bootstrap.sh` (add `--with-hermes` to also enroll the Hermes agent). This provisions `/etc/age/key.txt`, the sync timer, and prints an age pubkey.