public_git
/
freenas-proxmox
mirror of https://github.com/TheGrandWazoo/freenas-proxmox.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: add Cloudsmith migration guide and upgrade-paths reference 

- 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 <noreply@anthropic.com>
This commit is contained in:
Kevin Adams 2026-06-06 13:59:19 -04:00
parent d3dfcb4452
commit 61373f9db7
2 changed files with 153 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@ -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):

103
docs/upgrade-paths.md Normal file
View File

@ -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.