Issue

Use this article to troubleshoot storage migration, root-volume actual capacity, and residual task issues.

Environment

• Product: ZCF
• Component: Cloud
• Affected object: VM root volume/system volume
• Versions: 4.x, 5.x
• Scenario: Storage migration, root-volume actual capacity, or residual tasks

Symptoms

• A VM root volume, system volume, RootVolume, snapshot, migration, capacity, or performance path is abnormal.
• Platform state, underlying volume state, and guest OS partition/file-system results are inconsistent.
• Root-volume task completion state, migration state, or monitoring metrics are residual or missing.

Possible causes

• The primary storage hosting the root volume does not meet requirements with the cluster, physical host, image repository, or scheduling relationship.
• Guest OS partitions, LVM, file systems, or driver changes cause capacity, startup, or monitoring exceptions.
• After a snapshot, migration, reset, or task cancellation, platform state and underlying objects do not converge completely.

Resolution

1. Record vmUuid, rootVolumeUuid, primaryStorageUuid, hostUuid, clusterUuid, the task UUID, and failure time.
2. Compare platform RootVolume size/actualSize/installPath with guest OS partitions, LVM, and file-system state.
3. Check management-server logs, task logs, and underlying storage objects to identify failures in the snapshot, migration, reset, or monitoring path.
4. Before repairing a root-volume path, confirm backups, snapshots, image chains, the service downtime window, and rollback paths.

Key command

zstack-cli QueryVmInstance uuid=<vmUuid>
zstack-cli QueryVolume vmInstanceUuid=<vmUuid> type=Root
zstack-cli QueryPrimaryStorage uuid=<psUuid>
lsblk -f
df -h
grep -a -nE "<rootVolumeUuid>|<taskUuid>|snapshot|migrate|trash|actualSize" /usr/local/zstack/apache-tomcat/logs/management-server.log*

Remediation

• Based on the specific case, repair the root-volume scheduling relationship, capacity recognition, snapshot chain, migration residual state, or monitoring path.
• Because the root volume affects VM startup capability, preserve evidence and a rollback copy before handling it.

Verification

• Confirm that the symptom described in this article no longer occurs.
• UI, API, management-node logs, and underlying command output corroborate one another.
• Observe at least one related task or alarm cycle to confirm that the issue does not recur.

Risks and rollback

• Do not directly delete root-volume underlying files or snapshot chains, or modify volume state.
• A failed root-volume repair can prevent the VM from starting or make data unrecoverable.

Notes

• For snapshot chains, volumes, primary storage, image repositories, LV/RBD/qcow2 files, or database records, complete backups and read-only verification first. Do not delete underlying objects until dependencies are confirmed.
• For VM startup, migration, HA, Unknown status, or forced stop operations, first confirm the actual VM running location to prevent split-brain operation, dual writes, or unintended service interruption.
• If database modifications, underlying file operations, lock release, service restarts, driver or firmware upgrades, or bulk resource changes are required, contact ZStack technical support before proceeding.