docs: ADR-009 draft + versioning strategy — v3.1 PVE 9 only, v4.0 WebSocket
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 <noreply@anthropic.com>
This commit is contained in:
Kevin Adams
parent
84d459da02
commit
4e621a215c
|
|
@ -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.
|
||||
13
ROADMAP.md
13
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
|
||||
**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
|
||||
**Why major version:** WebSocket JSON-RPC 2.0 is a new transport layer — a genuine architectural change, not a support boundary adjustment.
|
||||
|
||||
| # | Title |
|
||||
|---|-------|
|
||||
|
|
|
|||
Loading…
Reference in New Issue