Kvm Converter Utilities (kc-utils)

Pure Go utilities that convert virtual machines from external hypervisors into KVM-compatible guests. Guest adaptations include VirtIO driver injection, initramfs and kernel updates, boot configuration fixes (device remapping, kernel args, UEFI), and network migration (VirtIO net drivers, NIC naming, static IPs) for Linux and Windows.

The core pipeline is four pure-Go binaries that inspect and mount guest disks, convert the guest OS, then unmount, validate filesystems, and emit JSON metadata for creating the target VM.

• Disk copying from VMware uses pure Go govmomi NFC export to stream VMDK files raw data directly into target PVCs.
• Guest filesystem operations go through a pluggable backend: host-kernel mounts (direct), a libguestfs appliance (guestfs), or a QEMU appliance with in-guest agent (qemu).

Benchmark : On OpenShift MTV cold migrations (three VMs in one plan), kc-v2v is faster end-to-end than virt-v2v, with lower peak memory and CPU on most guests and less network traffic. See the baseline tables and dashboard for the latest archived run.

Dashboard (source): Interactive charts of memory, CPU, and network I/O over time for the ref vs kc-v2v runs.

Three guest disk backends are available (see docs/architecture/backends.md):

• direct (--backend direct, default) — host kernel mounts and chroot for guest commands
• guestfs (--backend guestfs) — libguestfs appliance via guestfish
• qemu (--backend qemu) — QEMU appliance with in-guest agent over a virtio-serial socket

Forklift (MTV) Integration

kc-v2v is a drop-in replacement for the virt-v2v container image in Forklift. The MTV cluster setting is virt_v2v_image_fqin:

oc mtv settings set --setting virt_v2v_image_fqin \
  --value quay.io/yaacov/kc-v2v:devel-amd64

See docs/apps/forklift-usage.md for full usage instructions.

Design Highlights

• Pure Go core pipeline - builds with standard go build on any Unix host, no C toolchain required. Release images use GOOS=linux (make build). Guest disk backends have platform-specific runtime requirements; see docs/architecture/backends.md.
• Initramfs rebuild via guest tools - virtio drivers are injected by running the guest's own tooling via chroot into the mounted guest root (host-mount) or an in-appliance chroot (guestfs): dracut first, then update-initramfs, then mkinitramfs as fallbacks.
• Windows offline driver injection - virtio drivers are registered in the Windows registry (CriticalDeviceDatabase / DriverDatabase) offline, making the guest bootable on KVM. Firstboot PowerShell scripts then complete driver installation via pnputil and install the QEMU guest agent.
• ARM / aarch64 support - cross-architecture conversion works out of the box. kc-copy uses pure Go (govmomi NFC), so it compiles and runs on any Unix host.
• Pluggable architecture - Go interfaces with a generic Registry[K,V] and init() self-registration. Add a new hypervisor or distro by dropping a file into pkg/<utility>/<block>/plugins/.

Architecture

The core pipeline is four binaries executed in sequence by an external orchestrator (kc-v2v, a shell script, etc.):

Binary	Purpose
kc-prepare	Open disks, inspect guest OS, mount filesystems, collect metadata
kc-convert-linux	Convert Linux guests: remove hypervisor tools, inject virtio, fix bootloader
kc-convert-windows	Convert Windows guests: install virtio-win drivers, update registry, firstboot scripts
kc-finalize	Unmount, trim, fsck, assign bus slots, determine firmware, emit TargetMeta JSON
kc-v2v	V2V orchestrator for Forklift: runs the pipeline + inspection HTTP (optional NFC disk copy for blank PVCs)
kc-copy	NFC disk copy stage via govmomi
kc-guest-agent	In-appliance PID 1 for --backend qemu (not run on the conversion host)

The tree compiles on any Unix host. kc-copy runs on any Unix. make build defaults to GOOS=linux (set GOOS=darwin for a native Mac binary). Guest disk backend requirements are documented in docs/architecture/backends.md.

Inter-app communication uses JSON files written to a shared directory, plus a shared mount point where the guest root filesystem is mounted.

Develop

See community/CONTRIBUTING.md for directory layout, dependencies, build, test, and PR guidance.

Documentation

Apps

• docs/README.md - Documentation index
• docs/apps/README.md - Complete conversion flow
• docs/apps/kc-v2v.md - V2V orchestrator (Forklift conversion pod)
• docs/apps/kc-copy.md - NFC disk copy stage CLI
• docs/apps/kc-guest-agent.md - in-appliance agent for the qemu backend
• pkg/v2v/README.md - kc-v2v libraries (copy, vsphere, env, inspection)
• build/kc-v2v/README.md - Container image, Forklift Plan config
• docs/apps/forklift-usage.md - Using kc-v2v with Forklift (MTV)
• docs/apps/examples/ - JSON samples and runnable example
• docs/apps/kc-prepare.md - kc-prepare pipeline
• docs/apps/kc-convert-linux.md - Linux converter pipeline
• docs/apps/kc-convert-windows.md - Windows converter pipeline
• docs/apps/kc-finalize.md - kc-finalize pipeline

Debug

• docs/debug/README.md - local Mac/Linux qemu conversion cookbook

Architecture

• docs/architecture/README.md - Architecture reference index
• docs/architecture/backends.md - Guest disk backends (direct, guestfs, qemu)
• docs/architecture/guest-os-handlers.md - Linux distro and Windows version classification, special cases, and code map
• docs/architecture/conversion-paths.md - OS + source-hypervisor conversion path reference

Contributing

• community/architecture.md - Design principles for contributors and agents
• community/CONTRIBUTING.md - Build, test, layout, and dependencies
• community/commits.md - Commit subject and message body conventions
• community/pull-requests.md - Branch naming and PR writing guidelines
• community/code-review.md - Code review priorities and report shape

License

This project is licensed under the GNU General Public License v3.0.