Proxmox Live Migration Between Clusters: Moving VMs Without Downtime

Classic live migration inside a Proxmox cluster has been routine for years: one click in the web interface, and the VM moves to another node without interruption. As soon as the machine has to leave the cluster — for a hardware refresh, a datacenter move, or splitting a cluster that has grown too large — things used to get painful: backup, restore, reboot, downtime. With qm remote-migrate in Proxmox VE 8, that gap is closed. VMs can now be moved live between two fully independent clusters, including RAM contents and active database connections.

At DATAZONE we have been using the feature in production for migrations that previously only worked during a weekend maintenance window. This article shows how the command works, what preparation is needed, and where the limits are.

What qm remote-migrate actually does

Inside a cluster, all nodes share a common configuration database (pmxcfs) and Corosync quorum. Between two separate clusters this trust relationship does not exist. qm remote-migrate solves the problem through an HTTPS API connection with token authentication. The source node opens a WebSocket to the target cluster, transfers the VM configuration, replicates the disks over the network, and finally performs the classic QEMU live-migration handshake.

The result: the same VM ID or a new one, the same MAC address, the RAM travels along — open SSH sessions and database transactions survive the move. Inside the guest, only one anomaly is visible: the clock makes a small jump, nothing else.

Prerequisites and preparation

Before the actual command can run, a few things have to be in place. Here is the checklist.

Component	Requirement	Note
PVE version	8.1 or newer on both sides	We recommend 8.4+ due to NVMe mapping fixes
Network	Direct HTTPS reachability on port 8006	VPN or MPLS link, at least 1 Gbit/s
Storage	Compatible types on target side	LVM-Thin, ZFS, Ceph RBD are supported
API token	On target cluster with sufficient rights	Disable privilege separation
Fingerprint	SHA-256 of the target certificate	Read from pveproxy-ssl.pem

The API token is created on the target cluster as a realm user, typically migrate@pam with a token called xfer. Important: when creating the token, the “Privilege Separation” checkbox must be cleared, otherwise the role permissions will not apply.

Establishing certificate trust

Since the clusters do not share a common CA, the source cluster must explicitly know the fingerprint of the target. The easiest way to get it:

# On a target cluster node, read the fingerprint
openssl x509 -in /etc/pve/local/pveproxy-ssl.pem \
  -noout -fingerprint -sha256 | sed 's/://g'

# Example output
SHA256 Fingerprint=A1B2C3D4E5F6...

You will need this string for the migration command. If you run your own PKI with Let’s Encrypt or an internal CA, you can also fetch the fingerprint via the ACME interface — what matters is that the value matches the currently active certificate exactly.

The migration command in practice

Once token and fingerprint are in place, the actual migration is a single command on the source node. Here is a full example for a VM with two disks and one network card:

qm remote-migrate 142 248 \
  'host=pve-target.example.com,apitoken=PVEAPIToken=migrate@pam!xfer=8f3c...,fingerprint=A1B2C3D4E5F6...' \
  --target-bridge vmbr0 \
  --target-storage 'local-lvm:nvme-pool,backup-disk:hdd-pool' \
  --online

What is happening here:

• 142 is the VM ID on the source, 248 the new ID on the target
• host=... contains FQDN, token and fingerprint of the target cluster
• --target-bridge maps the source network to the target bridge
• --target-storage allows per-disk storage mappings
• --online turns an offline move into a real live migration

For a 32 GB VM with 200 GB of disks over a 10 Gbit link, we expect around 5—8 minutes total. The actual switch-over phase, in which the VM pauses briefly, is well below one second.

Common pitfalls

In projects we keep running into the same obstacles. The most important points from our practice:

Forgotten storage mapping: If the source is called local-zfs and the target tank-ssd, this must be mapped explicitly via --target-storage. Without a mapping, the migration aborts with a storage-not-found error.

Incompatible CPU type: If the VM is set to host CPU and the source and target CPU generations differ, the live switch will fail. Before migration we set a common denominator like x86-64-v3 and restart the VM once — after that the migration runs cleanly.

Snapshots and templates: VMs with active snapshots or those that serve as templates themselves cannot be remote-migrated. Delete snapshots first, clone templates and only migrate the clone.

Bandwidth limit: By default the migration uses all available bandwidth. With --bwlimit 500000 (500 MB/s) you can spare the production network.

HA manager: If the VM is under HA control, it must be removed from the HA group beforehand. Add it back in the target cluster after a successful migration.

Real-world use cases

Three typical scenarios in which we use cross-cluster migration:

1. Hardware refresh without a maintenance window: The new cluster runs in parallel with the old one, both serve production. VMs move over gradually, the old cluster empties node by node and gets decommissioned.
2. Datacenter relocation: Site change from location A to B with a short fibre link in between. VMs migrate live, nobody notices anything.
3. Cluster split: A cluster that has grown too large is split into two smaller units — for example to separate tenants or reduce quorum complexity.

In all three cases, only backup-restore with subsequent reboot was possible in the past. Today the application keeps running.

Limits and recommendations

Despite all progress, qm remote-migrate is not a silver bullet. For very large disks beyond 10 TB we recommend pre-syncing via pvesm export and pvesm import, after which only the RAM delta remains. GPU passthrough VMs also cannot be live migrated — the device context is lost during the switch.

For planning larger migrations we recommend running a pilot system with test load beforehand. In our Proxmox consulting projects we routinely build an identically configured test VM, migrate it together with a load generator, and measure switch-over times — only then do we touch the production workloads. Combined with a solid backup concept on Proxmox Backup Server, the risk profile is significantly better than a classic migration with downtime.

Conclusion

qm remote-migrate closes one of the last big gaps in the Proxmox ecosystem. Hardware refresh, site change and cluster restructuring can now be done without nightly maintenance windows — provided API token, certificate trust and storage mappings are in order.

DATAZONE supports you in planning and executing cross-cluster migrations, building parallel Proxmox environments, and ensuring a smooth transition without business interruption. Get in touch at kontakt@datazone.de — we analyse your starting point and design a migration path that fits your service hours.