From 48debc0911b84442fe8b14ed9c45a960c00f4dc0 Mon Sep 17 00:00:00 2001 From: dtoro Date: Sun, 5 Jul 2026 23:03:21 +0200 Subject: [PATCH] runbooks: clarify Netbird join is optional, not a required enrollment step MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Only off-LAN-reachable workstations (e.g. republic-laptop, mac-mini) need to join Netbird. LAN-reachable LXCs/VMs on 192.168.8.0/24 don't — they're already directly reachable, and off-LAN clients reach them via hubris's routed 192.168.8.0/24 Netbird network resource. Brings the runbook in line with oikos/ontology.yaml's lifecycle transition, which already says "mesh-joined-if-needed". Co-Authored-By: Claude Fable 5 --- runbooks/client-enrollment.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) 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.