Add VDDK support in VMware to KVM migration

source/adminguide/virtual_machines/importing_vmware_vms_into_kvm.rst

@@ -117,6 +117,179 @@ 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.
+   Operators can choose the conversion method on a per-migration basis in the UI import wizard.
+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
 -----