Migrating from VMware vSphere: full conversion playbook

Why migrate, and why now

VMware’s acquisition by Broadcom and the resulting shift to subscription-only licensing has pushed many organisations to evaluate alternatives. Proxmox VE is the most direct replacement: KVM-based, with a web console, clustering, HA, backups, and a familiar VM model. The migration is technical, not political — what matters is that the cutover happens with zero data loss and minimal downtime.

This lesson covers the full conversion playbook, not just disk conversion. A working disk image is only 30% of the job. The other 70% is drivers, licences, networking, and validation.

flowchart LR
  A[Phase 1<br/>Discovery &amp; inventory] --> B[Phase 2<br/>Storage migration]
  B --> C[Phase 3<br/>Network mapping]
  C --> D[Phase 4<br/>Driver preparation]
  D --> E[Phase 5<br/>Import into Proxmox]
  E --> F[Phase 6<br/>Validation]
  F --> G{All checks pass?}
  G -->|Yes| H[Phase 7<br/>Cutover &amp; decommission]
  G -->|No| E

Phase 1: Discovery and inventory

Before touching anything, build a complete picture of what you’re moving.

What to capture per VM

For each VM, document:

• Guest OS, kernel version, architecture (x86_64 vs others)
• Disk size, format (thick/thin), and any RDMs (raw device mappings)
• Network configuration (VLAN, IP, MAC)
• vSphere-specific features in use (paravirtual SCSI, VMXNET3, FT, vMotion, snapshots, CBT)
• Critical services, RPO/RTO requirements, and dependencies
• Backup schedule and last-known-good backup timestamp

Export this as a CSV from vCenter. Tools like RVTools produce this in one click.

Identify VMware-only features

Phase 2: Storage migration

The two main paths:

1. Cold conversion — VM is shut down, VMDK exported, converted, imported. Safest.
2. virt-v2v in-place — VM is running on VMware; virt-v2v connects over SSH/ESXi shell and pulls the disk over the network, converts, and writes to Proxmox storage.

Cold conversion with qemu-img

# Export the VM as OVF from vCenter (or grab the VMDK directly via scp)
# Convert thin-provisioned VMDK to qcow2
qemu-img convert -f vmdk -O qcow2 vm-disk1.vmdk vm-100-disk-0.qcow2

# Alternatively, output as raw for LVM-thin storage
qemu-img convert -f vmdk -O raw vm-disk1.vmdk vm-100-disk-0.raw

# Verify the converted image boots before continuing
qemu-img info vm-100-disk-0.qcow2
qemu-img check vm-100-disk-0.qcow2

Bulk conversion with virt-v2v

virt-v2v automates the conversion of VMware guests. It handles Windows driver injection (critical for virtio), UEFI conversion, and re-creates the VM definition.

# Install virt-v2v on a Linux jumpbox (CentOS / RHEL / Fedora recommended for vendor packages)
dnf install virt-v2v

# Convert a running VMware VM. Requires read-only access to vCenter or ESXi.
virt-v2v -i vmx ssh://root@esxi01/vmfs/volumes/datastore1/vmware-folder/vm.vmx \
         -o local -os /var/tmp/v2v-output/

# Convert and push directly to a Proxmox host (via SSH)
virt-v2v -i vmx ssh://root@esxi01/vmfs/volumes/datastore1/vmware-folder/vm.vmx \
         -o rhv -oc https://pve.example.com/api2/json

# Windows guests: virt-v2v injects the virtio drivers automatically
# Linux guests: ensure virtio-blk / virtio-scsi modules are loaded

Phase 3: Network mapping

Build a mapping document:

For VMs that were on VXLAN-backed port groups, recreate the equivalent SDN zone (see the SDN lesson).

Phase 4: Driver preparation

Windows guests must have virtio drivers installed before conversion, or they will blue-screen on first boot in Proxmox.

# Inside the Windows VM, before migration:
# 1. Download the virtio-win ISO
# 2. Mount it, run virtio-win-guest-tools.exe
# 3. Reboot — drivers install for viostor, vioscsi, NetKVM, viomem, Balloon
# 4. Shut down

For Linux guests, modern distributions (kernel 3.x+) have virtio built in or available as modules. Test by booting a converted image in qemu before declaring success.

Phase 5: Import into Proxmox

# Create the VM shell first
qm create 100 --name "web01" --memory 4096 --cores 4 --net0 virtio,bridge=vmbr0

# Import the converted disk
qm importdisk 100 vm-100-disk-0.qcow2 local-lvm -format qcow2

# Attach the imported disk as SCSI0
qm set 100 --scsi0 local-lvm:vm-100-disk-0 --boot order=scsi0

# Set boot mode (BIOS for legacy, UEFI for modern)
qm set 100 --bios ovmf --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=1

# Add a TPM if the source had vTPM
qm set 100 --tpmstate0 local-lvm:1,version=v2.0

# Start and watch the console
qm start 100

Phase 6: Validation

Don’t declare success on first boot. Validate:

• OS boots to login screen
• Network connectivity (ping gateway, ping external)
• All services start (check with systemctl, sc query, etc.)
• Licence re-activation (Windows KMS, RHEL subscription-manager, etc.)
• Application-level tests (smoke tests, synthetic transactions)
• Backup runs successfully (PBS job completes)
• Live migration works to a second node

Phase 7: Cutover and rollback

For production cutovers:

1. Freeze writes at the application layer (e.g., database in read-only mode)
2. Take a final vSphere snapshot
3. Power off the source VM
4. Power on the Proxmox VM
5. Validate
6. Update DNS / load balancer to point at the new VM
7. Keep the vSphere VM powered off but available for 7 days
8. Decommission after the validation window passes

The rollback path is: power on the vSphere VM, revert DNS.

Common pitfalls

• Forgetting to install Windows virtio drivers — blue-screen on first boot
• UEFI vs BIOS mismatch — Windows VMs from modern VMware usually need OVMF, not SeaBIOS
• vSAN dependency — VMs on vSAN disks cannot be exported via OVF; use VADP or storage vMotion to a shared datastore first
• Licence reactivation — Windows detects “hardware change” and may refuse to boot; have a KMS or MAK key ready
• VMware Tools — uninstall them; Proxmox has no agent equivalent (use QEMU Guest Agent instead)
• Time drift — disable VMware Tools time sync, enable QEMU Guest Agent time sync

Key takeaways

• A migration is a project, not a single event — plan for weeks, not days
• Always pilot on 2-3 representative VMs first
• Install virtio drivers in Windows guests before conversion
• Validate everything: boot, network, services, backups, live migration
• Have a rollback plan with a tested path

Knowledge check