8.1 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)
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 |
testing |
beta builds | Future — #272 |
Components (ADR-011)
| Component | Content |
|---|---|
main |
Base plugin (all installs) |
multipath |
truenas-proxmox-multipath — future opt-in, #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.
Upcoming — v3.1.0 (PVE 9 + Snapshots)
Target: Before PVE 8 EOL — 2026-08-31
PVE support: PVE 9.x only — PVE 8 support dropped
Decision date: 2026-05-31 — see ADR-009
Milestone: v3.1.0 — PVE 9 + Snapshots
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 (in progress)
| # | 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.
Open in v3.1.0
| # | Title | Notes |
|---|---|---|
| #277 | iSCSI GET_LBA_STATUS error on VM start | Log noise, non-fatal |
| #256 | Multipath — separate plugin (ADR-011) | Hardware-blocked |
| # | Title | Notes |
|---|---|---|
| #234 | Snapshot interface (Snapshot-as-Volume-Chains) | ✅ Done |
| #270 | Bump api() to PVE 9 APIVER |
✅ Done |
| #272 | GitHub Pages testing dist track (replace Cloudsmith testing) | Required |
| #256 | Multipath — separate truenas-proxmox-multipath plugin (ADR-011) |
Blocked on hardware |
| #249 | Per-variant dispatch (TrueNAS-Core.pm / TrueNAS-Scale.pm) | Evaluate |
Multipath design decision (2026-06-06)
Multipath ships as a separate plugin (TrueNASMultipath.pm) in a separate package (truenas-proxmox-multipath), distributed via the multipath apt component — not as a boolean option in the base plugin. See ADR-011 and #256.
Upcoming — v4.0.0 (WebSocket API, SCALE 25.x)
Target: After PoC testing on SCALE 25.04+
Why major version: WebSocket JSON-RPC 2.0 is a new transport — genuine architectural change.
| # | Title |
|---|---|
| #243 | WebSocket JSON-RPC 2.0 API support (TrueNAS SCALE 25.04+) |
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.