From 4e621a215c87d92c0915a368a55d801b19ac86aa Mon Sep 17 00:00:00 2001 From: Kevin Adams Date: Sun, 31 May 2026 23:13:21 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20ADR-009=20draft=20+=20versioning=20stra?= =?UTF-8?q?tegy=20=E2=80=94=20v3.1=20PVE=209=20only,=20v4.0=20WebSocket?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-009 (draft) supersedes ADR-008 with confirmed PVE 9 support, the lun integer fix approach, and a clear version→PVE support mapping: - v3.0.x: PVE 8 + PVE 9, REST API - v3.1.x: PVE 9 only, REST API, api() bump, snapshots - v4.0.x: WebSocket JSON-RPC 2.0 — genuine architectural change, major version ROADMAP: v3.2.0 renamed to v4.0.0 for WebSocket milestone; v3.1 scope updated to document PVE 8 drop and reasons. Co-Authored-By: Claude Sonnet 4.6 --- .../adrs/ADR-009-pve-version-support-v3.md | 86 +++++++++++++++++++ ROADMAP.md | 17 +++- 2 files changed, 99 insertions(+), 4 deletions(-) create mode 100644 .claude/cos/adrs/ADR-009-pve-version-support-v3.md diff --git a/.claude/cos/adrs/ADR-009-pve-version-support-v3.md b/.claude/cos/adrs/ADR-009-pve-version-support-v3.md new file mode 100644 index 0000000..4d5de0b --- /dev/null +++ b/.claude/cos/adrs/ADR-009-pve-version-support-v3.md @@ -0,0 +1,86 @@ +# ADR-009: PVE Version Support Matrix — v3.x and v4.0 Versioning Strategy + +**Date**: 2026-05-31 +**Status**: Draft +**Deciders**: Kevin Adams +**Supersedes**: ADR-008 (pending acceptance of this ADR) + +## Context + +ADR-008 established the PVE version support matrix for v3.0. Three things emerged +during v3.0 development that require revised decisions: + +1. **PVE 9 confirmed working** — pve01-hq was upgraded to PVE 9.2.3. One blocking + bug was found (#266, `lun` integer type in QEMU blockdev JSON) and fixed by + overriding `qemu_blockdev_options` in TrueNAS.pm. + +2. **`api()` version conflict** — PVE 8 has `APIVER = 11`; PVE 9 has `APIVER = 14`. + A single `api()` return value cannot satisfy both without warning (return 11) + or fatally failing on PVE 8 (return 14). The warning is cosmetic and deferred. + +3. **WebSocket API scope** — TrueNAS SCALE 25.04+ exposes a new JSON-RPC 2.0 + WebSocket API alongside the REST API. This is a new transport layer, not an + incremental improvement. It warrants a major version bump when adopted. + +4. **ADR-008 stated `volume_snapshot*` must ship in v3.0** — deferred to v3.1 (#234). + +## Decision + +### Version → PVE support mapping + +| Version | PVE support | TrueNAS API | Notes | +|---------|------------|-------------|-------| +| v3.0.x | PVE 8.x + PVE 9.x | REST (v2.0) | `api()` = 11; cosmetic warning on PVE 9 | +| v3.1.x | PVE 9.x only | REST (v2.0) | `api()` bumped to PVE 9 APIVER; PVE 8 dropped | +| v4.0.x | PVE 9.x+ | WebSocket JSON-RPC 2.0 | New transport; genuine breaking change | + +### Why v3.1 drops PVE 8 (not v4.0) + +Dropping an EOL'd host platform is a support boundary decision, not a behavior +or API change. Users on PVE 8 stay on v3.0.x, which continues to work. The +plugin's `storage.cfg` format, TrueNAS API calls, and iSCSI behavior are +unchanged. Minor version bump is appropriate. + +**PVE 8 EOL: 2026-08-31.** v3.1 must ship before that date so users have time +to migrate to PVE 9 before their platform is unsupported. + +### Why v4.0 for WebSocket API + +WebSocket JSON-RPC 2.0 is a fundamentally different transport layer. Adopting it +may require dropping or conditionally supporting the REST API for newer SCALE +versions, changing how the plugin establishes connections, and potentially +branching code paths per TrueNAS variant. This is an architectural change that +warrants a major version, not a minor one. + +### v3.0.x specifics + +- `api()` returns `11` — works on PVE 8 (exact match) and PVE 9 (within APIAGE range) +- PVE 9 emits "older storage API, upgrade recommended" — cosmetic, documented, expected +- `qemu_blockdev_options` override present — workaround for PVE `Plugin.pm` bug (#266) + - Remove when Proxmox fixes `lun => int($3)` in their code (see TrueNAS.pm comment) +- `volume_snapshot*` not implemented — deferred to v3.1 (#234) + +### v3.1.x specifics + +- Minimum PVE: 9.x +- `api()` bumped to match PVE 9's `APIVER` at time of release +- `volume_snapshot*` implementation (#234) +- Evaluate removal of `qemu_blockdev_options` override if Proxmox has fixed upstream +- `api()` bump tracked in #270 + +## Consequences + +- v3.0.0 can be tagged — PVE 8 + PVE 9 both verified +- v3.1.0 milestone must add `api()` bump (#270) as a prerequisite +- ROADMAP updated: v3.2.0 renamed to v4.0.0 for WebSocket API (#243) +- ADR-008 marked Superseded when this ADR is accepted + +## Alternatives Considered + +**v4.0 for dropping PVE 8**: Rejected — dropping an EOL platform is not a +behavioral break. Users on PVE 8 keep using v3.0.x. A major version would +signal something fundamentally different about what the plugin does. + +**v3.x for WebSocket API**: Rejected — WebSocket JSON-RPC 2.0 changes the +transport layer and may require dropping or splitting REST API support. That is +an architectural change deserving a major version signal to users. diff --git a/ROADMAP.md b/ROADMAP.md index 8fa4bbf..b248716 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -74,22 +74,31 @@ gh repo rename truenas-proxmox --repo TheGrandWazoo/freenas-proxmox --- -## Upcoming — v3.1.0 (Snapshots + PVE 9 hardening) +## Upcoming — v3.1.0 (PVE 9 only + Snapshots) -**Target:** Before PVE 8 EOL — 2026-08-31 +**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 + +v3.1 is the first release that requires PVE 9. Dropping PVE 8 allows: +- Bumping `api()` to match PVE 9's `APIVER` (silences "older storage API" warning — see [#270](https://github.com/TheGrandWazoo/freenas-proxmox/issues/270)) +- Implementing snapshot-as-volume-chains (PVE 9 feature) +- Removing the `qemu_blockdev_options` override if Proxmox fixes `Plugin.pm` upstream | # | Title | |---|-------| | [#234](https://github.com/TheGrandWazoo/freenas-proxmox/issues/234) | Snapshot interface (Snapshot-as-Volume-Chains, PVE 9.0+) | +| [#270](https://github.com/TheGrandWazoo/freenas-proxmox/issues/270) | Bump `api()` to PVE 9 APIVER — requires dropping PVE 8 | | [#249](https://github.com/TheGrandWazoo/freenas-proxmox/issues/249) | Per-variant dispatch (TrueNAS-Core.pm / TrueNAS-Scale.pm) — evaluate | | [#256](https://github.com/TheGrandWazoo/freenas-proxmox/issues/256) | Multipath support | --- -## Upcoming — v3.2.0 (WebSocket API, SCALE 25.x) +## Upcoming — v4.0.0 (WebSocket API, SCALE 25.x) **Target:** After PoC testing on SCALE 25.04 Fangtooth and 25.10 Goldeye -**Scope:** TBD pending PoC results +**Scope:** TBD pending PoC results +**Why major version:** WebSocket JSON-RPC 2.0 is a new transport layer — a genuine architectural change, not a support boundary adjustment. | # | Title | |---|-------|