ADR 008: Migration from Debian 12 Bookworm to Debian 13 Trixie

Synced read-only from /home/synnet/mirrors/synvirt-product/docs/decisions/008-migration-to-debian-13-trixie.md. Edit at the source, not here.

ADR 008: Migration from Debian 12 Bookworm to Debian 13 Trixie

Status

Accepted

Context

SynVirt 0.1 and 0.2 shipped on Debian 12 Bookworm (kernel 6.1 LTS). Two forces pushed us off that base for Hito 0.3:

1. Storage roadmap. Hito 0.3 introduces OpenZFS as a secondary data pool (see ADR 003 and ADR 009). We want to baseline on OpenZFS 2.4.x because block cloning and raidz expansion land in that series and both are load-bearing for the Hito 3 architecture. OpenZFS 2.4.x requires a kernel newer than 6.1.
2. Support window alignment. Kernel 6.12 LTS covers the entire SynVirt 0.x → 1.x roadmap (projected through 2027). Staying on 6.1 would force a mid-project kernel jump right when the storage layer is maturing.

Debian 13 Trixie (released August 2025) ships kernel 6.12 LTS and has a 5-year security support window plus an LTS phase that extends into the 2030s.

Decision

Migrate the SynVirt appliance ISO from Debian 12 Bookworm to Debian 13 Trixie starting with version 0.3.0. Concretely:

• iso-builder/build.sh pins:
  • DEBIAN_VERSION=13.4.0
  • DEBIAN_CODENAME=trixie
  • DEBIAN_ISO_SHA256=0b813535dd76f2ea96eff908c65e8521512c92a0631fd41c95756ffd7d4896dc
• Preseeds target mirror/suite=trixie and mirror/codename=trixie.
• APT uses apt-setup/non-free-firmware boolean true (Trixie’s non-free firmware split is consumed from the dedicated component).
• Bookworm ISOs are purged from iso-builder/cache/ on every build.

No in-place upgrade path is offered from 0.2 to 0.3. Upgrading an existing node requires a reinstall. localdata is introduced fresh in 0.3 (it didn’t exist on 0.2 nodes), so there is no migration loss for pool data; VM images on 0.2 nodes must be backed up and re-imported.

Rationale

• Kernel 6.12 LTS matches the project lifetime. Upstream projects a support window on 6.12 that spans the window we care about. Staying on 6.1 meant a forced kernel migration mid-0.x.
• OpenZFS 2.4.x parity across the pool. Installing 2.4.x on Bookworm would require a non-standard backports combination; on Trixie the package is available directly from trixie-backports (see ADR 010). This keeps the storage stack on a single major ZFS series from Hito 0.3 onward.
• Non-free firmware is already integrated. Trixie’s installer exposes the non-free firmware component in the standard APT flow, which simplifies hardware bring-up on NICs and RAID controllers that need firmware blobs.
• No ecosystem regressions. KVM, QEMU, libvirt, DRBD, nftables, OVN, and the Rust toolchain we pin are all available in Trixie at versions equal to or newer than Bookworm.

Consequences

• Fresh-install-only upgrade path. Nodes on 0.2 cannot be upgraded in place to 0.3. This is documented in the 0.3.0 release notes.
• Preseed reverifications required. Trixie’s installer behaves slightly differently from Bookworm’s in a few edge cases; see ADR 007 for the dual-firmware partman recipe that survived the migration, and the 0.3.0 test plan for the regression suite on BIOS/UEFI × SCSI/SATA.
• Base-image SHA pin. The SHA256 of the base netinst ISO is pinned in build.sh. Refreshing the base requires coordinated bumps of DEBIAN_VERSION and DEBIAN_ISO_SHA256.
• Bookworm knowledge is archival. Issues and runbooks written against Bookworm behavior should be re-verified before being cited on 0.3+ nodes.

Alternatives Considered

Stay on Debian 12 Bookworm, backport OpenZFS 2.4.x manually

• Pros: No base-OS migration work.
• Cons: Requires maintaining a custom OpenZFS build against kernel 6.1 LTS indefinitely. This is a supply-chain burden we explicitly do not want.
• Decision: Rejected.

Skip to Debian 13 mid-Hito-0.3 instead of at the start

• Pros: Lets 0.3 land on a familiar base.
• Cons: We would ship the dual-pool architecture, then immediately rebase on a different kernel / userland and re-qualify every path. Strictly more work.
• Decision: Rejected.

Wait for Debian 13.5+ before migrating

• Pros: Even more Trixie bug-fixes accumulated.
• Cons: Delays Hito 0.3 for a general maintenance window that we already trust. 13.4.0 is the current stable point release and has been in the field since its release.
• Decision: Rejected.