From vSphere to KVM in 5 Minutes: A Step-by-Step Guide

This guide walks you through migrating a virtual machine from VMware vSphere to KVM using HyperSDK. The entire process -- from connecting to vCenter to booting the converted VM on libvirt -- takes about five minutes for a typical workload.

Prerequisites

Before you begin, make sure you have:

• HyperSDK installed and the hypervisord daemon running (see the installation guide)
• vCenter Server credentials with at least read-only access to the VMs you want to migrate
• libvirt and qemu-kvm installed on the target host
• Sufficient disk space for the exported qcow2 image (roughly the same size as the source VMDK)

Step 1: Configure vCenter Connection

Edit your HyperSDK configuration file at /etc/hypersdk/config.yaml (or ~/.config/hypersdk/config.yaml for user-level configuration) and add your vCenter credentials:

providers:
  vsphere:
    enabled: true
    endpoint: "vcenter.example.com"
    username: "administrator@vsphere.local"
    password: "your-password"
    datacenter: "DC1"
    insecure: false

  kvm:
    enabled: true
    connection: "qemu:///system"
    storage_pool: "default"

After saving the file, restart the daemon:

sudo systemctl restart hypervisord

HyperSDK will validate the connection to vCenter on startup and report any issues in the system log.

Step 2: Browse VMs in the Dashboard

Open your browser and navigate to http://localhost:8080/web/dashboard/. Log in with your configured credentials and navigate to Migration > VMs in the left sidebar.

The VM browser displays all virtual machines discovered from your vCenter. Each VM is shown with its operating system icon (Windows, Ubuntu, CentOS, Debian, and others are all recognized automatically), along with CPU count, memory allocation, total disk size, and power state. You can filter by name, OS type, or power state using the search bar at the top.

Find the VM you want to migrate and verify its details. HyperSDK shows a readiness indicator for each VM -- a green checkmark means the VM is ready for export, while a yellow warning indicates potential issues like active snapshots that should be consolidated first.

Step 3: Export the VM

Click the Export button next to your chosen VM. The export dialog opens with the following options:

• Target format: Select qcow2 for KVM (this is the default)
• Compression: Enable to reduce transfer size (recommended for network transfers)
• Destination: Choose local to save to the HyperSDK server, or select a configured target provider

Click Start Export to begin. HyperSDK connects to vCenter, creates a temporary snapshot (if the VM is running), streams the disk data, and converts from VMDK to qcow2 format in a single pass. The original VM is not modified or powered off during this process.

Step 4: Monitor Progress

Navigate to Migration > Jobs in the sidebar to watch the export progress. The jobs table shows:

• Progress bar with percentage complete
• Transfer speed in MB/s
• Elapsed time and estimated time remaining
• Current phase (snapshot, stream, convert, finalize)

For a 50 GB VM on a gigabit network, expect the export to complete in 3-4 minutes. The progress updates in real time through the dashboard's WebSocket connection -- no need to refresh the page.

If anything goes wrong, click on the job row to see detailed logs. The explain mode (available under Observability > Explain) can diagnose common issues like network timeouts, permission errors, or storage space problems.

Step 5: Download the Converted Image

Once the job completes, navigate to Migration > Downloads. Your converted qcow2 file is listed with its size, checksum, and creation timestamp. Click Download to transfer it to your local machine, or note the server-side path if your KVM host is the same machine running HyperSDK.

The exported file includes a manifest (export-manifest.json) with metadata about the source VM: original disk layout, network configuration, boot firmware (BIOS or UEFI), and any guest customization that was applied.

Step 6: Deploy to libvirt

On your KVM host, use virt-install to create a new VM from the exported qcow2 image:

virt-install \
  --name my-migrated-vm \
  --memory 4096 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/exported-vm.qcow2,format=qcow2 \
  --import \
  --os-variant ubuntu22.04 \
  --network bridge=br0 \
  --noautoconsole

The --import flag tells virt-install to skip installation and boot directly from the existing disk image. Adjust the --os-variant, --memory, and --vcpus values to match your source VM's configuration (these are listed in the export manifest).

The VM should boot successfully on the first attempt. Linux VMs generally require no additional changes. The kernel detects the new virtio hardware and loads the appropriate drivers automatically.

Batch Migration for Multiple VMs

For migrating multiple VMs at once, use the Manifest Builder under Tools > Manifest Builder in the dashboard. Create a migration manifest that lists all the VMs you want to export, their target formats, and any per-VM configuration overrides. Submit the manifest and HyperSDK will process all exports as a batch job, running multiple conversions in parallel up to your configured concurrency limit.

Alternatively, use the CLI for scripted batch migrations:

hyperctl export --provider vsphere --format qcow2 --batch manifest.yaml

The batch job respects dependency ordering, so if you have VMs that must be migrated in a specific sequence (for example, a database server before its application servers), you can define those dependencies in the manifest.

Windows VM Considerations

Windows VMs require VirtIO drivers to run on KVM. HyperSDK handles this automatically when it detects a Windows guest operating system. During the conversion process, it injects the VirtIO storage and network drivers into the Windows image so the VM can boot without manual driver installation.

The auto-detection works for Windows Server 2016 and later, as well as Windows 10 and 11 desktop editions. For older Windows versions, you may need to install VirtIO drivers manually before or after migration. The dashboard's readiness check view will warn you if a Windows VM requires manual driver intervention.

After booting a migrated Windows VM on KVM, you will need to reactivate the Windows license, as the hardware fingerprint will have changed. This is expected behavior for any hypervisor migration.