From 61373f9db78b8804f200e6ba55a406661194abf4 Mon Sep 17 00:00:00 2001 From: Kevin Adams Date: Sat, 6 Jun 2026 13:59:19 -0400 Subject: [PATCH] docs: add Cloudsmith migration guide and upgrade-paths reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: new "Migrating from Cloudsmith" section with v2 and v3 command sequences and a one-line reason (Cloudsmith being phased out) - docs/upgrade-paths.md: full matrix of every starting version × repo combination with links to the right guide; v4.x rows stubbed with placeholder instructions so users know what's coming and where to look Co-Authored-By: Claude Sonnet 4.6 --- README.md | 50 ++++++++++++++++++++ docs/upgrade-paths.md | 103 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 153 insertions(+) create mode 100644 docs/upgrade-paths.md diff --git a/README.md b/README.md index 53b8df4..8b2c8ab 100644 --- a/README.md +++ b/README.md @@ -162,6 +162,56 @@ https://thegrandwazoo.github.io/freenas-proxmox main main" \ sudo apt update ``` +### Migrating from Cloudsmith + +> Cloudsmith is being phased out. GitHub Pages is the permanent home for this project's packages. + +If you installed from the Cloudsmith apt repo, swap your source to GitHub Pages. Your installed package is not affected — this only changes where future updates come from. + +**On v3.x (Cloudsmith stable):** + +```bash +# Remove the old Cloudsmith source +sudo rm -f /etc/apt/sources.list.d/truenas-proxmox*.list +sudo rm -f /usr/share/keyrings/ksatechnologies-truenas-proxmox*.gpg + +# Import the GitHub Pages GPG key +curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \ + | gpg --dearmor \ + | sudo tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null + +# Point to the v3 dist track +echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \ +https://thegrandwazoo.github.io/freenas-proxmox v3 main" \ + | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list + +sudo apt update +``` + +**On v2.x (Cloudsmith stable) — staying on v2:** + +```bash +# Remove the old Cloudsmith source +sudo rm -f /etc/apt/sources.list.d/freenas-proxmox*.list /etc/apt/sources.list.d/truenas-proxmox*.list +sudo rm -f /usr/share/keyrings/ksatechnologies-truenas-proxmox*.gpg + +# Import the GitHub Pages GPG key +curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \ + | gpg --dearmor \ + | sudo tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null + +# Point to the v2 dist track (v2.x only — you will never receive a v3 package) +echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \ +https://thegrandwazoo.github.io/freenas-proxmox main main" \ + | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list + +sudo apt update +``` + +For a full upgrade path matrix — including what to do when v4 ships — see [docs/upgrade-paths.md](docs/upgrade-paths.md). + +--- + ### Testing / Beta Release For early access to new features (may be unstable): diff --git a/docs/upgrade-paths.md b/docs/upgrade-paths.md new file mode 100644 index 0000000..aa0b196 --- /dev/null +++ b/docs/upgrade-paths.md @@ -0,0 +1,103 @@ +# Upgrade Paths + +Quick reference for every migration scenario. Find your current version and repo source in the table, then follow the link for step-by-step instructions. + +--- + +## Where am I, and where do I go? + +| Current version | Current repo | → Stay on current major | → Move to v3.x | → Move to v4.x | +|---|---|---|---|---| +| **v2.x** | Cloudsmith stable | [Swap repo to GitHub Pages `main`](#cloudsmith-to-github-pages) | [Swap repo + config migration](migrating-from-v2.md) | TBD when v4 ships — will require v3 config first | +| **v2.x** | GitHub Pages `main` | Already on correct repo ✅ | [Config migration only](migrating-from-v2.md) | TBD when v4 ships — will require v3 config first | +| **v3.x** | Cloudsmith stable | [Swap repo to GitHub Pages `v3`](#cloudsmith-to-github-pages) | Already on v3 — swap repo only | [Change dist track to `v4` + v3→v4 guide](#future-v4) | +| **v3.x** | GitHub Pages `v3` | Already on correct repo ✅ | Already here ✅ | [Change dist track to `v4` + v3→v4 guide](#future-v4) | + +**Not sure which version you have?** Run this on any Proxmox node: +```bash +dpkg -l truenas-proxmox freenas-proxmox 2>/dev/null | grep '^ii' +``` + +**Not sure which repo you're using?** +```bash +cat /etc/apt/sources.list.d/truenas-proxmox*.list /etc/apt/sources.list.d/freenas-proxmox*.list 2>/dev/null +``` + +--- + +## Cloudsmith → GitHub Pages {#cloudsmith-to-github-pages} + +> Cloudsmith is being phased out. GitHub Pages is the permanent home for this project's packages. Your installed package is not affected — this only changes where future updates come from. + +Full instructions are in the [README — Migrating from Cloudsmith](../README.md#migrating-from-cloudsmith) section. + +In short: +1. Remove your existing Cloudsmith source file from `/etc/apt/sources.list.d/` +2. Remove the old Cloudsmith keyring from `/usr/share/keyrings/` +3. Import the GitHub Pages GPG key to `/etc/apt/keyrings/truenas-proxmox.gpg` +4. Add the GitHub Pages source pointing at the right dist track (`main` for v2, `v3` for v3) +5. Run `apt update` + +--- + +## What changes between major versions + +| | v2.x → v3.x | v3.x → v4.x (future) | +|---|---|---| +| **Breaking change?** | Yes — auth model, iSCSI model, package name | Yes — WebSocket API replaces REST | +| **In-place upgrade?** | No — VM disks must be moved | TBD | +| **Plugin restarts VMs?** | No — Move Disk is live | TBD | +| **Config changes?** | Yes — API key replaces username/password | TBD | +| **Full guide** | [migrating-from-v2.md](migrating-from-v2.md) | Will be added when v4 ships | + +--- + +## v2.x → v3.x + +See [migrating-from-v2.md](migrating-from-v2.md) for the full step-by-step guide. + +High-level steps: +1. Install `truenas-proxmox` on every Proxmox node (from GitHub Pages `v3` dist) +2. Create a TrueNAS API key +3. Add a new v3 storage entry in Proxmox (keep the old v2 entry running alongside) +4. Move VM disks one at a time using Proxmox Move Disk (VMs stay running) +5. Remove the old v2 storage entry once all disks are moved + +**Do not run `apt upgrade` from a v2 Cloudsmith install without reading the migration guide first.** v3.0 is a breaking change — your storage will need reconfiguration. + +--- + +## v3.x → v4.x (future) {#future-v4} + +v4.0 will replace the TrueNAS REST API with the WebSocket JSON-RPC 2.0 API introduced in TrueNAS SCALE 25.04. This is an architectural change and will be a major version with its own migration guide. + +When v4.0 ships, this section will be updated with: +- What changes in v4.0 (API model, config fields, compatibility matrix) +- Whether an in-place upgrade is possible +- Step-by-step migration from v3.x +- Step-by-step migration from v2.x (if a direct v2→v4 path is supported) + +**To receive v4.x packages when they ship**, you will need to change your `sources.list` dist track from `v3` to `v4`: + +```bash +# When v4.0 is released — do NOT run this until the v4 migration guide is published +echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \ +https://thegrandwazoo.github.io/freenas-proxmox v4 main" \ + | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list +sudo apt update +``` + +`apt upgrade` on the `v3` dist track will never pull in a v4 package — you must explicitly change the dist track. This is intentional. + +--- + +## Dist track reference + +| Dist track | Contains | Who should use it | +|---|---|---| +| `main` | v2.x packages only | Users staying on v2.x | +| `v2` | v2.x packages (alias for `main`) | Same as `main` — explicit pin | +| `v3` | v3.x packages only | All current v3 installs | +| `v4` | v4.x packages only | Added when v4.0 ships | + +Packages on one dist track are never promoted to another. Changing major versions always requires an explicit `sources.list` edit.