diff --git a/.claude/cos/runbooks/RUNBOOK-002-release-checklist.md b/.claude/cos/runbooks/RUNBOOK-002-release-checklist.md index 0488e60..5ebd51b 100644 --- a/.claude/cos/runbooks/RUNBOOK-002-release-checklist.md +++ b/.claude/cos/runbooks/RUNBOOK-002-release-checklist.md @@ -36,6 +36,12 @@ checklist, not infrastructure. section exists yet (a smaller release that wasn't tracked incrementally), write one now covering what actually shipped. +2a. **Debian changelogs**: prepend an `X.Y.Z-1` entry to `packaging/changelog.Debian` + and `packaging/DEBIAN-multipath/changelog.Debian`. These are what + `apt changelog` shows. They fell behind during v4.0.0/4.0.1, still topped + at 3.2.4/3.2.2, and were caught up at v4.0.2. Check with + `dpkg-parsechangelog -l -S Version`. + 3. **ROADMAP.md**: move the entry from "Upcoming" to "Released", following the exact pattern already established for v3.0.0/v3.1.0/v3.2.0/v4.0.0 — Released date, branch, GitHub Release link, "Confirmed tested" table (real versions diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d9205c..1fb99ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,72 @@ See each [GitHub Release](https://github.com/TheGrandWazoo/truenas-proxmox/relea --- +## [4.0.2] — 2026-10-13 + +Volume lifecycle fixes. Every change is backward compatible and `storage.cfg` is unchanged. +Milestone: *v4.0.2 — Volume lifecycle fixes*. + +### Added +- **Disk resize** (`volume_resize`) for `truenas` and `truenas-multipath` (#294). + Before this, the base `Plugin.pm` died with `can't resize this image format`. + That blocked `qm disk resize`, the GUI, and Terraform cloud-image provisioning. + - The zvol is grown through the pool/dataset update API, aligned to 1 MiB and + sent as an integer `volsize` (required by SCALE's validation). + - The WebSocket transport gains the `PUT` → `pool.dataset.update` mapping. + - Multipath also rescans the target's kernel iSCSI sessions and runs + `multipathd resize map` when the device is active, so the QMP + `block_resize` on a running VM can grow past the old dm size. +- First Perl unit-test harness (`t/`, a mock TrueNAS API plus a PVE plugin stub), + run by `prove` in the CI lint job (#292). + +### Fixed +- **Cloud-init drives**: `parse_volname` now accepts `vm-N-cloudinit` and + `base-N-cloudinit` (#294). `alloc_image` already created them, but every later + operation, including `qm destroy`, died with + `unable to parse TrueNAS volume name`. +- **`volume_size_info` in list context** now returns `(size, format, used, parent)`, + like ZFSPoolPlugin (#294). Before this, the content API, and the `bpg/proxmox` + Terraform provider that calls it, died with `no format`. A missing zvol now + dies instead of reporting a size of 0. +- **Orphan zvols couldn't be deleted** (#292). `path()` died on a zvol with no + iSCSI extent, so `pvesm free`, the GUI Remove and `qm destroy` couldn't clean up + failed allocations or v2-era leftovers. `path()` now returns a placeholder, + `iscsi:///unmapped/` (multipath: + `/dev/mapper/truenas-unmapped-`), together with the real owner and vtype. + `activate_volume` still refuses it, so no VM can open it. +- **`qm destroy` silently left multipath disks on TrueNAS** (#291). The + multipath `path()` returned the LUN id as the owner VMID and the storeid as the + vtype, so PVE skipped every disk while the task still reported `OK`. + `_naa_to_wwid(undef)` also returned a truthy `"3"`, which pointed at + `/dev/mapper/3`. It now returns undef. + +### Changed +- **`truenas-proxmox-multipath` now depends on the exact same `truenas-proxmox` + version**, `(= X.Y.Z-1)` instead of `(>= 3.1.0)` (#299). The multipath plugin + calls the base plugin's private helpers and `SUPER::volume_resize`, so a + mismatched pair failed at runtime. CI fails the build if the dependency drifts. + +### Documentation +- `docs/upgrade-paths.md` now has the real **v3.x → v4.x** in-place procedure + (pre-checks, track switch, verification, rollback) and the **v2.x → v4.x** + ordering. The README, getting-started and migrating-from-v2 now install from + `v4` on PVE 9 (#293). +- PVE 8 guidance corrected: v3.1+ already requires PVE 9 (ADR-009), so on PVE 8 + only `3.0.0-1` loads and it must be pinned with `apt-mark hold`. +- README troubleshooting entries for #291, #292 and #294, with workarounds + for ≤ 4.0.1. + +### Verified (live, PVE 9.2.21, pve01) +- Full cycle on every transport and storage type: create with a cloud-init + drive, content API `format: raw`, resize +1G while stopped, start, resize + +1G while running (QEMU sees the new size), `qm cloudinit update`, then + `qm destroy --purge` with no orphan volumes and no iSCSI sessions left. + - TrueNAS CORE 13.0-U6.8, REST transport + - TrueNAS SCALE 25.04.2.6, WebSocket transport + - TrueNAS SCALE 25.10.6, WebSocket transport + - `truenas-multipath` on SCALE 25.04.2.6, two portals +- `prove t/` passes, and perlcritic is clean. + ## [4.0.1] — 2026-09-01 ### Fixed diff --git a/ROADMAP.md b/ROADMAP.md index c9c56bc..fd5f898 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -201,6 +201,42 @@ Also verified as part of this release: a full `alloc_image`/`free_image`/snapsho --- +## Released — v4.0.2 (Volume lifecycle fixes) + +**Released:** 2026-10-13 +**Branch:** `main` +**GitHub Release:** https://github.com/TheGrandWazoo/freenas-proxmox/releases/tag/v4.0.2 +**Backport:** v3.2.6 on `release/3.x` (REST only, multipath included) + +Closes the volume-lifecycle gaps found while running real workloads (Terraform cloud-image provisioning, orphan cleanup after the cluster's PVE 9 upgrade): disk resize, cloud-init drives, content-API sizing, deletable orphans, and multipath `qm destroy`. Also adds the first unit-test harness (`t/` + `prove` in CI). + +### Confirmed tested + +| Component | Versions | +|-----------|---------| +| Proxmox VE | 9.2.21 | +| TrueNAS CORE | 13.0-U6.8 (REST transport) | +| TrueNAS SCALE | 25.04.2.6, 25.10.6 (WebSocket transport); multipath on 25.04.2.6 with two portals | + +### What shipped + +| # | Title | Commit | +|---|-------|--------| +| [#292](https://github.com/TheGrandWazoo/freenas-proxmox/issues/292) | `path()` placeholder for extent-less zvols — orphans deletable via PVE | f5e625a | +| [#291](https://github.com/TheGrandWazoo/freenas-proxmox/issues/291) | Multipath `path()` returns owner VMID — `qm destroy` no longer orphans disks | 8c919d1 | +| [#294](https://github.com/TheGrandWazoo/freenas-proxmox/issues/294) | `volume_resize`, cloud-init volnames, list-context `volume_size_info` | 83bda13 | +| [#293](https://github.com/TheGrandWazoo/freenas-proxmox/issues/293) | Docs: real v3→v4 upgrade path; PVE 8 pin to 3.0.0-1 | 615d779 | +| [#299](https://github.com/TheGrandWazoo/freenas-proxmox/issues/299) | Multipath depends on the exact base package version | e40d6d8 | + +### Ideas under consideration (not committed) + +| # | Title | Notes | +|---|-------|-------| +| — | Multipath: degrade instead of fail when one of N portals is down | Seen in the #294 lab test (2026-10-12): one unreachable portal made `activate_volume` fail outright. Should it log in on the remaining paths and warn? | +| — | Multipath: quieter `deactivate_volume` | `qm stop` prints `iscsiadm: No matching sessions found` / `No records found`. Harmless, but noisy. | + +--- + ## Process Rules - Every business decision (defer, hold, change scope) is recorded here **and** as a comment on the relevant GitHub issue — not only in conversation or AI memory. diff --git a/packaging/DEBIAN-multipath/changelog.Debian b/packaging/DEBIAN-multipath/changelog.Debian index 7b202ec..de9898b 100644 --- a/packaging/DEBIAN-multipath/changelog.Debian +++ b/packaging/DEBIAN-multipath/changelog.Debian @@ -1,3 +1,14 @@ +truenas-proxmox-multipath (4.0.2-1) trixie; urgency=medium + + * volume_resize: rescan kernel iSCSI sessions and multipathd resize map + so running VMs see the grown disk (#294) + * path() returns the owner VMID and vtype; qm destroy no longer silently + orphans multipath disks (#291) + * _naa_to_wwid(undef) returns undef instead of "3" (#291) + * Depend on the exact same truenas-proxmox version (#299) + + -- KSA Technologies, LLC Tue, 13 Oct 2026 00:00:00 +0000 + truenas-proxmox-multipath (3.2.2-1) bookworm; urgency=low * Version bump to match truenas-proxmox 3.2.2; api() fix inherited from TrueNAS.pm diff --git a/packaging/changelog.Debian b/packaging/changelog.Debian index 98ad8cb..7df4d64 100644 --- a/packaging/changelog.Debian +++ b/packaging/changelog.Debian @@ -1,3 +1,18 @@ +truenas-proxmox (4.0.2-1) trixie; urgency=medium + + * Add volume_resize (zvol grow via pool/dataset update; WebSocket PUT + mapping) so qm disk resize works, including on running VMs (#294) + * parse_volname accepts vm-N-cloudinit / base-N-cloudinit (#294) + * volume_size_info returns (size, format, used, parent) in list context; + fixes content API "no format" (#294) + * path() returns a placeholder for extent-less zvols so orphans can be + freed through PVE (#292) + * Multipath path() returns the owner VMID and vtype so qm destroy no + longer leaves multipath disks behind (#291) + * v4.0.0/4.0.1 (WebSocket transport for SCALE 25.04+) — see CHANGELOG.md + + -- KSA Technologies, LLC Tue, 13 Oct 2026 00:00:00 +0000 + truenas-proxmox (3.2.4-1) bookworm; urgency=medium * Fix postinst/postrm to also restart pvestatd, pve-ha-lrm, pve-ha-crm on diff --git a/perl5/PVE/Storage/Custom/TrueNAS.pm b/perl5/PVE/Storage/Custom/TrueNAS.pm index 80d951b..0273aef 100644 --- a/perl5/PVE/Storage/Custom/TrueNAS.pm +++ b/perl5/PVE/Storage/Custom/TrueNAS.pm @@ -58,7 +58,7 @@ use PVE::Storage::Plugin; use base qw(PVE::Storage::Plugin); -our $VERSION = '4.0.1'; +our $VERSION = '4.0.2'; # Per-host runtime state cache my $state = {};