Document host kernel / EL userland compatibility expectations for KubeVirt nodes
Description:
KubeVirt's documentation does not state any recommended or minimum host kernel version, nor does it explain that virt-launcher ships an Enterprise Linux (CentOS Stream / RHEL) based libvirt/qemu userland whose behaviour can depend on the host kernel matching that userland reasonably closely.
Host requirements today are framed purely in terms of capabilities — virt-host-validate qemu, presence of /dev/kvm, /dev/vhost-net, /dev/net/tun, and the kvm / vhost_net modules. There is no guidance that running the EL-based userland on a substantially different (particularly newer, non-EL) host kernel can change device feature negotiation in ways that break workloads.
This gap surfaced concretely in #16386: virtio-net USO features (VIRTIO_NET_F_GUEST_USO4/GUEST_USO6/HOST_USO, bits 54–56) are negotiated from the host kernel's tun/vhost-net capabilities. USO support landed in the mainline tun driver in kernel 6.2, whereas EL9's 5.14.z carries it only via selective backport. A node running a newer non-EL host kernel offers USO to the EL9 QEMU in virt-launcher, the guest enables it, and a subsequent QEMU packaging change (qemu-kvm-9.1.0-20.el9, which retroactively disables USO on rhel9 machine types) then rejects that device state on the migration target — breaking live migration of already-running VMs. Reporters in that thread did not have their host kernel/OS documented, and running a non-EL host kernel against the EL userland is a likely contributing factor.
What you expected:
The user guide (most naturally cluster_admin/installation.md, alongside "Validate Hardware Virtualization Support") should:
- Note that
virt-launcherbundles an EL-based libvirt/qemu userland. - Recommend running a host kernel aligned with that userland, and warn that significant divergence (especially newer, non-EL kernels) can cause virtio device feature-negotiation mismatches affecting live migration and other operations.
- Point at
virt-host-validateand the required KVM/vhost capabilities as today, but add the userland/kernel compatibility caveat.
URL: https://kubevirt.io/user-guide/cluster_admin/installation/
Additional context:
Related bug: #16386 (live migration of pre-upgrade VMs fails with Failed to load virtio-net / Operation not permitted due to USO feature bits). Root-cause analysis in that issue. The only existing host-kernel version note in the docs today is memfd/hugepages requiring kernel >= 4.14 (compute/virtual_hardware.md); there is no broader host kernel guidance.
Source: kubevirt/kubevirt