CHAPTER 21
VM Migration
VM migration moves a virtual machine from one SimpleVM host to another. You migrate a workload to perform host maintenance, balance load across hosts, replace hardware, move a VM closer to the storage or network it needs, or build toward a clustered, high-availability design. SimpleVM exposes a Migrate action in the management interface and supports the same operation through advanced command-line tools. Most administrators should start in the management interface; the command line is included for control, scripting, and troubleshooting detail.
This chapter works through migration in order: what each migration type requires, how local and shared storage change the options available to you, how to perform a live move and an offline move, and how to diagnose a migration that does not behave as expected. Administrators arriving from VMware can treat live migration as the SimpleVM equivalent of vMotion; that concept map is in Chapter 26, Advanced Administration and Command-Line Reference (see Section 26.8, VMware-to-SimpleVM Concepts).
- Understand the options — what live, offline, and cluster-managed migration each require (Section 21.1).
- Confirm readiness — host, CPU, storage, network, and firewall checks before any move (Section 21.2).
- Account for storage — why local storage usually means offline migration, and why shared storage enables live migration (Sections 21.3 and 21.4).
- Move the VM — live migration for running workloads (Section 21.5) and offline migration when downtime is acceptable (Section 21.6).
- Recover from problems — diagnose a failed or stalled migration without making it worse (Section 21.7).
21.1 Migration Overview
Overview
Migration is a planned administrative operation, especially for production VMs. The right method depends on whether the VM can tolerate downtime and on where its disk images live. Choosing the method before you start is what keeps a migration predictable.
The three migration types differ in whether the VM keeps running, how much downtime to expect, and what the storage must provide.
| Migration type | Best used when | Typical downtime | Storage requirement |
|---|---|---|---|
| Live migration | The VM should keep running while it moves to another host. | Minimal, but not always zero. Workload activity and network conditions affect the final switchover. | The VM disk images must be reachable by both the source and destination hosts during the migration. |
| Offline migration | The VM can be shut down first, or the workload is not time-sensitive. | The VM is unavailable while it is shut down and moved. | Shared storage helps but is not always required. Local storage usually means copying the disk image and defining the VM on the destination. |
| Cluster-managed migration | The VM is part of a cluster or high-availability design. | Depends on the cluster configuration and the operation performed. | Shared storage and consistent cluster networking are normally required. See Chapter 22, Configuring Host Clusters for Live VM Migration and High Availability. |
21.2 Migration Requirements
Overview
A successful migration depends on compatibility between the source host, the destination host, the VM configuration, the storage, and the network path between hosts. Treat the items below as a readiness gate: confirm them before you start, not while a move is in progress.
Before you begin
- You have administrative access to both the source and the destination SimpleVM host. The accounts and privilege model are covered in Chapter 17, User Access and Administrative Tasks (see Section 17.3, Privileged Tasks).
- Both hosts are installed, running, and reachable over the management network, and they run compatible SimpleVM versions. the supported version policy for migration between hosts.
- The destination host has enough CPU, memory, and storage capacity for the VM.
- The VM configuration is compatible with the destination host, including CPU features, firmware type, virtual devices, and attached media.
- The VM network exists on the destination host. If the VM uses bridged networking, the destination must reach the same network segment. See Chapter 14, Managing Virtual Networks (and Section 14.7, Connecting VMs to Virtual Networks) and Chapter 15, Managing Host Networking.
- The required firewall services and migration ports are allowed between hosts (see the note after the checklist).
- A recent backup or recovery point exists for important workloads. See Chapter 20, Backup and Recovery.
Migration readiness checklist
| Check | Why it matters | Where to verify |
|---|---|---|
| Host reachability | The source host must be able to contact the destination throughout the migration. | Ping, DNS lookup, host firewall rules, and the management interface. |
| CPU compatibility | A VM moved to a host with incompatible CPU features may fail to start or run unstably. | Host hardware inventory, CPU model comparison, or command-line checks. |
| Storage access | Live migration needs the running VM to keep access to its disk images during and after the move. | Storage pools, shared-storage mounts, and the VM disk paths. |
| Network compatibility | The VM must remain reachable on the correct network after it moves. | Virtual-network settings, bridge configuration, VLAN design, and guest network settings. |
| Firewall access | Migration traffic fails if host firewalls block management or migration connections. | Firewall page, allowed services, and the cluster/migration rules. |
| Workload state | High I/O or memory-write-heavy workloads can make live migration slow or cause it to fail. | VM performance graphs and an application maintenance window. |
21.3 Local Storage Migration Considerations
Overview
A VM uses local storage when its disk images live on one SimpleVM host and are not automatically available to other hosts. Local storage is simple and fast for single-host deployments, but it limits migration because the disk must move with the VM. The disk cannot be reached from the destination during a live transfer, so the running state has nowhere consistent to land.
For a running VM, live migration is designed around shared storage. When a VM uses only local host storage, plan for offline migration unless SimpleVM-specific tooling confirms a supported copy-based live workflow. the local-storage copy/import workflow and whether copy-based live migration is supported.
Procedure: Move a local-storage VM
Use this offline workflow when a VM's disks are local to the source host.
- Schedule a maintenance window for the VM, and confirm it has a current backup.
- Shut down the VM from the guest operating system where possible.
- Record the VM name, disk image paths, network settings, and any attached ISO or host-device configuration.
- Copy the VM disk image files to the destination host or a shared transfer location. the supported copy procedure.
- Define or import the VM on the destination host using the copied disk image and the recorded configuration. the supported import procedure.
- Start the VM on the destination and verify the guest OS, application, network, and storage behave as expected.
- Keep the original VM powered off until the migrated VM is fully verified.
Revert this change
If the migrated VM does not start or does not work correctly, shut it down on the destination and start the original VM on the source host. Do not run both copies at once unless the guest OS and application are designed for duplicate instances — running duplicates can cause IP conflicts, application data conflicts, or storage corruption.
21.4 Shared Storage Migration Considerations
Overview
Shared storage means the VM disk images are available to more than one SimpleVM host. This is the preferred foundation for live migration, clustering, and high availability, because the VM can move between hosts without copying its full disk image during the migration. Only the running memory state has to transfer, which is what makes a live move fast.
Shared storage requirements
- The storage location is reachable by both the source and destination hosts.
- The storage path or storage-pool configuration is consistent across hosts. the storage path and pool consistency requirements across hosts.
- The storage system provides reliable performance for the VM workload.
- The storage system supports the organization's backup, snapshot, and recovery requirements.
- The VM does not depend on a host-local ISO, disk image, or device that is unavailable on the destination.
21.5 Live VM Migration
Overview
Live migration moves a running VM from one host to another while the VM keeps operating. The migration transfers the VM's running state to the destination, then performs a final switchover. Users may notice little or no interruption, but the exact impact depends on workload activity, network speed, storage access, and host compatibility.
Before you begin
- Complete the migration readiness checklist in Section 21.2, Migration Requirements.
- Confirm the VM disk images are reachable by both hosts through shared storage.
- Confirm the destination has enough CPU and memory headroom to run the VM.
- Avoid starting a live migration during heavy backup, update, or high-I/O windows.
- Notify application owners when migrating production workloads.
Procedure: Live migrate from the management interface
- Sign in to the SimpleVM management interface on the source host.
- Open Virtual machines and locate the VM you want to migrate.
- Open the VM row action menu and select Migrate.
- Enter or select the destination SimpleVM host.
- Choose whether the migration is temporary or permanent. For most maintenance and host-balancing work, use a permanent migration unless you intentionally want the VM definition to remain on the source host.
- Review the migration summary and select Migrate.
- Wait for the migration to complete. Do not restart either host during the migration.
Verification
- The VM appears on the destination host and remains running after the switchover.
- If the migration was permanent, the source host is no longer responsible for the VM.
- The guest operating system keeps its expected network connectivity.
- Application services inside the VM continue to work.
Procedure: Live migrate from the command line
Use the command line when you need a controlled workflow, scripting, or troubleshooting output. The example uses an SSH-based libvirt connection to the destination host. Run command-line tasks under your named account with sudo rather than in a root shell; see Section 17.5, Command-Line Access.
Use --undefinesource only when the move is permanent and the source host should remove its VM definition after the migration succeeds. Omit it for an intentional temporary migration, or when support directs you to preserve the source definition.
Verification (command line)
On the destination host, confirm the VM is listed and running, then check the guest:
- Open the VM console and confirm the guest operating system is responsive.
- Confirm the VM still has network connectivity and that application services are working.
- Review host CPU, memory, storage, and network usage after the migration.
Revert this change
A completed live migration is normally reverted by migrating the VM back to the original host. First confirm the original host still has access to the same storage and network resources and that the reason for the first migration has been resolved.
21.6 Offline Migration
Overview
Offline migration moves a VM while it is shut down. It is safer for local-storage moves, hardware replacement, and lower-priority workloads where downtime is acceptable, and it removes the risk of a live migration failing because of a high memory-change rate or heavy I/O.
Before you begin
- Confirm the VM can be shut down during the maintenance window, and back up important data first.
- Record the VM configuration, including CPU, memory, disk, network, firmware, and boot settings.
- Confirm whether the VM disk is on shared storage or local storage.
- Confirm that users and application owners understand the expected outage.
Procedure: Offline migration using shared storage
- Shut down the VM from the guest operating system and confirm it is stopped on the source host.
- Migrate or define the VM on the destination host, pointing to the same shared storage location. the supported define/import step.
- Start the VM on the destination host.
- Verify the guest operating system, network connectivity, application status, and storage access.
- Remove or disable the old VM definition on the source host only after the migrated VM is verified.
Procedure: Offline migration from the command line
This example assumes the destination can access the VM storage, or that the environment has been prepared for the move. For local-storage VMs, copy and import steps may be required before the VM can start on the destination.
Verification
- The VM is listed on the destination host and starts successfully.
- The guest operating system boots without disk or network errors.
- The VM has the expected IP address, DNS behavior, and application connectivity.
- The VM is not accidentally running on both hosts.
Revert this change
If offline migration fails before the source VM definition or disk data is removed, keep the migrated copy powered off and restart the original VM on the source host. If the source definition or disk files were already removed, restore the VM from backup, or recreate the VM definition using the original disk images if they are still intact. See Chapter 20, Backup and Recovery.
21.7 Migration Troubleshooting
Overview
Most migration problems come from host reachability, firewall restrictions, incompatible CPU features, unavailable storage paths, or network differences between hosts. Start with the simplest checks before changing VM configuration. For symptom-based diagnosis across the whole product, see Section 25.9, Migration and Cluster Issues, in Chapter 25, Troubleshooting.
| Symptom | Likely cause | Recommended action |
|---|---|---|
| The Migrate action is unavailable. | The VM state, host configuration, or build may not support the selected workflow. | Confirm VM state, host connectivity, and SimpleVM version; check whether migration is offered from the current screen. |
| Migration fails immediately. | Destination unreachable, authentication failed, or firewall blocks the connection. | Verify DNS, IP reachability, administrator credentials, SSH access, and firewall rules between hosts. |
| Live migration starts but never finishes. | The VM changes memory faster than migration can transfer it, or the network is too slow. | Retry during a quieter period, reduce workload activity, or switch to offline migration. |
| VM appears on the destination but is paused. | The migration is still completing, or failed during final switchover. | Check the migration job status, host logs, and VM state before forcing power actions. |
| VM boots but has no network access. | The destination host network or bridge does not match the source. | Verify virtual network, bridge, VLAN, firewall, and guest IP settings. See Chapter 14 and Chapter 15. |
| VM cannot find its disk after migration. | The disk path or storage pool is not available on the destination. | Confirm shared-storage mounts, storage-pool status, permissions, and disk-path consistency. |
| Application errors after migration. | The guest or application detected a network, time, storage, or duplicate-instance issue. | Check guest and application logs, time synchronization, duplicate VM state, and application requirements. |
Useful command-line checks
The confirmed migration command reference is consolidated in Chapter 26, Advanced Administration and Command-Line Reference (see Section 26.7, Common Migration Commands).
When to stop and recover
Stop the attempt and move into recovery planning if the disk path is unclear, the VM appears registered on both hosts, the guest file system reports errors, or the workload owner reports application-level data issues. In those situations, avoid repeated power cycles and preserve the original source VM state until the issue is understood.
Chapter review
After completing this chapter, an administrator should be able to choose between live and offline migration based on downtime tolerance and storage model; confirm host, CPU, storage, network, and firewall readiness before a move; perform a live migration from the management interface or the command line and verify the VM on the destination; perform an offline migration for local-storage or downtime-tolerant workloads; revert a migration cleanly; and diagnose a stalled or failed migration without leaving a workload running on two hosts.