Virtual Machine and Storage Migration

Cockpit facilitates the migration of running virtual machines (VMs) and their virtual disks between physical Vapor hosts and storage pools without causing workload interruption or guest downtime.

---

1. Compute Live Migration

Compute live migration transfers the active runtime execution state (vCPUs and RAM) of a running VM from a source physical host to a destination physical host.

Depending on the storage architecture, Cockpit executes compute migration in one of two ways:

A. Shared Storage Migration

• Architecture: The VM's virtual disks reside on a network storage pool (e.g., NFS, OCFS2, or SAN) accessible to both the source and destination hosts.
• Workflow: Only the CPU state and memory pages are copied over the network to the target host. Because the virtual disks do not need to be duplicated or transferred, the switchover is completed within seconds.

B. Shared-Nothing Migration (Block Migration)

• Architecture: The VM's virtual disks are stored on local disks (e.g., local SSDs) of the source host.
• Workflow: Cockpit initiates a block-level copy of the virtual disk files over the network while the VM is running. Simultaneously, memory pages and CPU execution states are synchronized. Once the block and memory copies are fully synchronized, Cockpit executes the final switchover. Migration time depends on the disk volume size and network bandwidth.

Identity is preserved. When a compute migration completes, the VM keeps its Cockpit identity: its place in the inventory tree and any object-scoped permissions assigned to it move with it to the destination host. The VM is relocated in place rather than removed and re-imported, so you do not need to re-apply permissions or re-file it in a folder after migrating.

---

2. Storage-Only Migration

Storage migration transfers a VM's virtual disk files between different datastores (storage pools) on the same physical host while the VM remains active.

• Storage Copy Mode: Copies the underlying disk image (typically in qcow2 or raw format) block-by-block to the target storage pool.
• Auto-Pivot: Once the disk duplication is complete, Cockpit executes an automatic runtime pivot. The hypervisor redirects new disk write operations to the new target disk file and flushes remaining writes.
• Remove Source File (optional): Reclaiming the original disk image is off by default. When you enable the "Remove source file after migration completes" option, Cockpit deletes the source disk image only after the pivot succeeds. Leave it disabled to keep the original as a fallback.
• Destination validation: Before any copy begins, the destination path is validated on the host — it must resolve inside a known storage pool (paths that escape a pool are rejected) and must not overwrite an existing file. Choose a distinct destination filename if one already exists.

---

3. Advanced Migration Configuration

Administrators can configure the following advanced parameters when initiating a migration:

• Live: Toggles live migration mode. Disabling this executes an offline/cold migration (suspending the VM before moving it).
• Undefine Source (enabled by default, recommended): Removes the VM's XML definition from the source host once the migration succeeds — the standard "move" behavior. Leaving this disabled is not recommended: the VM then remains defined on both the source and destination hosts, which produces duplicate inventory entries and, on shared storage, risks disk corruption if the stale source copy is ever started. Only disable it when you deliberately intend to keep a copy on the source.
• Storage Copy Mode: Selects how disks are handled. None assumes the disks are already reachable on the destination (shared storage). Copy all performs a full disk copy (shared-nothing). Incremental copies only the differences against an existing base on the destination.
• Compressed: Compresses migration data in transit to reduce the volume transferred over the network, at the cost of source-host CPU.
• Auto Converge: Mitigates scenarios where the guest OS writes to memory (dirtying memory pages) faster than the network can copy it to the target host. When active, this setting dynamically throttles the guest VM's CPU execution rate to allow the memory sync to converge and complete the migration.
• Remove Source Disks (destructive): Available for compute-and-storage migrations. When enabled, the source disk image files are permanently deleted from the source host after a successful migration (CDROM/floppy devices are excluded). This cannot be undone.
• Network / Disk Mappings: Optionally remap the VM's source networks and disk paths to their equivalents on the destination host. Supplied mappings are validated against the destination before the migration starts.

Additional low-level flags — Persistent, Tunnelled, Allow-Unsafe, Verbose, Max Bandwidth, and Max Downtime — are exposed in Vapor's per-host migration dialog rather than the Cockpit wizard. Destructive flags (Remove Source Disks, Allow-Unsafe) there require an explicit acknowledgement before the migration can start.

---

4. Pre-Flight Validation and Trust

Before executing a migration, Cockpit performs the following validation. The list below reflects what is actually enforced today — review the operational notes for the checks that libvirt performs at switchover rather than up front.

• Host TLS Trust: Compute migration streams over qemu+tls://, which requires a mutual TLS trust relationship between the source and destination Vapor hosts. In the migration wizard this is an explicit step: after selecting a destination host, click Establish host trust. Cockpit exchanges and installs each host's CA certificate (restarting libvirtd on a host only when its trust store actually changed). The Start Migration button remains disabled until trust is established.
• Shared-Storage Scope Check: For compute-only migration (no storage copy), Cockpit verifies that every disk resides on a datastore marked shared. A compute-only migration of a VM with disks on local (non-shared) storage is rejected before it starts.
• Storage Destination Check (storage-only migration): The target path is validated on the host — it must resolve inside a known storage pool and must not overwrite an existing file. The wizard also performs a same-pool guard and an available-space check against the target datastore.
• Mapping Validation: When you supply explicit network or disk mappings, they are validated against the live destination host before the migration begins; a mapping that does not resolve on the destination fails the pre-flight.

Operational notes. Cockpit does not currently perform a proactive destination CPU-compatibility check or a general network-bridge check for every interface. libvirt still enforces these at switchover — a migration will fail if the destination CPU cannot run the guest's CPU model, or if a network the VM uses (and that you did not remap) does not exist on the destination. To avoid surprises, confirm that the destination host exposes the same virtual networks/bridges the VM uses, and that its CPU is compatible, before migrating. Broader automated pre-flight checks are planned.