From b41fefb72bdacb0450da7081b99b2716a375c7b2 Mon Sep 17 00:00:00 2001 From: Kevin Adams Date: Tue, 19 May 2026 18:33:13 -0400 Subject: [PATCH] docs: add PVE version compatibility warnings across all user touchpoints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Users on unsupported PVE versions now get clear guidance at every layer — README, install time, and GitHub release notes — rather than silently failing or getting confusing patch errors. - README: replace bare compatibility table with a full matrix and prominent callout blocks for PVE 7 (last v2.x), PVE 8 (EOL 2026-08-31), PVE 9+ (use v3.0), and PVE ≤6 (unsupported) - postinst: add check_pve_version() that exits on PVE < 7, warns loudly on PVE 7 (stay on v2.x, do not upgrade to v3.0), notes the PVE 8 EOL date, and warns on PVE 9+ (v2.x not supported) - build.yml release template: add a version compatibility table so every GitHub release prominently states who should and should not install it Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/build.yml | 20 ++++++++++++++----- README.md | 33 ++++++++++++++++++++++++++++---- packaging/DEBIAN/postinst | 38 +++++++++++++++++++++++++++++++++++++ 3 files changed, 82 insertions(+), 9 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 91abf7f..239caaa 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -315,18 +315,28 @@ jobs: body: | ## freenas-proxmox v${{ needs.build.outputs.version }} - > **Edit before publishing** — fill in tested versions below. + > **Edit before publishing** — fill in tested versions and remove inapplicable notices below. - ### Supported Proxmox VE Versions - - Proxmox VE 8.x (tested: ) + ### ⚠️ Version Compatibility Notices + + | Your Proxmox VE | What to do | + |:----------------|:-----------| + | **PVE 9+** | ❌ Do **not** install v2.x — use v3.0 when released | + | **PVE 8.x** | ✅ Supported. Note: PVE 8 EOL is **2026-08-31** — plan your upgrade to PVE 9 + v3.0 | + | **PVE 7.x** | ⚠️ Best-effort only. This is the **last v2.x release** supporting PVE 7. Do **not** upgrade to v3.0 — stay on v2.x | + | **PVE 6 or older** | ❌ Not supported | + + ### Tested Proxmox VE Versions + - Proxmox VE 8.4.x (tested: ) + - Proxmox VE 8.3.x (tested: ) - Proxmox VE 7.x (best-effort: ) - ### Supported TrueNAS Versions + ### Tested TrueNAS Versions - TrueNAS CORE: - TrueNAS SCALE: ### Installation - See [README](https://github.com/TheGrandWazoo/freenas-proxmox#installation). + See [README → Installation](https://github.com/TheGrandWazoo/freenas-proxmox#installation). ### Changes See [CHANGELOG.md](https://github.com/TheGrandWazoo/freenas-proxmox/blob/master/CHANGELOG.md#unreleased). diff --git a/README.md b/README.md index bc83971..c1246d3 100644 --- a/README.md +++ b/README.md @@ -41,10 +41,35 @@ Proxmox VE's built-in ZFS-over-iSCSI storage type uses SSH to manage LUNs on the ## Compatibility -| Plugin Version | Proxmox VE | TrueNAS CORE | TrueNAS SCALE | -|:--------------:|:----------:|:------------:|:-------------:| -| **3.x** (upcoming) | 8.x | 13.0-U6+ | 23.10 (Cobia)+, 24.04 (Dragonfish)+ | -| **2.x** (current stable) | 7.x, 8.x | 11.3+ | 22.02+ | +### Version Matrix + +| Plugin Version | Proxmox VE | TrueNAS CORE | TrueNAS SCALE | Status | +|:--------------:|:----------:|:------------:|:-------------:|:------:| +| **3.x** *(upcoming)* | 8.x, 9.x | 13.0-U6+ | Cobia (23.10)+, Dragonfish (24.04)+ | In development | +| **2.x** *(current)* | 7.x ⚠️, 8.0–8.3 ✅, 8.4.x ✅ | 11.3+ | 22.02+ | Active | +| **1.x** *(legacy)* | 5.x, 6.x | 11.x | — | Unsupported | + +### Important Version Notices + +> **Proxmox VE 7 users** +> +> v2.x is the **last release series that supports PVE 7**. PVE 7 support is best-effort only — no new patches will be developed for it. +> +> **Do not upgrade to v3.0** when it releases — v3.0 requires Proxmox VE 8 or later. Stay on the latest v2.x release. + +> **Proxmox VE 8 users** +> +> Proxmox VE 8 reaches **end-of-life on 2026-08-31**. Plan your upgrade to PVE 9 before that date. +> +> v2.x works on PVE 8. When you upgrade to PVE 9, migrate to v3.0 (coming before the EOL date). + +> **Proxmox VE 9+ users** +> +> v2.x is **not supported on PVE 9**. Use v3.0 when it is released. Do not install v2.x on a PVE 9 node. + +> **Proxmox VE 5 or 6 users** +> +> These versions are not supported. PVE 5 reached end-of-life in 2019, PVE 6 in 2022. Please upgrade your Proxmox VE installation. Check the [Releases page](https://github.com/TheGrandWazoo/freenas-proxmox/releases) for the specific Proxmox and TrueNAS versions tested against each release. diff --git a/packaging/DEBIAN/postinst b/packaging/DEBIAN/postinst index ee21871..17d0d81 100644 --- a/packaging/DEBIAN/postinst +++ b/packaging/DEBIAN/postinst @@ -106,11 +106,49 @@ restart_pve_services() { log "Done. Refresh your Proxmox browser tab to load the updated UI." } +# Warn the user if their PVE version is outside the supported range for this +# plugin version. Exits non-zero (aborting the install) only for versions so +# old that no patches exist (< 7). +check_pve_version() { + local major="$1" + + if [ "$major" -lt 7 ]; then + log "ERROR: Proxmox VE ${major}.x is not supported by this plugin." + log " PVE 5 and 6 reached end-of-life in 2019 and 2022 respectively." + log " Please upgrade your Proxmox VE installation before installing this plugin." + exit 1 + fi + + if [ "$major" -eq 7 ]; then + log "WARNING: *** Proxmox VE 7 — Important Notice ***" + log "WARNING: v2.x is the LAST release series that supports Proxmox VE 7." + log "WARNING: PVE 7 support is best-effort only; no new patches will be" + log "WARNING: developed for it." + log "WARNING: When v3.0 is released, DO NOT upgrade to it — v3.0 requires" + log "WARNING: Proxmox VE 8 or later. Stay on the latest v2.x release." + fi + + if [ "$major" -eq 8 ]; then + log "INFO: Proxmox VE 8 reaches end-of-life on 2026-08-31." + log "INFO: Plan your upgrade to PVE 9 and migration to v3.0 before that date." + fi + + if [ "$major" -ge 9 ]; then + log "WARNING: *** Proxmox VE ${major}.x — Not Supported by v2.x ***" + log "WARNING: This plugin (v2.x) is not supported on Proxmox VE 9 or later." + log "WARNING: Patches may fail to apply or the UI may not work correctly." + log "WARNING: Please use v3.0 of this plugin, which is designed for PVE 9+." + log "WARNING: See: https://github.com/TheGrandWazoo/freenas-proxmox/releases" + log "WARNING: Continuing anyway — but expect problems." + fi +} + # ── Entry point ────────────────────────────────────────────────────────────── major=$(detect_pve_major) pve_mgr_minor=$(detect_pve_manager_minor) log "Proxmox VE major version: ${major}, pve-manager: ${pve_mgr_minor}" +check_pve_version "$major" case "$1" in