Skip to content

Add VDDK support in VMware to KVM migration #640

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
harikrishna-patnala wants to merge 1 commit into
base: 4.22
Choose a base branch
from
+172 −0
Draft

Add VDDK support in VMware to KVM migration #640

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 172 additions & 0 deletions source/adminguide/virtual_machines/importing_vmware_vms_into_kvm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,178 @@ If you are hitting the following error when running ovftool, install the depende
dnf install libnsl


VDDK-based Optimized Conversion
-------------------------------

CloudStack supports an optimized VMware-to-KVM migration path using virt-v2v in vpx input mode combined with
VMware's Virtual Disk Development Kit (VDDK). This method eliminates the OVF export phase entirely and streams
disk blocks directly from the source hypervisor into the conversion pipeline, resulting in significantly faster
migration times.

The traditional OVF-based workflow operates in two sequential phases:

1. Export the entire VM as OVF/VMDK files to temporary storage (full disk copy).
2. Convert the local VMDK files using virt-v2v (second full disk read and write).

The VDDK-based workflow replaces both phases with a single streaming pipeline:

- virt-v2v connects directly to vCenter via ``vpx://``
- Disk blocks are read on demand via VDDK (using nbdkit internally as the translation layer between the
VDDK API and virt-v2v's NBD block device interface)
- Conversion and disk transfer happen concurrently
- Only allocated blocks are transferred; zero-filled and sparse extents are skipped
- No intermediate OVF or VMDK files are created

This reduces disk I/O amplification, eliminates temporary staging storage, and shortens end-to-end migration time.

.. note:: CloudStack does not distribute VDDK, operators must download it separately.
Along with the new VDDK-based conversion method the traditional OVF-based method remains supported for environments.
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sentence reads incomplete/awkward: “the traditional OVF-based method remains supported for environments.” Consider clarifying what environments this refers to (e.g., “...supported for environments where VDDK cannot be used/installed”).

Suggested change
Along with the new VDDK-based conversion method the traditional OVF-based method remains supported for environments.
Along with the new VDDK-based conversion method, the traditional OVF-based method remains supported for environments where VDDK cannot be used or installed.

Copilot uses AI. Check for mistakes.
Operators can choose the conversion method on a per-migration basis in the UI import wizard.

Comment on lines +144 to +147
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The .. note:: directive at line 144 is immediately followed by unindented text without a blank line. In reStructuredText this commonly triggers a docutils/Sphinx warning ("Explicit markup ends without a blank line") and the following sentences won't be part of the note. Add a blank line after the note (and indent the following lines if they’re intended to be included in the note block).

Suggested change
.. note:: CloudStack does not distribute VDDK, operators must download it separately.
Along with the new VDDK-based conversion method the traditional OVF-based method remains supported for environments.
Operators can choose the conversion method on a per-migration basis in the UI import wizard.
.. note::
CloudStack does not distribute VDDK, operators must download it separately.
Along with the new VDDK-based conversion method the traditional OVF-based method remains supported for environments.
Operators can choose the conversion method on a per-migration basis in the UI import wizard.

Copilot uses AI. Check for mistakes.
Host Prerequisites for VDDK-based Conversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To use VDDK-based migration, operators must prepare each KVM host that will run the conversion: install the conversion
tools, install VDDK manually, configure libguestfs, and verify host connectivity to vCenter/ESXi.

Example: prepare one KVM conversion host

**Step 1: Install the conversion stack (RHEL / Rocky / Alma Linux)**

::

dnf install -y epel-release
dnf config-manager --set-enabled crb
dnf install -y virt-v2v libguestfs-tools libguestfs-xfs qemu-img nbdkit

**Step 2: Configure libguestfs backend as** ``direct``

VDDK does not work with the default sandbox backend. Configure ``direct``:

::

cat <<EOF > /etc/profile.d/libguestfs.sh
export LIBGUESTFS_BACKEND=direct
EOF

source /etc/profile.d/libguestfs.sh

This can also be configured persistently with ``libguestfs.backend`` in ``/etc/cloudstack/agent/agent.properties`` (see `Agent Properties for VDDK-based Conversion`_ below).

**Step 3: Download and install VDDK**

Download the VDDK tarball and extract it to a known location on the KVM host, for example, ``/opt/vmware-vddk``.
The resulting directory must contain the VDDK libraries under a ``lib64`` subdirectory.

::

mkdir -p /opt/vmware-vddk
tar -xf VMware-vix-disklib-9*.tar.gz -C /opt/vmware-vddk

Expected layout after extraction::

/opt/vmware-vddk/vmware-vix-disklib-distrib/
lib64/
include/
bin64/

**Step 4: Add EL9 compatibility symlink (when using VDDK 9)**

On EL9 distributions, virt-v2v may expect ``libvixDiskLib.so.8``. Create this compatibility symlink:

::

cd /opt/vmware-vddk/vmware-vix-disklib-distrib/lib64
ln -s libvixDiskLib.so.9 libvixDiskLib.so.8

.. note:: This compatibility symlink is commonly required on RHEL 9, Rocky Linux 9, and Alma Linux 9.

**Step 5: Verify host setup**

::

ls /opt/vmware-vddk/vmware-vix-disklib-distrib/lib64/libvixDiskLib.so.8
virt-v2v --version
nbdkit --version

**Step 6: Verify required network access**

The KVM conversion host must be able to reach:

.. cssclass:: table-striped table-bordered table-hover

============================== ====== ==============================
Target Port Purpose
============================== ====== ==============================
vCenter 443 API / authentication
ESXi hosts 902 VDDK NFC disk transfer
ESXi hosts 443 VM metadata
============================== ====== ==============================

Agent Properties for VDDK-based Conversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following properties can be configured in ``/etc/cloudstack/agent/agent.properties`` on each KVM host to enable and tune the VDDK-based conversion.
After editing this file, restart the CloudStack agent (``systemctl restart cloudstack-agent``).
These values can also be passed in details parameters in importVm API as key-value pairs.

.. cssclass:: table-striped table-bordered table-hover

+------------------------+----------------------------------------------------------------------+-------------------------------------------------------+
| Property | Description | Default / Example |
+========================+======================================================================+=======================================================+
| ``libguestfs.backend`` | The libguestfs backend for VDDK-based conversion. | ``direct`` |
| | Must be set to ``direct`` for VDDK to work correctly. | |
+------------------------+----------------------------------------------------------------------+-------------------------------------------------------+
| ``vddk.lib.dir`` | Path to the VDDK library directory on the KVM host. | ``/opt/vmware-vddk/vmware-vix-disklib-distrib`` |
| | Passed to virt-v2v as ``-io vddk-libdir=<path>``. | |
+------------------------+----------------------------------------------------------------------+-------------------------------------------------------+
| ``vddk.transports`` | Ordered VDDK transport preference. | Example: ``nbd:nbdssl`` |
| | Passed as ``-io vddk-transports=<value>`` to virt-v2v. | |
+------------------------+----------------------------------------------------------------------+-------------------------------------------------------+
| ``vddk.thumbprint`` | Optional vCenter SHA1 thumbprint. | If unset, CloudStack computes it automatically on |
| | Passed as ``-io vddk-thumbprint=<value>`` to virt-v2v. | the KVM host via ``openssl``. |
+------------------------+----------------------------------------------------------------------+-------------------------------------------------------+

Example configuration in ``/etc/cloudstack/agent/agent.properties``:

::

# LIBGUESTFS backend to use for VMware to KVM conversion via VDDK (default: direct)
libguestfs.backend=direct

# Path to the VDDK library directory for VMware to KVM conversion via VDDK,
# passed to virt-v2v as -io vddk-libdir=<path>
vddk.lib.dir=/opt/vmware-vddk/vmware-vix-disklib-distrib

# Ordered VDDK transport preference for VMware to KVM conversion via VDDK, passed as
# -io vddk-transports=<value> to virt-v2v. Example: nbd:nbdssl
# vddk.transports=nbd:nbdssl

# Optional vCenter SHA1 thumbprint for VMware to KVM conversion via VDDK, passed as
# -io vddk-thumbprint=<value>. If unset, CloudStack computes it on the KVM host via openssl.
# vddk.thumbprint=


Recommendations for Using VDDK-based Conversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Use a single primary storage pool for direct conversion**

When VDDK-based conversion is enabled, it is strongly recommended to configure the conversion to write directly
to the destination primary storage pool (i.e., set *Convert to storage pool directly* to ``true`` in the import wizard).
This eliminates the two-step process of the traditional OVF method, conversion to temporary storage followed by
an import step, replacing it with a single streaming pipeline that writes converted QCOW2 disks directly to the
destination primary storage.

**Network placement for optimal disk transfer throughput**

For best performance, place the KVM conversion host on the same high-bandwidth network as the source ESXi hosts.
VDDK disk transfer uses VMware's NFC protocol on TCP port 902. ESXi routes NFC traffic to the conversion host based
on standard IP routing, if the conversion host is reachable over a dedicated storage or migration network,
ESXi will naturally select that VMkernel interface for disk transfer, keeping bulk data off the management network
without requiring any special configuration in virt-v2v or CloudStack.

Usage
-----

Expand Down
Loading