docs(kubevirt): preserve TopoLVM VM data when reinstalling node OS (ACP-56362)

[Muyan0828]

Adds a solution for moving workload cluster nodes to a new operating system (for example off CentOS 7) while keeping the disks of KubeVirt VMs that live on TopoLVM local storage. Tracked in ACP-56362.

Approach

• Primary path: reinstall the system disk only and add the node back under the same hostname/IP. The LVM metadata lives on the data disks, so the PVC/PV/LogicalVolume objects keep pointing at the original LVs and the VMs start on their original PVCs.
• Safety net: clone each VM disk to Ceph RBD with a CDI DataVolume before the reinstall.
• Fallback: if the data disks are lost, recover TopoLVM on the node and clone the disks back from Ceph.

Pitfalls covered (all hit during validation)

• Data disk device names can swap after a reinstall (vdb ↔ vdc); the guide checks disks by content and fixes TopolvmCluster/CephCluster before the node rejoins, because the 4.1 TopoLVM operator can vgremove a VG whose PVs no longer match its config.
• The recreated Node object loses its taint state and the virtualization switch; a new control-plane:NoSchedule taint keeps virt-handler off the node.
• Removing a control plane node takes it out of the OVN database cluster, but adding it back does not; the guide covers restoring ovn-central membership and OVN_DB_IPS.
• A wiped data disk leaves a stale status.json in lvmdconfig-<node> that stops TopoLVM from recreating the VG.

Validation: run end to end on an ACP 4.1.7 cluster (TopoLVM 4.1.5, Rook-Ceph 4.1.5, KubeVirt 1.5.2 / CDI 1.62.0, Kube-OVN), moving nodes from CentOS 7.9 to RHEL 9.6. Test VMs covered both Block and Filesystem volume modes:

• primary path: after reinstalling the system disk, sha256 of all 4 disks matched the pre-reinstall baseline and the VMs booted on their original PVCs unchanged;
• fallback path: with the data disks wiped, TopoLVM was recovered, the disks were cloned back from Ceph (checksums matched), and the VMs booted.

Changing OVN_DB_IPS of the ovs-ovn DaemonSet is noted in the guide as not tested.

The id: field is omitted on purpose so CI assigns the KB id on merge; zh is generated by the translation job.

🤖 Generated with Claude Code