Kevin AdamsandClaude Opus 5.5
0ce578d63f
Per RUNBOOK-002, the version bump, CHANGELOG, ROADMAP and both Debian changelogs land before the tag so the release ships with its docs. The CHANGELOG now also covers the review follow-ups and the final live retest. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
freenas-proxmox / truenas-proxmox — Roadmap
This file captures release scope, business decisions, and deferred items. It is updated in the same commit as any scope or decision change — not just in issues or memory.
Released — v3.0.0 (TrueNAS Custom Plugin)
Released: 2026-05-31
Branch: release/3.x (default branch at the time; renamed to main 2026-08-30, see ADR-013)
GitHub Release: https://github.com/TheGrandWazoo/freenas-proxmox/releases/tag/v3.0.0
Full rewrite as a native PVE::Storage::Custom plugin. No patching of PVE files, no SSH, full TrueNAS REST API, bearer token auth only.
Confirmed tested
| Component | Versions |
|---|---|
| Proxmox VE | 8.4.x, 9.2.x |
| TrueNAS CORE | 13.0-U6 |
| TrueNAS SCALE | 24.10 Electric Eel, 25.04, 25.10 |
What shipped
| # | Fix |
|---|---|
| #266 | PVE 9: lun string vs integer in QEMU blockdev JSON |
| #269 | SCALE 25.10 strict Pydantic rejects volsize as string |
| #267 | free_image 422 on targetextent delete when VM is running |
| #265 | Loop over all targetextent rows in free_image |
| #264 | SCALE 25.04 integer type coercion + alias uniqueness |
| #261 | API token keyfile (/etc/pve/priv/truenas-<id>.key) |
| #262 | Package rename: freenas-proxmox → truenas-proxmox + transitional package |
| #263 | Fix truenas_target full-IQN match |
| #260 | TPM state disk limitation callout |
| #250 | Rollback orphaned TrueNAS resources on alloc_image partial failure |
| #228 | Migration docs: beginner, advanced, troubleshooting |
Released — GitHub Pages APT Repository
Completed: 2026-06-06
Closed: #230
URL: https://thegrandwazoo.github.io/freenas-proxmox
Replaced Cloudsmith as the primary package distribution channel. Per-major-version dist tracks prevent silent cross-version upgrades (ADR-010). Optional feature packages distributed via apt components (ADR-011).
Dist tracks
| Dist | Content | Sources.list |
|---|---|---|
main |
v2.x — backward-compat alias | ... freenas-proxmox main main |
v2 |
v2.x — explicit pin | ... freenas-proxmox v2 main |
v3 |
v3.x | ... freenas-proxmox v3 main |
v4 (rivendell) |
v4.x — current stable | ... freenas-proxmox v4 main |
testing |
beta builds from main (shipped v3.1.0, #272) |
... freenas-proxmox testing main |
v3→v4 upgrade procedure: docs/upgrade-paths.md (#293, v4.0.2).
Components (ADR-011)
| Component | Content |
|---|---|
main |
Base plugin (all installs) |
multipath |
truenas-proxmox-multipath — optional add-on, #256 |
Cloudsmith transition state (2026-06-06)
| Channel | State |
|---|---|
Stable (truenas-proxmox) |
v3.x+ no longer published here; v2.x still published |
Testing (truenas-proxmox-testing) |
Still active until #272 ships |
Migration tooling
scripts/migrate-repo-to-github-pages.sh — auto-detects installed version, finds Cloudsmith sources by URL content, switches to correct dist track. Run on each Proxmox node as root.
Deferred Business Decisions
GitHub Repo Rename: freenas-proxmox → truenas-proxmox
Status: Deferred — no timeline set
Decision date: 2026-05-25
Tracked in: #229
All code is ready. GitHub auto-redirects old URLs so there is no technical urgency.
gh repo rename truenas-proxmox --repo TheGrandWazoo/freenas-proxmox
Note: FUNDING.yml is tied to the user account, not the repo name. Rename has no effect on GitHub Sponsors.
Released — v3.1.0 (PVE 9 + Snapshots)
Released: 2026-06-07
PVE support: PVE 9.x only — PVE 8 support dropped
Decision date: 2026-05-31 — see ADR-009
GitHub Release: https://github.com/TheGrandWazoo/freenas-proxmox/releases/tag/v3.1.0
v3.1 is the first release that requires PVE 9. Dropping PVE 8 allows:
- Bumping
api()to PVE 9'sAPIVER(silences "older storage API" warning) - Implementing snapshot-as-volume-chains (PVE 9 feature)
- Removing the
qemu_blockdev_optionsoverride if Proxmox fixesPlugin.pmupstream
Completed in v3.1.0
| # | Title | Commit |
|---|---|---|
| #270 | Bump api() to 14 — silences PVE 9 "older storage API" warning |
fc74a42 |
| #272 | GitHub Pages testing dist track (retires Cloudsmith testing) | 03fe20b |
| #273 | Debian changelog in package (apt changelog was failing) |
1c98591 |
| #274 | Filename: prefix stripped from Packages — packages not downloadable | 19a3ec2 |
| #275 | README badges pointed to non-existent repo | da0aaff |
| #276 | parse_volname state volume crash — RAM snapshots left orphans | 80a7889 |
| #234 | Snapshot interface — ZFS snapshots via TrueNAS REST API | 59d8a81 |
Snapshot implementation (2026-06-07): Verified on PVE 9.2.3 against TrueNAS CORE 13.0-U6 and SCALE 24.10. Disk-only and RAM snapshots both confirmed working end-to-end including rollback.
Carried forward
| # | Title | Notes |
|---|---|---|
| #277 | iSCSI GET_LBA_STATUS error on VM start | Log noise, non-fatal — open |
Released — v3.2.0 (Multipath)
Released: 2026-06-20
GitHub Release: https://github.com/TheGrandWazoo/freenas-proxmox/releases/tag/v3.2.0
Introduces the truenas-proxmox-multipath optional add-on package. Active-active iSCSI multipath via dm-multipath. Separate plugin (TrueNASMultipath.pm) in the multipath apt component — not part of the base plugin. See ADR-011.
Confirmed tested
| Component | Versions |
|---|---|
| Proxmox VE | 9.2.x |
| TrueNAS CORE | 13.0-U6 (FreeBSD / ALUA) |
| TrueNAS SCALE | 24.10 Electric Eel, 25.04 |
Path mode: Active-active (multibus + service-time 0) — both paths carry I/O simultaneously. Failover and path recovery confirmed on CORE and SCALE 25.04.
What shipped
| # | Title | Commit |
|---|---|---|
| #256 | Multipath plugin — truenas-proxmox-multipath package (ADR-011) |
da82356 |
| #278 | Multipath UI panel (truenas-multipath in Datacenter → Storage → Add) |
da82356 |
| #279 | postinst: strip pre-existing unmanaged devices block in multipath.conf | b7acb60 |
Known differences: CORE vs SCALE multipath
| TrueNAS CORE (FreeBSD) | TrueNAS SCALE (Linux) | |
|---|---|---|
| iSCSI target | ctld |
Linux LIO |
| ALUA | Yes — hwhandler='1 alua', prio=50 |
No — hwhandler='0', prio=1 |
| Portal config | 0.0.0.0 (all interfaces) |
Per-IP listen addresses required |
| Failover time | ~2s (ALUA state query) | <0.1s |
| SCALE 25.04 note | — | port field rejected in PUT /api/v2.0/iscsi/portal — omit it (#280) |
Released — v4.0.0 (Rivendell, WebSocket API)
Released: 2026-08-31
Branch: main (promoted from next at cutover — release/3.x archives the v3.x line, per ADR-013's first-ever major-version cutover)
GitHub Release: https://github.com/TheGrandWazoo/freenas-proxmox/releases/tag/v4.0.0
Why major version: WebSocket JSON-RPC 2.0 is a new transport — genuine architectural change (ADR-009).
WebSocket JSON-RPC 2.0 transport for TrueNAS SCALE 25.04+, auto-detected per host alongside the existing REST v2.0 transport (TrueNAS CORE, SCALE < 25.04) — storage.cfg unchanged either way. Full design and live-verification history: ADR-012 (Accepted).
Confirmed tested
| Component | Versions |
|---|---|
| Proxmox VE | 9.2.3 |
| TrueNAS CORE | 13.x (REST transport regression-checked, real production host) |
| TrueNAS SCALE | 25.10.3.1, 25.10.6, 25.04.2.6 (WebSocket transport) |
What shipped
| # | Title |
|---|---|
| #243 | WebSocket JSON-RPC 2.0 transport, auto-detected per host |
Also verified as part of this release: a full alloc_image/free_image/snapshot cycle over the new transport (zero orphans), a REST-path regression check against real TrueNAS CORE, and truenas-proxmox-multipath working over WebSocket with zero code changes. See CHANGELOG.md for the full list, including two real bugs caught and fixed during live testing before ever shipping.
Ideas under consideration (not committed)
| # | Title | Notes |
|---|---|---|
| #289 | UI: show installed plugin + TrueNAS version per storage | Floated 2026-08-30 alongside #243/ADR-012 work — a per-node plugin version and per-storage TrueNAS version could differ across a cluster, similar to how Ceph's panel surfaces per-node version info. Possible v4.0.0 scope, backported to v3.x if small enough. |
| — | Nice-to-have: friendlier apt Origin label |
PVE's Repositories panel shows our repo as truenas-proxmox with a generic ? icon. The Debian/Proxmox logos are hard-coded in proxmox-widget-toolkit APTRepositories.js, so third-party repos can't get one. Optional: set the Release file's Origin: to something nicer (e.g. KSA Technologies) in the repo publish step. Don't override the UI renderer from truenas-storage.js, because that would be patching PVE core. Low priority (2026-10-04). |
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 | path() placeholder for extent-less zvols — orphans deletable via PVE |
f5e625a |
| #291 | Multipath path() returns owner VMID — qm destroy no longer orphans disks |
8c919d1 |
| #294 | volume_resize, cloud-init volnames, list-context volume_size_info |
83bda13 |
| #293 | Docs: real v3→v4 upgrade path; PVE 8 pin to 3.0.0-1 | 615d779 |
| #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. |
Released — v4.0.3 (WebSocket reliability)
Released: 2026-10-14
Branch: main
GitHub Release: https://github.com/TheGrandWazoo/freenas-proxmox/releases/tag/v4.0.3
TrueNAS closes idle WebSockets after 30–60 s, and long-lived PVE daemons reused the dead cached connection. VM creates failed, content listings returned HTTP 500, and SCALE storages flapped to inactive. The CLI never showed it. Found by the slm-saas-poc Terraform session. v3.x is unaffected because it is REST only.
Confirmed tested
| Component | Versions |
|---|---|
| Proxmox VE | 9.2.21 |
| TrueNAS SCALE | 25.04.2.6, 25.10.6 (WebSocket transport) |
What shipped
| # | Title | Commit |
|---|---|---|
| #303 | Check and ping a cached WebSocket before reuse; retry read-only calls once; drop the connection on timeout, write failure or failed login | d4ef4a4 |
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.
- ADRs (in
.claude/cos/adrs/) capture architectural decisions. - This file captures timing, business rationale, and deferred actions.