104 lines
4.6 KiB
Markdown
104 lines
4.6 KiB
Markdown
# 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.
|