Skip to content

Cross-Hypervisor Migration

PegaProx supports migrating virtual machines across different hypervisor platforms-ESXi, Proxmox VE, and XCP-ng-in any supported direction. This eliminates vendor lock-in and enables gradual platform transitions without manual disk conversion or VM recreation.

Supported Migration Paths

Source Target Notes
ESXi Proxmox VE VMDK → qcow2/raw conversion. Requires SSH on ESXi host.
ESXi XCP-ng VMDK → VHD conversion. SSH required on ESXi side.
XCP-ng Proxmox VE VHD → qcow2/raw conversion. Uses XAPI for disk export.
Proxmox VE XCP-ng qcow2/raw → VHD conversion. Requires source_node parameter.

How It Works

Plan Generation

The plan endpoint analyzes the source VM’s configuration-CPU, memory, disks, network interfaces, OS type-and generates a migration plan with translated hardware settings for the target hypervisor.

Hardware Translation

CPU types, disk bus controllers (IDE, SCSI, VirtIO), and NIC models are automatically mapped to the closest equivalent on the target platform. OS type identifiers are translated between hypervisor-specific formats.

Disk Export & Conversion

Disks are streamed from the source hypervisor and converted to the target format in a single pass. For ESXi sources, this uses SSH-based VMDK access. For XCP-ng, the XAPI export interface is used.

VM Creation & Import

A new VM is created on the target cluster with the translated configuration, and the converted disks are imported into the specified target storage pool.

Hardware Mapping Reference

Component ESXi Proxmox VE XCP-ng
Disk format VMDK (thin/thick) qcow2 / raw VHD
Disk bus LSI Logic SAS / PVSCSI VirtIO SCSI / IDE / SATA xvd (PV) / hd (HVM)
NIC model VMXNET3 / E1000 VirtIO / E1000 / RTL8139 netfront (PV) / RTL8139 (HVM)
CPU type Host passthrough kvm64 / host / custom Host passthrough
OS type (Linux) otherGuest64 l26 Other install media
OS type (Windows) windows9_64Guest win10 / win11 Windows 10 / 11

Requirements & Limitations

  • ESXi sources require SSH access for direct VMDK streaming
  • Proxmox VE → XCP-ng requires the source_node parameter (disks are node-local)
  • Same hypervisor type migrations are not supported-use native migration tools
  • GPU passthrough and SR-IOV devices are not migrated. Reconfigure manually on target.
  • Only current VM state is migrated. Snapshots are not transferred.
  • From 1.3, an ESXi source is authorized by its ESXi permissions: copying a VM needs vmware.vm.migrate on it (or an ESXi ACL that grants it), removing the source needs vmware.vm.manage. The Proxmox vm.* permissions no longer count for ESXi guests.
  • From 1.3, a Proxmox VE → XCP-ng migration with remove source checks again, right before it deletes the source, that the VMID still belongs to the guest it copied. If the guest is gone or the VMID now belongs to another guest, the source is left in place and the log says so.
  • From 1.3, the ESXi → XCP-ng path checks the datastore and the path parts of each disk before it copies anything.

Note: After migration, install the target hypervisor’s guest tools (QEMU Guest Agent for Proxmox, XCP-ng Guest Tools for XCP-ng) for optimal performance.

API Endpoints

Method Endpoint Description
GET /api/xhm/plan Generate migration plan (query: source_cluster, source_vmid, target_cluster)
POST /api/xhm/migrate Start cross-hypervisor migration
GET /api/xhm/migrations List all active and completed migrations
GET /api/xhm/migrations/{id} Get migration status and progress