3.0 KiB
ADR-008: PVE Version Support Matrix
Date: 2026-05-19
Status: Accepted
Deciders: Kevin Adams
Context
Proxmox VE releases 8.4, 9.0, and 9.1 introduced storage-subsystem changes that affect which PVE versions the plugin must support and under what constraints. Specifically:
- PVE 8.4 broke our existing
pvemanagerlib.jspatch (issue #223) - PVE 9.0 introduced Snapshot-as-Volume-Chains for thick-provisioned iSCSI
- PVE 9.1 is the current stable release as of 2026-05-19
The plugin currently ships a single patch per major PVE version (7.x, 8.x).
Phase 3 (v3.0) eliminates all patches by using the proper PVE::Storage::Custom
plugin interface — but we need a clear decision on which PVE versions each release
series must support.
Decision
v2.x (current) — patch-based
| PVE version | Support level | Notes |
|---|---|---|
| PVE 7.x | Best-effort | No active testing; patches ship but may lag |
| PVE 8.0–8.3 | Supported | Existing patch works |
| PVE 8.4.x | Supported (blocked) | pvemanagerlib.js patch broken — fix tracked in #223 |
| PVE 9.x | Not supported | pvemanagerlib.js too diverged; v3.0 is the answer |
v2.3.0 is the last planned release to ship patched versions of PVE system files. It will support PVE 7 (best-effort) and PVE 8 (fully). PVE 9.x users should wait for v3.0 or run v2.x in degraded mode (plugin works; UI dropdown may not show).
v3.0.x — custom plugin, no patches
| PVE version | Support level | Notes |
|---|---|---|
| PVE 8.x | Supported (core) | Custom plugin interface available since PVE 7 |
| PVE 9.0+ | Fully supported | Includes snapshot-as-volume-chains integration |
| PVE 7.x | Not supported | v3.0 requires API features not available in PVE 7 |
Minimum supported PVE for v3.0: 8.x (core), 9.0 (snapshots).
Snapshot support (volume_snapshot, volume_snapshot_rollback,
volume_snapshot_delete) requires PVE 9.0 Snapshot-as-Volume-Chains and will
be gated at runtime: the methods will be present but return an appropriate error
on PVE < 9.0.
Consequences
- Issue #223 (pvemanagerlib.js PVE 8.4 fix) must ship in v2.3.0
- v3.0.0 must implement the full
PVE::Storage::Custominterface includingvolume_snapshot*methods (initially returning unsupported on PVE < 9.0) - CI for v3.0 must test against both PVE 8.x and PVE 9.x targets
- The v3.0.0 milestone description and related issues should call out PVE 9.0 as the target for snapshot feature parity
- PVE 9.x users stuck on v2.x should be documented in a known-limitations note
Alternatives Considered
Support PVE 9.x in v2.x via a new patch: rejected — pvemanagerlib.js diverged significantly in 9.0; maintaining a third patch variant adds fragility without addressing the root cause (patch-based approach).
Make PVE 9.0 the minimum for v3.0: rejected — custom storage plugins work in PVE 8.x and dropping 8.x support would leave a large user base with no upgrade path until they upgrade PVE.