docs(runbook): drop the claim that a cold rebuild needs console access #662

2026-08-27T09:26:14Z

claude-bot commented

2026-08-27 09:26:14 +00:00

The rewrite earlier today stated, at the top and again in known gaps, that the rebuild cannot be driven remotely: management is a tagged VLAN, a maintenance-mode node cannot configure VLANs, so it comes up unreachable and every machine needs a keyboard.

That is wrong. A maintenance-mode node DHCPs untagged and is reachable at that address. It is not on management, but it answers — and that is precisely the address apply-config --insecure targets in Step 2. All three bare-metal conversions were driven that way, days before I wrote the opposite into the runbook.

The claim came from #576 and was carried in without being checked against what had already happened in this repo. A disaster-recovery runbook is the worst place to put an unverified constraint: it is read when there is no capacity to discover that a stated prerequisite is fiction, and "you need physical access to three machines" is exactly the sort of statement that changes whether someone attempts a recovery at all.

What survives is narrower and true: MS-01 has no IPMI and nothing here does PXE, so booting from USB is physical. Everything after the boot is remote.

Also removes the follow-on error from my first correction, which claimed the switch port change on 2026-08-27 had fixed a reachability problem. There was none to fix. That change is real and useful — a maintenance-mode node now lands in management rather than the fallback network — but it did not turn an impossible rebuild into a possible one.

#576 still carries the original claim; known gaps now flags it as wrong.

The rewrite earlier today stated, at the top and again in known gaps, that the rebuild cannot be driven remotely: management is a tagged VLAN, a maintenance-mode node cannot configure VLANs, so it comes up unreachable and every machine needs a keyboard. **That is wrong.** A maintenance-mode node DHCPs untagged and is reachable at that address. It is not on management, but it answers — and that is precisely the address `apply-config --insecure` targets in Step 2. All three bare-metal conversions were driven that way, days before I wrote the opposite into the runbook. The claim came from #576 and was carried in without being checked against what had already happened in this repo. A disaster-recovery runbook is the worst place to put an unverified constraint: it is read when there is no capacity to discover that a stated prerequisite is fiction, and *"you need physical access to three machines"* is exactly the sort of statement that changes whether someone attempts a recovery at all. What survives is narrower and true: MS-01 has no IPMI and nothing here does PXE, so booting from USB is physical. Everything after the boot is remote. Also removes the follow-on error from my first correction, which claimed the switch port change on 2026-08-27 had fixed a reachability problem. There was none to fix. That change is real and useful — a maintenance-mode node now lands in management rather than the fallback network — but it did not turn an impossible rebuild into a possible one. #576 still carries the original claim; known gaps now flags it as wrong.

claude-bot added 1 commit 2026-08-27 09:26:14 +00:00

docs(runbook): drop the claim that a cold rebuild needs console access

ci/woodpecker/pr/ci-scripts-test Pipeline was successful

Details

ci/woodpecker/pr/ci-manifests-test Pipeline was successful

Details

ci/woodpecker/pr/pr-review Pipeline was successful

Details

f51eb8bf35

The rewrite earlier today stated, at the top and again in known gaps, that the
rebuild cannot be driven remotely: management is a tagged VLAN, a maintenance
mode node cannot configure VLANs, so it comes up unreachable and every machine
needs a keyboard.

That is wrong. A maintenance-mode node DHCPs untagged and is reachable at that
address — it is not on management, but it answers, and that is precisely the
address `apply-config --insecure` targets in Step 2. All three bare-metal
conversions were driven that way.

The claim came from #576 and was carried into this document without being
checked against what had actually happened days earlier in this repo. It is the
worst place to put an unverified constraint: a disaster-recovery runbook is read
when there is no capacity to discover that a stated prerequisite is fiction, and
"you need physical access to three machines" is exactly the kind of statement
that changes whether someone attempts a recovery at all.

What survives is narrower and true: MS-01 has no IPMI and nothing here does
PXE, so booting from USB is physical. Everything after the boot is remote.

Also removes the follow-on error from the first correction, which claimed the
switch port change on 2026-08-27 had fixed a reachability problem. There was no
reachability problem to fix. That change is real and useful — a maintenance mode
node now lands in management rather than the fallback network — but it did not
turn an impossible rebuild into a possible one.

#576 still carries the original claim and is flagged in known gaps as wrong.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

claude-bot referenced this pull request

2026-08-27 09:26:29 +00:00

Separate the four traffic classes onto their own VLANs #576

review-bot reviewed

2026-08-27 09:27:49 +00:00

review-bot left a comment

🤖 Automated review — model claude-haiku-4-5-20251001 (complexity: trivial), commit f51eb8bf35fb3ed354b15bc2f6f36ee11dd46e83.

Advisory review by the review-bot pipeline. It never approves; a human merges. Push new commits to get a fresh review.

Summary

This PR corrects a critical misconception in the cold-rebuild runbook: it removes the false claim that nodes come up unreachable and removes an unnecessary physical-access prerequisite. The changes are factually grounded in the actual bare-metal conversion procedures documented elsewhere in the repo, and they improve the runbook by making the true constraint (booting is physical) clear while also suggesting more practical alternatives (reading DHCP leases from the UDM rather than requiring console access).

🟢 Nits

Line 114 in new version: "Read the leases off the UDM" is practical guidance, but could be more explicit about which UDM (e.g., "your UniFi Dream Machine") for readers unfamiliar with the infrastructure. Not blocking, since the prereq already mentions "the UDM" in context.

Tests

This is pure documentation; no tests apply.

Recommendation

Looks reasonable — no blocking issues; the factual corrections are well-grounded.

Verification notes

The changes replace false claims with accurate ones:

The maintenance-mode reachability claim (old: "comes up unreachable"; new: "DHCPs untagged and is reachable") is validated by kubernetes/RUNBOOK-baremetal-conversion.md:174–176, which states "Maintenance mode DHCPs untagged on every link; on these hosts that lands on 192.168.8.x, which is routable from the workstation." This runbook was written after the jupiter conversion on 2026-08-25, confirming the procedure works.
The apply-config --insecure usage is explicitly documented in Step 2 of this runbook (line 193) and in the baremetal-conversion runbook, confirming it works with the DHCP maintenance-mode address — consistent with the PR's clarification.
The UDM suggestion replaces an unrealistic "read the address off the console" instruction with a more practical alternative (DHCP leases on the UDM), which aligns with the claim that you don't need physical access after booting.
The flagging of #576's claim as unobserved is appropriate: the PR documents that "all three bare-metal conversions were driven that way" and the baremetal-conversion runbook proves this was done 2026-08-25. The note in the known gaps section correctly labels #576's claim as incorrect, which is valuable for future readers.

🤖 **Automated review** — model `claude-haiku-4-5-20251001` (complexity: trivial), commit `f51eb8bf35fb3ed354b15bc2f6f36ee11dd46e83`. > Advisory review by the `review-bot` pipeline. It never approves; a human merges. Push new commits to get a fresh review. --- ## Summary This PR corrects a critical misconception in the cold-rebuild runbook: it removes the false claim that nodes come up unreachable and removes an unnecessary physical-access prerequisite. The changes are factually grounded in the actual bare-metal conversion procedures documented elsewhere in the repo, and they improve the runbook by making the true constraint (booting is physical) clear while also suggesting more practical alternatives (reading DHCP leases from the UDM rather than requiring console access). ## 🟢 Nits - Line 114 in new version: "Read the leases off the UDM" is practical guidance, but could be more explicit about *which* UDM (e.g., "your UniFi Dream Machine") for readers unfamiliar with the infrastructure. Not blocking, since the prereq already mentions "the UDM" in context. ## Tests This is pure documentation; no tests apply. ## Recommendation Looks reasonable — no blocking issues; the factual corrections are well-grounded. --- ## Verification notes The changes replace false claims with accurate ones: 1. **The maintenance-mode reachability claim** (old: "comes up unreachable"; new: "DHCPs untagged and is reachable") is validated by `kubernetes/RUNBOOK-baremetal-conversion.md:174–176`, which states "Maintenance mode DHCPs untagged on every link; on these hosts that lands on `192.168.8.x`, which is routable from the workstation." This runbook was written after the jupiter conversion on 2026-08-25, confirming the procedure works. 2. **The `apply-config --insecure` usage** is explicitly documented in Step 2 of this runbook (line 193) and in the baremetal-conversion runbook, confirming it works with the DHCP maintenance-mode address — consistent with the PR's clarification. 3. **The UDM suggestion** replaces an unrealistic "read the address off the console" instruction with a more practical alternative (DHCP leases on the UDM), which aligns with the claim that you don't need physical access after booting. 4. **The flagging of #576's claim** as unobserved is appropriate: the PR documents that "all three bare-metal conversions were driven that way" and the baremetal-conversion runbook proves this was done 2026-08-25. The note in the known gaps section correctly labels #576's claim as incorrect, which is valuable for future readers.

k.renner merged commit a65109fee0 into master

2026-08-27 10:26:31 +00:00

k.renner referenced this issue from a commit

2026-08-27 10:26:31 +00:00

Merge pull request 'docs(runbook): drop the claim that a cold rebuild needs console access' (#662) from runbook-remote-rebuild-possible into master

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: konairius/homelab#662