Added vddk support in vmware to kvm migrations by harikrishna-patnala · Pull Request #12970 · apache/cloudstack

harikrishna-patnala · 2026-04-07T04:43:47Z

Description

This PR introduces the VDDK implementation as part of VMware to KVM migration which reduces the migration time by half when compared to the existing implementation with exportOVF

Solution: Introduce VDDK configuration at both the host agent level and per-API-call level, wired through the migration execution pipeline on the KVM host.

Key Capabilities

Capability	Detail
Host-level config	Four new `agent.properties` keys configure VDDK defaults per KVM host
API-level overrides	Callers can pass VDDK settings via `importVm` `details`, overriding host defaults
Secure password handling	vCenter password written to a temp file, passed via `-ip` or `--password-file` based on virt-v2v version, and deleted immediately after use
Auto-thumbprint fetch	If no thumbprint is configured, it is automatically retrieved from vCenter via `openssl s_client`

Configuration Keys

libguestfs.backend   # LIBGUESTFS backend (default: direct)
vddk.lib.dir         # Path to VDDK library directory
vddk.transports      # Transport preference, e.g. nbd:nbdssl
vddk.thumbprint      # vCenter SHA1 thumbprint (auto-fetched if unset)

Precedence

API details  >  agent.properties

Doc PR: apache/cloudstack-documentation#640

Types of changes

Breaking change (fix or feature that would cause existing functionality to change)
New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Enhancement (improves an existing feature and functionality)
Cleanup (Code refactoring and cleanup, that may add test cases)
Build/CI
Test (unit or integration test code)

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Major
Minor

Bug Severity

Screenshots (if appropriate):

How Has This Been Tested?

How did you try to break this feature and the system with this change?

harikrishna-patnala · 2026-04-07T04:49:18Z

@blueorangutan package

blueorangutan · 2026-04-07T04:50:04Z

@harikrishna-patnala a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

codecov · 2026-04-07T05:45:34Z

Codecov Report

❌ Patch coverage is 34.35294% with 279 lines in your changes missing coverage. Please review.
✅ Project coverage is 17.61%. Comparing base (4708121) to head (5c3993f).
⚠️ Report is 2 commits behind head on 4.22.

Files with missing lines	Patch %	Lines
...ervisor/kvm/resource/LibvirtComputingResource.java	5.88%	96 Missing ⚠️
.../wrapper/LibvirtConvertInstanceCommandWrapper.java	47.42%	82 Missing and 10 partials ⚠️
.../apache/cloudstack/vm/UnmanagedVMsManagerImpl.java	60.25%	19 Missing and 12 partials ⚠️
...va/com/cloud/agent/api/ConvertInstanceCommand.java	0.00%	30 Missing ⚠️
...java/com/cloud/agent/manager/AgentManagerImpl.java	0.00%	17 Missing ⚠️
.../java/com/cloud/agent/api/to/RemoteInstanceTO.java	23.07%	10 Missing ⚠️
...e/cloudstack/api/command/admin/vm/ImportVmCmd.java	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##               4.22   #12970    +/-   ##
==========================================
  Coverage     17.60%   17.61%            
- Complexity    15677    15699    +22     
==========================================
  Files          5918     5918            
  Lines        531681   532140   +459     
  Branches      65005    65084    +79     
==========================================
+ Hits          93623    93749   +126     
- Misses       427498   427810   +312     
- Partials      10560    10581    +21

Flag	Coverage Δ
uitests	`3.70% <ø> (-0.01%)`	⬇️
unittests	`18.69% <34.35%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

harikrishna-patnala · 2026-04-07T05:54:02Z

@blueorangutan package

blueorangutan · 2026-04-07T05:58:39Z

@harikrishna-patnala a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

harikrishna-patnala · 2026-04-07T05:58:45Z

@blueorangutan package

blueorangutan · 2026-04-07T06:02:56Z

@harikrishna-patnala a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-04-07T06:52:35Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 17380

harikrishna-patnala · 2026-04-07T13:39:58Z

@blueorangutan package

sureshanaparti · 2026-04-08T04:21:51Z

agent/conf/agent.properties

+# 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=
+


@harikrishna-patnala can you update the docs with these settings here: https://docs.cloudstack.apache.org/en/4.22.0.0/adminguide/virtual_machines.html#importing-virtual-machines-from-vmware-into-kvm

added a doc PR here apache/cloudstack-documentation#640

sureshanaparti · 2026-04-08T04:23:32Z

agent/conf/agent.properties

 # Instance conversion VIRT_V2V_TMPDIR env var
 #convert.instance.env.virtv2v.tmpdir=
+
+# LIBGUESTFS backend to use for VMware to KVM conversion via VDDK (default: direct)


should keep other possible options in the comment (other than direct) ?

api/src/main/java/org/apache/cloudstack/api/command/admin/vm/ImportVmCmd.java

...ain/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtConvertInstanceCommandWrapper.java

sureshanaparti · 2026-04-08T05:38:40Z

CheckConvertInstanceCommand should ensure vddk support on host when usevddk is enabled, in addition to virt-v2v, and skip checking ovf export (in LibvirtCheckConvertInstanceCommandWrapper)

cloudstack/server/src/main/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImpl.java

Line 2060 in 71f47d6

    
           private CheckConvertInstanceAnswer checkConversionSupportOnHost(HostVO convertHost, String sourceVM, boolean checkWindowsGuestConversionSupport) {

Copilot

Pull request overview

This PR adds a VDDK-based VMware→KVM conversion path (via virt-v2v) to speed up importVm migrations, with host-level defaults (agent.properties) and API-level overrides (importVm details), plus UI support and tests.

Changes:

Introduces usevddk API parameter and propagates VDDK settings through the VMware→KVM import pipeline into ConvertInstanceCommand.
Implements VDDK conversion execution on KVM hosts (password-file handling, vCenter thumbprint retrieval, virt-v2v option detection) and advertises host VDDK capability.
Updates UI to toggle VDDK mode and adjusts conversion options; adds i18n string and expands unit test coverage.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
ui/src/views/tools/ImportUnmanagedInstance.vue	Adds “Use VDDK” toggle and alters conversion option interactions/params.
ui/public/locales/en.json	Adds UI label for VDDK toggle.
server/src/main/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImpl.java	Wires `usevddk` and `details` overrides into conversion flow; adds validation.
server/src/test/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImplTest.java	Adds test cases for VDDK behavior and validations.
core/src/main/java/com/cloud/agent/api/ConvertInstanceCommand.java	Adds VDDK-related fields to conversion command.
api/src/main/java/org/apache/cloudstack/api/command/admin/vm/ImportVmCmd.java	Adds `usevddk` request parameter.
api/src/main/java/org/apache/cloudstack/api/ApiConstants.java	Adds `USE_VDDK` constant.
api/src/main/java/com/cloud/host/Host.java	Adds host detail key for VDDK support.
api/src/main/java/com/cloud/agent/api/to/RemoteInstanceTO.java	Adds cluster/host fields needed for VPX URL construction.
engine/orchestration/src/main/java/com/cloud/agent/manager/AgentManagerImpl.java	Persists reported host VDDK support detail.
plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/LibvirtComputingResource.java	Loads VDDK agent.properties, detects virt-v2v password option, reports VDDK support.
plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtReadyCommandWrapper.java	Reports `host.vddk.support` in Ready response.
plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtConvertInstanceCommandWrapper.java	Adds VDDK conversion execution path and thumbprint parsing.
plugins/hypervisors/kvm/src/test/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtConvertInstanceCommandWrapperTest.java	Adds unit tests around VDDK conversion behavior.
agent/src/main/java/com/cloud/agent/properties/AgentProperties.java	Defines new agent properties for VDDK settings.
agent/conf/agent.properties	Documents new VDDK-related configuration keys.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ui/src/views/tools/ImportUnmanagedInstance.vue

Copilot · 2026-04-08T05:39:45Z

...ain/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtConvertInstanceCommandWrapper.java

+        String vcenterPassword = vmwareInstance.getVcenterPassword();
+        if (StringUtils.isBlank(vcenterPassword)) {
+            logger.error("({}) Could not determine vCenter password for {}", originalVMName, vmwareInstance.getVcenterHost());
+            return false;
+        }
+
+        String passwordFilePath = String.format("/root/v2v.pass.cloud.%s",
+                StringUtils.defaultIfBlank(vmwareInstance.getVcenterHost(), "unknown"));
+        try {
+            Files.writeString(Path.of(passwordFilePath), vcenterPassword);
+            logger.debug("({}) Written vCenter password to {}", originalVMName, passwordFilePath);
+        } catch (Exception e) {
+            logger.error("({}) Failed to write vCenter password file {}: {}", originalVMName, passwordFilePath, e.getMessage());
+            return false;
+        }
+
+        String vpxUrl = buildVpxUrl(vmwareInstance, originalVMName);
+
+        StringBuilder cmd = new StringBuilder();
+
+        String effectiveLibguestfsBackend = StringUtils.defaultIfBlank(libguestfsBackend, "direct");
+        cmd.append("export LIBGUESTFS_BACKEND=").append(effectiveLibguestfsBackend).append(" && ");
+
+        cmd.append("virt-v2v ");
+        cmd.append("--root first ");
+        cmd.append("-ic '").append(vpxUrl).append("' ");
+        if (StringUtils.isBlank(passwordOption)) {
+            logger.error("({}) Could not determine supported password file option for virt-v2v", originalVMName);
+            return false;
+        }
+
+        cmd.append(passwordOption).append(" ").append(passwordFilePath).append(" ");
+        cmd.append("-it vddk ");
+        cmd.append("-io vddk-libdir=").append(vddkLibDir).append(" ");
+        String vddkThumbprint = StringUtils.trimToNull(configuredVddkThumbprint);
+        if (StringUtils.isBlank(vddkThumbprint)) {
+            vddkThumbprint = getVcenterThumbprint(vmwareInstance.getVcenterHost(), timeout, originalVMName);
+        }
+        if (StringUtils.isBlank(vddkThumbprint)) {
+            logger.error("({}) Could not determine vCenter thumbprint for {}", originalVMName, vmwareInstance.getVcenterHost());
+            return false;
+        }


performInstanceConversionVddk writes the vCenter password to a fixed path under /root derived from the vCenter host. This is vulnerable to races between concurrent conversions (overwriting/deleting each other’s password file) and may leave the password on disk on early returns (e.g., when passwordOption is blank or thumbprint lookup fails). Use a unique temp file (e.g., Files.createTempFile), set restrictive permissions (0600), and ensure deletion happens in a finally block that runs for all exit paths.

...ain/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtConvertInstanceCommandWrapper.java

server/src/main/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImpl.java

Copilot · 2026-04-08T05:39:46Z

...ypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/LibvirtComputingResource.java

+        try {
+            ProcessBuilder pb = new ProcessBuilder("virt-v2v", "--help");
+            Process process = pb.start();
+
+            String output = new String(process.getInputStream().readAllBytes());
+            process.waitFor();
+
+            if (output.contains("-ip <filename>")) {
+                return "-ip";
+            } else if (output.contains("--password-file")) {
+                return "--password-file";
+            } else {
+                LOGGER.error("virt-v2v does not support -ip or --password-file");
+                return null;
+            }
+        } catch (Exception e) {
+            LOGGER.error("Failed to detect virt-v2v password option: {}", e.getMessage());
+            return null;
+        }


detectPasswordFileOption() runs virt-v2v --help via ProcessBuilder without a timeout and without consuming stderr; if virt-v2v hangs or produces enough stderr output, agent startup could block indefinitely. Consider using the existing Script helper with a timeout (and redirected stderr), and check/handle the process exit code before trusting output.

Suggested change

try {

ProcessBuilder pb = new ProcessBuilder("virt-v2v", "--help");

Process process = pb.start();

String output = new String(process.getInputStream().readAllBytes());

process.waitFor();

if (output.contains("-ip <filename>")) {

return "-ip";

} else if (output.contains("--password-file")) {

return "--password-file";

} else {

LOGGER.error("virt-v2v does not support -ip or --password-file");

return null;

}

} catch (Exception e) {

LOGGER.error("Failed to detect virt-v2v password option: {}", e.getMessage());

return null;

}

final int timeout = 30;

final Script script = new Script("/bin/bash", timeout, LOGGER);

script.add("-c");

script.add("virt-v2v --help 2>&1");

final AllLinesParser parser = new AllLinesParser();

final String executionResult = script.execute(parser);

if (executionResult != null) {

LOGGER.error("Failed to detect virt-v2v password option: {}", executionResult);

return null;

}

final String output = parser.getLines();

if (StringUtils.isBlank(output)) {

LOGGER.error("Failed to detect virt-v2v password option: empty output from virt-v2v --help");

return null;

}

if (output.contains("-ip <filename>")) {

return "-ip";

} else if (output.contains("--password-file")) {

return "--password-file";

} else {

LOGGER.error("virt-v2v does not support -ip or --password-file");

return null;

}

server/src/main/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImpl.java

harikrishna-patnala · 2026-04-08T14:33:39Z

@blueorangutan package

blueorangutan · 2026-04-08T14:36:05Z

@harikrishna-patnala a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-04-08T15:26:53Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 17407

harikrishna-patnala · 2026-04-09T00:25:23Z

@blueorangutan package

blueorangutan · 2026-04-09T00:26:04Z

@harikrishna-patnala a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-04-09T01:25:30Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 17411

sureshanaparti · 2026-04-09T04:22:59Z

...ain/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtConvertInstanceCommandWrapper.java

+                String vddkLibDir = resolveVddkSetting(cmd.getVddkLibDir(), serverResource.getVddkLibDir());
+                if (StringUtils.isBlank(vddkLibDir)) {
+                    String err = String.format("VDDK lib dir is not configured on the host. " +
+                            "Set '%s' in agent.properties to use VDDK-based conversion.", "vddk.lib.dir");


Suggested change

"Set '%s' in agent.properties to use VDDK-based conversion.", "vddk.lib.dir");

"Set '%s' in agent.properties or in details parameter of the import api calll to use VDDK-based conversion.", "vddk.lib.dir");

sureshanaparti · 2026-04-09T04:26:08Z

...ain/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtConvertInstanceCommandWrapper.java

+            return false;
+        }
+
+        String passwordFilePath = String.format("/root/v2v.pass.cloud.%s.%s",


Suggested change

String passwordFilePath = String.format("/root/v2v.pass.cloud.%s.%s",

String passwordFilePath = String.format("/tmp/v2v.pass.cloud.%s.%s",

sureshanaparti · 2026-04-09T04:44:47Z

server/src/main/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImpl.java

+
+            boolean isOvfExportSupported = false;
+            if (!useVddk) {
+                CheckConvertInstanceAnswer conversionSupportAnswer = checkConversionSupportOnHost(convertHost, sourceVMName, false);


can add conversion support check for vddk as well? if convert host is from the api cmd and it doesn't support vddk, fail early.

auto selection of convert host (when convert host is not passed from the api cmd) should return null and no hosts with vddk support.

sureshanaparti · 2026-04-09T04:49:34Z

server/src/main/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImpl.java

-                // Uses KVM Host for OVF export to temporary conversion location, through ovftool
-                importVmTasksManager.updateImportVMTaskStep(importVMTask, zone, owner, convertHost, importHost, null, ConvertingInstance);
-                convertedInstance = convertVmwareInstanceToKVMAfterExportingOVFToConvertLocation(
+                // Uses KVM Host for direct conversion using VDDK, or for OVF export to temporary conversion location through ovftool                 importVmTasksManager.updateImportVMTaskStep(importVMTask, zone, owner, convertHost, importHost, null, ConvertingInstance);


Suggested change

// Uses KVM Host for direct conversion using VDDK, or for OVF export to temporary conversion location through ovftool importVmTasksManager.updateImportVMTaskStep(importVMTask, zone, owner, convertHost, importHost, null, ConvertingInstance);

// Uses KVM Host for direct conversion using VDDK, or for OVF export to temporary conversion location through ovftool

importVmTasksManager.updateImportVMTaskStep(importVMTask, zone, owner, convertHost, importHost, null, ConvertingInstance);

sureshanaparti · 2026-04-09T04:57:16Z

server/src/main/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImpl.java

+            }
+            if (!volumeApiService.doesStoragePoolSupportDiskOffering(selectedStoragePool, rootDiskOffering)) {
+                throw new InvalidParameterValueException(String.format("The root disk offering '%s' is not supported by the selected conversion storage pool '%s'. " +
+                        "When using VDDK, all selected disk offerings must be compatible with the conversion storage pool, as it will become the primary storage for the imported volumes.",


conversion storage pool is option parameter, and for ovf export scenario, secondary storage is used as the default conversion storage. ensure conversion storage pool is set in case of vddk (and update the update the importVm API parameter convertinstancepoolid description that it is the primary storage for vddk enabled conversion).

sureshanaparti · 2026-04-09T05:01:34Z

server/src/main/java/org/apache/cloudstack/vm/UnmanagedVMsManagerImpl.java

+                if (StringUtils.isBlank(selectedHost.getDetail(Host.HOST_VDDK_SUPPORT))) {
+                    err = String.format(
+                            "Cannot use VDDK-based conversion on host %s as the '%s' is not there on the host",
+                            selectedHost, Host.HOST_VDDK_SUPPORT);


in some cases, agent is not restarted after updating vddk libs in the host, so this detail can be blank, check it using CheckConvertInstanceCommand (in checkConversionSupportOnHost())

sureshanaparti · 2026-04-09T05:08:11Z

engine/orchestration/src/main/java/com/cloud/agent/manager/AgentManagerImpl.java

+                        } else {
+                            host.getDetails().put(Host.HOST_VDDK_VERSION, vddkVersion);
+                        }
+                        updateNeeded = true;


do we need all these params in host_details? Persisting Host.HOST_VDDK_VERSION should be enough when vddk lib is properly set, to indicate vddk support.

boring-cyborg bot added component:agent component:api component:kvm component:UI labels Apr 7, 2026

Added vddk support in vmware to kvm migrations

7dc5d50

harikrishna-patnala force-pushed the Introduce-vddk-in-vmware-to-kvm-migrations-422 branch from b95cfb7 to 7dc5d50 Compare April 7, 2026 04:48

harikrishna-patnala added this to the 4.22.1 milestone Apr 7, 2026

harikrishna-patnala added 2 commits April 7, 2026 10:44

Fix UI

d380447

Add defaults in the UI

fbd8082

Added validations for selected storage and selected diskofferings

cb42c2f

harikrishna-patnala added 2 commits April 7, 2026 17:36

password file related changes and vddk support addition in host details

ababa52

Detect password file option while kvm initialisation

7fb0b85

boring-cyborg bot added the component:orchestration label Apr 7, 2026

harikrishna-patnala requested a review from sureshanaparti April 7, 2026 13:40