CR-2026-04-03: Restructure VyOS Migration from Monolith to Project Hierarchy

1. Change Summary

Field Value

CR ID

CR-2026-04-03-001

Date

2026-04-03

Priority

P2: Important

Type

Documentation Restructure

Status

Approved

Requestor

Evan Rosado

Implementor

Evan Rosado

Target Repo

domus-infra-ops

2. Objective

Decompose runbooks/domusdigitalis-vyos-migration.adoc (758 lines) from a monolithic runbook into a multi-page project structure with thin wrapper pages and granular partials. This establishes the first subdirectory-based project in domus-infra-ops, matching the pattern proven in domus-captures (ThinkPad T16g deploy, Kora CLI, ISE 3.4 Migration).

3. Justification

3.1. Business Case

The VyOS migration is a completed infrastructure project (pfSense decommissioned 2026-03-07), not an active runbook. Treating it as a runbook creates three problems:

  1. Maintenance burden — 758 lines in a single file makes targeted updates painful. Updating one milestone’s status requires scrolling through 400+ lines of unrelated content.

  2. No reusability — Tables (SPOF inventory, HA deployment status) are trapped inside the monolith. Other docs can’t reference them via include::partial$.

  3. Pattern inconsistency — domus-captures projects use thin wrappers + partials. domus-infra-ops has zero multi-page projects. This creates cognitive overhead when switching between repos.

3.2. What This Enables

  • Independent updates to any phase without touching other phases

  • Reusable partials (SPOF table, HA deployment status) includable from other docs

  • Navigation that shows project structure at a glance (13 nav entries vs 1)

  • Sets the pattern for future domus-infra-ops projects (Vault PKI, k3s Platform, etc.)

4. Current State vs Target State

Component Current (Before) Target (After)

File structure

Single 758-line file at runbooks/domusdigitalis-vyos-migration.adoc

13 thin wrapper pages in projects/vyos-migration/ + 31 partials in partials/projects/vyos-migration/

Navigation

Single entry under Runbooks > Firewall & WAN (line 211)

15-entry hierarchy under Projects > Migrations with phases, rollback, reference, decisions, field notes

Content ownership

All content inline — monolithic

Each logical unit in its own partial — independently updatable

Partials

0 project-specific partials (existing vyos-*.adoc are infrastructure data, untouched)

31 new partials under partials/projects/vyos-migration/

Project pattern

No multi-page projects in domus-infra-ops

First multi-page project — sets the standard

5. Scope

5.1. In Scope

  • Create pages/projects/vyos-migration/ with 13 thin wrapper pages

  • Create partials/projects/vyos-migration/ with 31 content partials

  • Move validation script to examples/vyos/migration-final-validation.sh

  • Create 4 new content partials (status-dashboard, metadata, decisions, field-notes)

  • Update nav.adoc — remove old runbook entry, add project hierarchy

  • Delete the old monolith

5.2. Out of Scope

  • runbooks/vyos-deployment.adoc — untouched (includes existing vyos-*.adoc partials)

  • Existing partials/vyos-*.adoc files — infrastructure data, not project structure

  • Content changes — this is a restructure, not a rewrite

  • Other domus-infra-ops projects — they stay as single-file for now

6. Implementation Plan

6.1. Phase 1: Directory Structure

Create two new directories:

  • pages/projects/vyos-migration/

  • partials/projects/vyos-migration/

6.2. Phase 2: Extract Partials from Monolith

Extract content from the 758-line monolith into 25 partials. Each partial contains only content (no page headers). Comments at top indicate source and includer.

Partial Source (monolith lines) Type

summary.adoc

39-59

Executive summary table

planning-hardware.adoc

68-93

Hardware requirements table

planning-software.adoc

95-116

Software requirements table

planning-verification.adoc

118-135

Pre-migration verification script

phase-a-dns.adoc

144-189

DNS milestone + checkpoint

phase-b-deployment.adoc

191-241

VyOS deployment + checkpoint

phase-c-security.adoc

243-287

Security + checkpoint

phase-d-testing.adoc

289-313

Pre-cutover + checkpoint

phase-e-vrrp.adoc

315-368

VRRP + checkpoint + failover test

phase-f-advanced.adoc

370-400

Advanced features

ref-premigration.adoc

409-430

Pre-migration runbook links

ref-dns.adoc

432-449

DNS runbook links

ref-ha-deployment.adoc

451-513

HA deployment + SPOF tables

ref-vyos-config.adoc

515-528

VyOS runbook links

ref-emergency.adoc

530-543

Emergency procedure links

ref-network.adoc

545-558

Network infrastructure links

ref-postmigration.adoc

560-569

Post-migration runbook links

rollback-dns.adoc

585-598

DNS rollback

rollback-vyos.adoc

600-614

VyOS config rollback

rollback-complete.adoc

616-631

Full rollback to pfSense

post-migration.adoc

687-726

7-day stabilization checklist

related-docs.adoc

728-757

Cross-reference links

6.3. Phase 3: Validation Script to Examples

Move final validation script (lines 635-683) to examples/vyos/migration-final-validation.sh.

6.4. Phase 4: Create New Partials

4 partials that don’t exist in the monolith:

Partial Purpose

status-dashboard.adoc

Per-phase status table with completion indicators (matches T16g deployment status pattern)

metadata.adoc

PRJ metadata: ID, author, dates, status, completion date, key hostnames

decisions.adoc

Architecture rationale: why VyOS over OPNsense, why VRRP over CARP, why zone-based firewall, why dual-BIND, parallel deployment risk model

field-notes.adoc

Deployment observations: pfSense decommission (2026-03-07), VRRP failover results, pending items (C/F), scope creep backlog

6.5. Phase 5: Create Thin Wrapper Pages

13 pages following the T16g pattern — 5-7 lines each:

= Phase A: DNS Infrastructure
:description: BIND9 DNS record migration — 43 A + 43 PTR + 9 CNAME records
:navtitle: Phase A: DNS Infrastructure
:icons: font

include::partial$projects/vyos-migration/phase-a-dns.adoc[]

Multi-partial pages (index, planning, rollback, validation, reference) include 2-5 partials each.

6.6. Phase 6: Update Navigation

Remove from nav.adoc line 211 (Runbooks > Firewall & WAN):

*** xref:runbooks/domusdigitalis-vyos-migration.adoc[VyOS Migration (Master)]

Add to Projects section (~line 147):

** Migrations
*** VyOS Migration (pfSense → VyOS)
**** xref:projects/vyos-migration/index.adoc[Overview]
**** xref:projects/vyos-migration/planning.adoc[Planning]
**** Phases
***** xref:projects/vyos-migration/phase-a-dns.adoc[A: DNS Infrastructure]
***** xref:projects/vyos-migration/phase-b-deployment.adoc[B: VyOS VM Deployment]
***** xref:projects/vyos-migration/phase-c-security.adoc[C: Security & Observability]
***** xref:projects/vyos-migration/phase-d-testing.adoc[D: Pre-Cutover Testing]
***** xref:projects/vyos-migration/phase-e-vrrp.adoc[E: VRRP HA]
***** xref:projects/vyos-migration/phase-f-advanced.adoc[F: Advanced Features]
**** xref:projects/vyos-migration/rollback.adoc[Rollback]
**** xref:projects/vyos-migration/validation.adoc[Validation & Stabilization]
**** xref:projects/vyos-migration/reference.adoc[Reference]
**** xref:projects/vyos-migration/decisions.adoc[Decisions & Risks]
**** xref:projects/vyos-migration/field-notes.adoc[Field Notes]

6.7. Phase 7: Delete Monolith

Remove pages/runbooks/domusdigitalis-vyos-migration.adoc.

6.8. Phase 8: Build Verification

cd ~/atelier/_bibliotheca/domus-infra-ops
make 2>&1 | grep -E "WARN|ERROR"

Verify:

  • No broken xrefs

  • No missing includes

  • All 13 pages render

  • Nav hierarchy displays correctly

  • runbooks/vyos-deployment.adoc still works (untouched)

7. Rollback Plan

All changes are in git. If the build fails or the structure doesn’t work:

# Revert all changes in domus-infra-ops
git -C ~/atelier/_bibliotheca/domus-infra-ops checkout -- .
git -C ~/atelier/_bibliotheca/domus-infra-ops clean -fd

The monolith is recoverable from git history at any time.

8. Risk Assessment

Risk Likelihood Impact Mitigation

Broken xrefs in new pages

Medium

Low (build warnings)

Build verification before commit; all xref targets are existing pages

Other pages link to old monolith path

Low

Medium (broken links)

Grep for domusdigitalis-vyos-migration across all repos before deleting

Existing vyos-deployment.adoc breaks

None

High

Out of scope — file is not touched

Nav rendering issues

Low

Low

Test locally with make serve

9. Communication

Audience Timing Method

Self (documentation)

During change

Local build verification

10. What Stays Untouched

  • runbooks/vyos-deployment.adoc and all its partial includes

  • All existing partials/vyos-*.adoc files (infrastructure data)

  • All xref targets referenced in the monolith (runbook links still valid)

  • examples/vyos/ existing content

11. File Inventory

11.1. New Files (44 total)

Category Count

Thin wrapper pages

13

Extracted partials

22

New content partials

4

Example scripts

1

Total new files

44 [1]

11.2. Deleted Files (1)

  • pages/runbooks/domusdigitalis-vyos-migration.adoc

12. Related

1. Replaces 1 monolithic file