Migration

VM migration moves a VM from its current cluster node to another online node. Sylve transfers the VM’s managed ZFS dataset roots, recreates the VM on the destination, moves workload ownership, then cleans up the source only after a successful cutover.

Caution

This is not live migration, but it is designed to keep the interruption small. Sylve sends the bulk of the VM’s native ZFS data while the source remains online, then transfers only the final changes during cutover. On a healthy cluster with a fast link and a workload that has not changed heavily since the initial transfer, downtime can be measured in seconds.

Sylve uses native recursive ZFS send and receive with an incremental final sync, coordinated directly by its Go control plane. This keeps the move focused on the VM’s actual managed datasets instead of routing it through an extra storage abstraction. The VM is stopped only for the final sync and, when it was previously running, started automatically on the target.

What moves with the VM

Migration preserves the VM’s managed ZFS storage roots as a coordinated set. A VM with disks on several pools moves every root instead of flattening its storage into one pool. The resulting VM retains supported configuration such as its CPU topology, RAM, storage layout, supported options, network configuration, and Cloud-Init settings.

The following items are deliberately not copied to the target because they are host-specific or local to the source:

Item	What happens on the target
PCI passthrough devices	Removed from the migrated VM. Prepare equivalent hardware and attach it again if required.
CPU pinning	Cleared. Reconfigure pinning for the target host’s CPU topology.
ISO and CD images	Not transferred. A missing image is detached, so download it on the target and reattach it if needed.
VirtIO 9P shares	Not transferred when the shared dataset is unavailable on the target. Recreate the share after the required filesystem is present.
VNC port	Reassigned when the configured target port is already in use.

Open the migration dialog

Open the VM’s Summary page and select Migrate. The dialog lists the other online cluster nodes, so the source node cannot be selected accidentally. Selecting a target runs validation automatically.

The dialog uses three outcomes:

Outcome	Meaning
Migration not allowed	A blocking requirement is missing. Resolve every listed reason before the Migrate action becomes available.
Ready to migrate	All hard checks passed.
Warnings	Migration can continue, but one or more target-specific settings will be changed, skipped, or need attention afterward.

Walkthrough result

The walkthrough migrates a Home Assistant VM with a 32 GiB ZFS volume in 1 minute 6 seconds. The VM is powered off only for the final 12 seconds of the move.

ZFS reports 22.8 GiB used and 3.5 GiB referenced for the volume. These are different ZFS accounting values, not the volume’s provisioned size or the exact number of bytes sent over the network:

• Used includes space that ZFS accounts to the dataset, including space retained by snapshots and, on a parent dataset, its descendants.
• Referenced is the data reachable from the dataset’s current state. It does not include every byte retained by its snapshots or child datasets.

For this reason, a 32 GiB zvol can show a much smaller referenced value while ZFS still accounts for substantially more used space. The migration transfer size and duration also depend on compression, snapshots, the amount of data changed during the initial transfer, and the network link.

Before you migrate

Migration is available from the VM Summary page when another eligible online cluster node exists. It is intended for moving a normal, Sylve-managed VM between nodes in the same cluster.

Prepare the destination before beginning:

Requirement	Why it matters
An online target node	The target must be a different online cluster member.
Matching ZFS pool names	Every pool used by the VM’s managed storage must exist on the target with the same name. Sylve transfers the dataset into its existing pool namespace rather than choosing a replacement pool. See ZFS Pools.
No guest-ID collision	The VM ID must not already be used on the target by either a VM or a jail. VM and jail IDs share one cluster-wide namespace.
Working cluster connectivity	Sylve uses the cluster’s authenticated node-to-node access to check pools and transfer storage. The target must be reachable and support the current migration checks.
Usable backup targets	Every target used by an enabled backup job for this VM must exist, be enabled, and validate successfully from the destination node.
No competing work	A running lifecycle task, backup event, replication event, HA transition, or another migration for this VM blocks the move. Wait for it to finish.
Replication fully disabled	Disable the VM’s replication policy. If policy deletion or another transition is active, wait for it and the replication lease to clear before retrying. A stable disabled policy can remain and follows the VM to the destination.

The target selector lists only other online nodes. Selecting one automatically runs preflight validation. The Migrate button remains disabled until validation allows the move.

Review validation warnings

Some target differences are warnings, not blocks. Sylve shows them before you start and again if they are encountered during the move. Read each warning carefully because the VM configuration on the destination can differ from the source.

Warning	Destination behaviour
PCI passthrough	Host-specific PCI devices are dropped. Prepare and attach equivalent hardware on the target later if required.
CPU pinning	Host CPU pins are cleared because they are specific to the source topology. Reconfigure them after migration if needed.
Low free memory	Migration can proceed, but the target may not have enough available memory for the VM’s configured allocation.
Missing ISO or CD image	The VM starts without that attachment. Add the image to Downloader on the target and attach it again if needed.
Missing network switch	The affected NIC is omitted. Create the appropriate Standard Switch or Manual Switch on the target, then add the NIC again.
Missing VirtIO 9P shared dataset	The shared folder is skipped. Make the required filesystem available on the target before re-adding the share.
VNC port in use	Sylve assigns a free VNC port on the target. Review the VM’s console configuration after migration.
Stale VM dataset on target	A leftover dataset with the same VM path is replaced by the migrated data. Investigate it before continuing if it could contain data you need.

Start the migration

1. Open the VM’s Summary page and select Migrate.
2. Select the target node.
3. Wait for validation to finish. Resolve every blocking reason and review every warning.
4. Select Migrate to queue the operation.
5. Follow the progress dialog. You can close it while the migration continues in the background, then return to the VM Summary page to see its lifecycle state.

The progress dialog reports these phases:

Phase	What Sylve does
Preflight check	Rechecks target readiness, the VM configuration, and backup targets used by enabled jobs for this VM.
Initial replication	Creates migration snapshots and transfers the VM’s managed dataset roots to the target while the source can still be running.
Stop source	Records whether the VM was running and stops it when necessary.
Final sync	Transfers the changes made since the initial replication. This is part of the outage window.
Transfer ownership	Moves the VM’s shared guest-ID claim to the destination before the VM is imported there.
Start on target	Imports the VM on the target. A VM that was running on the source is started; a VM that was already stopped remains stopped.
Policy adjustment	Reassigns any disabled replication policy and rebinds the VM’s backup-job runners to the destination.
Cleanup source	Removes the migrated VM datasets and local VM metadata from the source.
Finalize	Confirms that the migration guard has been released and marks the task complete.

Cancellation and recovery

You can request cancellation only during Preflight check or Initial replication. Once cutover starts, cancellation is intentionally unavailable because the source may already be stopped and the target state is being committed.

If the dialog is closed, the task continues and can be reopened. If a failure occurs after cutover, Sylve keeps the migration protected and retries recovery safely instead of allowing conflicting VM, backup, or replication actions. Let the task reach a terminal state before making manual changes to either copy of the VM or its datasets.

After a successful move, open the VM on the target node and verify its console, networking, storage attachments, and any target-specific settings called out in the validation warnings.