Moving a VM: changing the node and pool
"Moving a VM" in vStack Center means two different operations with different mechanisms. Which one you choose depends on the problem you need to solve. If a node is going into maintenance, the machine needs to run on another node while its data stays where it is. If a pool is running out of space or being decommissioned, you need to move the data to another pool, and the node running the machine does not matter.
Live migration was introduced in 3.1.0: a running machine is moved to another node without stopping, and the guest OS continues running. Moving data between pools still requires the machine to be stopped.
This page describes moving a machine by stopping it first. This works on any version and does not require a separate privilege. For live migration, its prerequisites, and viewing progress, see "Moving and cloning VMs". If live migration is unavailable, plan a downtime window: when changing nodes, the downtime equals the time needed to stop and start the machine; when changing pools, it equals the time needed to copy the data.
Changing nodes uses placement at startup. When starting a machine, you select a node explicitly; without a selection, vStack Center chooses the least-loaded node in the ONLINE state. This does not work for every machine: remote startup and automatic placement are available for machines with disks in NVMe mode, while a machine using virtio-blk can start only on the node hosting its data pool.
Changing pools is data migration: a full ZFS send/receive cycle, followed by reregistration of the disks, snapshots, and the machine itself, then deletion of the source dataset. This is a lengthy operation that returns a single result: the result arrives after the entire cycle completes, rather than when copying starts. vStack Center does not show copying progress.
| Task | What to do | What moves | Key limitation |
|---|---|---|---|
| Free up a node for maintenance when downtime is unacceptable | Live migration to the selected node | Only execution; data stays in its pool | Available since 3.1.0; requires the Live Migrate VM privilege; the machine must be running |
| Free up a node for maintenance when downtime is acceptable | Stop the machine and start it on the selected node | Only execution; data stays in its pool | With virtio-blk, the machine can start only on the pool's node |
| Free up a storage pool | Migrate the machine to another pool | Data: disks, snapshots, VM registration | The VM is stopped; the target pool differs from the source pool |
| Create a quick copy alongside the source | Clone the machine | Nothing moves — a copy is created | The clone is always on the source pool; the operation uses the API |
Prerequisites
- Permissions for the machine: Cluster master can see any VM in the cluster; a regular
user can work only with machines in their VDCs (virtual data
centers). Starting and stopping require a VDC role of
role_id ≤ 3; - To change pools, the Cluster master role: migration is available only to this role;
- The target pool is imported on a node; otherwise, vStack Center cannot determine the pool's node and returns code -25307;
- A target pool name in the form
z02: a letter followed by two digits; - VDC quotas and cluster capacity allow the machine to start: startup checks both quotas and memory overcommitment;
- An agreed downtime window;
- vStack Center version 3.0.5 for VM cloning and 3.1.0 for live migration; moving a machine by stopping it first and migrating data between pools also work on earlier versions.
Step 1. Record the machine's current state
Before any move, you need to know three things: where the machine is now, which resources it uses, and whether it can run on another node at all.
- Open Provider Data Center → All Virtual Machines and find the machine. The State column shows its state, and Storage (GB) shows how much space it occupies.
- Open the machine card and check the General properties section: the node running it (Node), the machine's VDC, CPU (Cores), RAM, OS profile, and VM configuration version.
- Read the Disks table: the Name, Slot, Disk size (GB), Sector size, IOps limit, and MBps limit columns. Use it to calculate the amount of data to be copied and record the rate limits.
- Count the snapshots in the Snapshots table: the Name, Date of creation, and Size (GB) columns. The snapshot count must match after migration.
| What to record | Why |
|---|---|
| The node running the machine (Node) | Determine which node the machine needs to leave |
| The machine's data pool | Select a target pool that differs from the source |
| Disk mode — NVMe or virtio-blk | Determines whether the machine can start on a node other than the pool's node |
| State (State) | Determines whether the machine accepts a startup or migration command |
| Snapshot count | Verification after moving the data |
Disk mode is not shown as a separate field on the card. If the machine uses virtio-blk, you discover this when trying to start it on another node: startup is rejected with code -460.
Step 2. Stop the machine
Both operations require a stopped machine, so this step is shared.
- Open the VM card (or find the machine in the list), click Actions, and select the stop command.
- If the guest system does not respond to ACPI, set a forced shutdown timeout (0–999 seconds) or disable ACPI shutdown.
- Wait for State to change to "stopped". While the operation is in progress, the machine is locked: other commands for it are rejected.
The stop command accepts a suspended machine just as it accepts a running one.
Task A. Start the machine on another node
Use this before node maintenance: the data stays in its pool, and only the execution location changes.
- Make sure the machine's disks are in NVMe mode. A machine using virtio-blk can start only on the node hosting its data pool. Trying to start it on another node returns code -460.
- Open the VM card, click Actions, and select the start command.
- Select the target node. The node number ranges from 1 to the number of nodes in the cluster. If you leave automatic selection enabled, vStack Center chooses the least-loaded node in the ONLINE state. This is useful when starting many machines after maintenance.
- Wait for State to change to "running" and check the Node field in the General properties section. The node on which the machine actually started is shown there, for both explicit and automatic selection.
If there are no suitable nodes, code -458 is returned.
Restarting does not change the node: a restart uses the machine's current placement. To change nodes, you must stop the machine and then start it.
Task B. Move data to another pool
Use this when a pool is full or is being decommissioned. Migration copies data through a ZFS send/receive stream, reregisters the disks, snapshots, and machine, then deletes the source dataset.
- Select the target pool. Open Provider Data Center → Storage Resources: the ZFS pools table shows Health, Consuming, Scrubbing, Resilvering, Current node, and Capacity (RAW). Choose a healthy pool with no resilvering or integrity check in progress.
- Open the pool and, in the Properties section, compare Free with the total Disk size
(GB) of all the machine's disks. There must be enough free space for all disks. The
target pool name must have the form
z02. - Make sure the machine is stopped, or has been created but never started. Migration does not accept other states and returns code -25306.
- Open the VM card, click Actions, select migration, and specify the target pool.
- Wait for the cycle to complete. While it is in progress, the machine is locked, and the result arrives once, after copying, reregistration, and deletion of the source dataset. The log panel shows the operation's progress — click LOG.
- Verify the result: the snapshot count in the Snapshots table matches the count recorded before migration, and the source pool has more free space in Storage Resources. The API provides the exact disk placement across pools — see the API reference.
- Start the machine.
Migration to the same pool is prohibited and rejected with code -25305. Copying uses a limited set of transfer ports. When all of them are occupied by other migrations, code -25308 is returned. Retry the operation later.
Task C. Create a quick copy instead of moving the machine
Sometimes a copy solves the problem instead of a move: for example, you need to test an update on a duplicate machine. A clone is an instant copy-on-write copy of a stopped machine. The operation takes seconds regardless of disk size and uses almost no capacity.
Cloning is not available in the web interface. An administrator performs the operation through the API — see the API reference. Only the clone's name and description are specified.
- Stop the source machine: cloning a running machine is rejected with code -2603.
- Start cloning and specify the clone's name.
- Wait for the clone to appear in the All Virtual Machines list. It is created through the same sequence as a new machine: first a record, then assembly on the node.
The clone inherits the source's entire configuration and is created in the same VDC and on the same pool; this does not replace moving the machine. MAC addresses are generated anew, and addresses are allocated as during normal creation.
An existing clone retains its source. While the clone exists, the source cannot be deleted, and its migration will fail at the step that deletes the source datasets. This is a known limitation. Remove the clones first, then move the source.
Finishing the work
- Start the machine and verify that it is running: check State in the VM list and the Node field on the card.
- After changing pools, check the freed capacity in Storage Resources: the source pool will have more free space. The source dataset is deleted as part of the migration cycle; no separate command is required.
- Check that the disks and snapshots are present in the Disks and Snapshots tables on the machine card. The machine retains its rate limits: check IOps limit and MBps limit for the disks, and the bandwidth limit for the network ports.
- If the machine was moved for node maintenance, take the node out of service only after all of its machines have started on other nodes.
Verifying the result
| What to check | Where to look | Expected result |
|---|---|---|
| The machine runs on the required node | VM card, General properties section | The Node field shows the selected node |
| The machine is running | VM list, State column | The state indicates "running" |
| Snapshots are present | VM card, Snapshots table | The snapshot count matches the count recorded before migration |
| Disks are present | VM card, Disks table | The disk configuration and rate limits are unchanged |
| Space has been freed in the source pool | Storage Resources, Capacity (RAW) | The source pool's used capacity has decreased |
| Data has moved to the target pool | Through the API | The machine's pool and each disk's pool are the target pool |
If something goes wrong
| What you see | Cause | What to do |
|---|---|---|
| Error code -25300 | Migration is available only to the Cluster master role | Sign in with a cluster-level role |
| Error code -25306 | The machine is neither stopped nor in the "created" state | Stop the machine and wait for it to actually stop |
| Error code -25305 | The target pool is the same as the source | Select another pool: migration to the same pool is prohibited |
| Error code -25307 | The target pool's node could not be determined | The pool may not be imported. In Storage Resources, check the Current node column |
| Error code -25304 | The machine's node could not be determined | Check node states in Server Nodes |
| Error code -25308 | No transfer ports are available | Wait for other migrations to complete and retry |
| Error code -25310 | The migration cycle did not complete: reregistration failed | Check the machine and disk states on the card; do not start another migration until the cause is established |
| Error code -460 | The machine uses virtio-blk: it can start only on its pool's node | You cannot change the execution node. Migrate the data to a pool on the required node |
| Error code -459 | Windows in NVMe mode has not completed initial setup | Complete setup on the pool's node, then start remotely |
| Error code -458 | No nodes in the ONLINE state are available for placement | Bring nodes back into service or select a node manually |
| Error code -442, -443 | A nonexistent node is selected | Use a node number from the Server Nodes table |
| Error code -457 | The machine is already running | Stop it before starting it again |
| Error code -455 | The machine is suspended | Resume it, then start it |
| Error code -409 | The machine is locked by another operation | Wait for that operation to complete; the machine is unlocked automatically when the node responds |
| Error code -413, -414, -415 | The VDC's storage, memory, or core quota is exhausted | Free up or increase the quota |
| Error code -440 | Cluster memory is exhausted, accounting for overcommitment | Start on another node or free up memory |
| Error code -452 | Disks did not connect over the network during remote startup | Start the machine on its pool's node and check fabric connectivity |
| Error code -2603 | The clone's source is not stopped | Stop the machine before cloning |
| Error code -2605 | The machine is managed by a service, such as a software-defined router (Edge) | Service machines cannot be cloned |
| Error code -3001, -429 | No machine with this identifier is visible to you | Check the machine and permissions for its VDC |
| Migration appears "stuck" with no response | The result arrives once, after the entire cycle | Wait: the duration depends on disk size. Copying progress is not displayed |
| The machine does not start after migration | Placement changed or resources are insufficient | Check quotas and the availability of ONLINE nodes; start a machine using virtio-blk on the new pool's node |
Limitations
Migration progress is unavailable: the result arrives when the cycle completes and does not report how much data has been copied. Estimate the duration from the machine's disk sizes in the Disks table.
The target pool is specified by a name in the form z02. A pool with any other name format
cannot be specified as a migration target.
Migration cannot be canceled. If the cycle fails, check the machine's state by reading its card, rather than issuing another command.
See also
- The complete set of migration and cloning operations — "Moving and cloning VMs".
- The machine lifecycle and its states — "Virtual machine lifecycle".
- Selecting a target pool by capacity and health — "Viewing cluster pools".
- Taking a node out of service for maintenance — "Managing cluster nodes".
API methods
API operations on this page: vm-list, vm-get, vm-statuses,
vm-snapshot-list, vms-stop, vms-start, vms-restart, vm-migration,
vms-clone, pool-map-by-guid, pools-get, cluster-node-disable — see the
API reference.