From 0a8e7e7484def696ebb33acd56f700c83240aceb Mon Sep 17 00:00:00 2001 From: Kevin Adams Date: Mon, 25 May 2026 08:34:40 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20add=20TPM=20limitation=20callout=20and?= =?UTF-8?q?=20v2.x=E2=86=92v3.0=20migration=20path=20(#260,=20#228,=20#252?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add TPM state disk known limitation to v3.0 Prerequisites with clear workaround (local-lvm or NFS for tpmstate0, shared storage for live migration with TPM) - Expand Upgrading section with v2.x→v3.0 Move Disk migration path, confirmed tested on PVE 8.4 with CORE 13.0-U6 and SCALE 24.10 - Note in-place rename is not supported; Move Disk is the supported path Closes #260, #228, #252 Co-Authored-By: Claude Sonnet 4.6 --- README.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d5b1a54..a66a759 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,14 @@ v3.0 is a fully API-driven custom storage plugin. No SSH keys required. Copy the key — you will need it during storage configuration in Proxmox. +> **Known limitation — TPM state disks** +> +> `tpmstate0` (virtual TPM) disks **cannot** be stored on v3.0 iSCSI storage. The `swtpm` backend requires a local filesystem path and cannot use the `iscsi://` URIs that v3.0 provides to QEMU. +> +> If your VM uses Secure Boot or TPM, store the `tpmstate0` disk on a separate storage (e.g. `local-lvm` or NFS). All other disk types — virtio, scsi, IDE, EFI — work normally. +> +> For live VM migration with TPM, the TPM state disk must also be on shared filesystem storage (NFS or CephFS), not on this plugin's storage. + ### v2.x (current stable) 1. **SSH keys** configured between Proxmox and TrueNAS — required for ZFS pool listing by the Proxmox core (see the [Proxmox wiki](https://pve.proxmox.com/wiki/Storage:_ZFS_over_iSCSI), section starting with `mkdir /etc/pve/priv/zfs`). @@ -205,12 +213,41 @@ Edit `/etc/pve/storage.cfg` on any cluster node and change `blocksize 8192` to ` ## Upgrading -The package integrates with Proxmox VE's standard upgrade mechanism. On `apt upgrade`, the package will automatically re-apply any patches needed after a Proxmox VE update: +### v2.x → v2.x (patch / minor upgrade) + +Standard apt upgrade — the package re-applies any patches needed after a Proxmox VE update automatically: ```bash apt update && apt full-upgrade ``` +### v2.x → v3.0 (migration) + +v3.0 is a different storage plugin type (`PVE::Storage::Custom::TrueNAS`) and uses a different architecture (per-VM iSCSI targets, `iscsi://` paths). There is no in-place upgrade — disk data stays on TrueNAS and you move VM disks across using Proxmox's built-in **Move Disk** function. + +> **Tested migration path (confirmed in lab):** +> Migrating live VM disks from a v2.x storage to a v3.0 storage via Move Disk was validated on Proxmox VE 8.4 with TrueNAS CORE 13.0-U6 and TrueNAS SCALE 24.10. VMs remained running throughout the migration. + +#### Step-by-step + +1. **Install v3.0** on all Proxmox nodes (see [Installation](#installation) — use the testing channel until v3.0 is stable-released). + +2. **Add a new v3.0 storage** in Proxmox (*Datacenter → Storage → Add → TrueNAS (ZFS/iSCSI)*). Use the same TrueNAS pool as your existing v2.x storage. Give it a distinct ID (e.g. `truenas-v3`). + +3. **For each VM**, move its disks from the v2.x storage to the new v3.0 storage: + - Select the VM → **Hardware** tab + - Select the disk → **Move Disk** + - Choose the new v3.0 storage as the target + - Check **Delete source** if you want the old zvol removed after the move + + Repeat for each disk (including EFI disk if present). VMs can remain running during Move Disk. + +4. **Verify** the VM boots and its disks are accessible after migration. + +5. **Remove the v2.x storage** from Proxmox once all VMs are migrated (*Datacenter → Storage → Remove*). The iSCSI targets and extents that belonged to the old storage will need to be cleaned up from TrueNAS manually if they were not auto-removed. + +> **Note:** EFI disks (`efidisk0`) and data disks can be migrated with Move Disk. TPM state disks (`tpmstate0`) must stay on local-lvm or NFS — see the [TPM limitation](#v30-upcoming) in Prerequisites. + --- ## Uninstalling