Document navigation

Overview

The migration service migrates VM operating systems and data from a source platform to ZStack ZSphere. This chapter describes migration from VMware vSphere environments. The source platform provides the VMs to migrate, data gateways transfer migration data, and the target platform hosts the migrated VMs.

Before using the migration service, upload its installation package, deploy the service, and upload the required VDDK packages. Then add the source platform. When creating migration tasks, check the source VMs and configure target resources. After data synchronization, you can create test VMs to verify the migration results before performing cutover. After migration, remove migration snapshots and tasks as needed.

Step 1: Upload the Migration Service Package

After uploading the installation package, the system automatically decompresses it and extracts the required files.

  • Ensure that the migration service license is installed on the platform and that you have sufficient license capacity.
  • Prepare the migration service installation package in .tar.gz format.
  • Ensure that an image storage is added to the platform and that the image storage has sufficient storage space.
  1. In the navigation pane, select O&M Management > Migration Service.
  2. On the Migration Service page, click Upload.
  3. In the Upload Migration Service Package dialog, configure the following options:
    Option Description
    Upload By Select the method for uploading the installation package, including URL and local file. Interrupted local uploads can be resumed.
    Note:
    • The system automatically retries recoverable upload errors. If an upload is paused due to a network interruption and the page remains open, the upload resumes automatically after the network recovers.
    • If the browser retains permission to access the original local file after the page is refreshed or you sign in again, the system automatically resumes an upload that was paused due to an error. If the browser prompts you to allow access to previously selected files or folders, grant access as needed.
    • If the browser does not have permission to access the file or the permission has expired, the upload cannot resume automatically. Click Pending Uploads at the top of the page. In the Pending Upload Tasks panel, locate the task, click Select to Continue, and reselect the same local file.
    • A manually paused task does not resume automatically. In the task details, click Continue.
    • If the local file has been modified, moved, or deleted, the original upload task cannot resume. Start a new upload.
    • If an upload error occurs, the platform automatically retries the upload up to five times. If all five retry attempts fail, the upload task enters the Failed state and cannot be resumed. Start a new upload.
    • Click View Upload History to view local file upload tasks.
    URL / Installation Package Enter a URL or upload the installation package file.
    Storage Path Specify a directory path to store the uploaded installation package and its decompressed files.
    Note:
    • Ensure that the directory has sufficient available space. Otherwise, the installation fails.
    • Do not use system directories such as /, /dev, /proc, /sys, /usr/bin, /bin, or /opt. Using these directories might cause server issues.
  4. Review the configuration and click OK.

Step 2: Deploy the Migration Service

Select the appropriate resources for your business requirements and deploy the migration service. After deployment, upload the required VDDK packages before using the migration resource and task features.

  1. On the Migration Service page, click Install.
  2. In the Deploy Migration Service dialog, configure the following options:
    Option Description
    Migration Service Version Displays the version of the service to be installed and deployed.
    Data Center The migration service is deployed as a data gateway VM. Select a data center.
    Location Select where the service runs.
    CPU The default is 8 cores. Set the number of CPU cores.
    Memory The default is 8 GB. Set the memory size.
    Storage Location Specify the data storage.
    Storage Pool When the storage location is distributed storage, specify a storage pool.
    Disk 1 The default is 100 GB. Set the system disk size to at least 100 GB.
    Migration Network Specify a distributed port group to use as the migration network. Ensure that the selected distributed port group has network connectivity with both the source and target platforms.
    IPv4 Address Specify an IP address.
    Note: The IP address allocation method depends on the configuration of the selected migration network:
    • When DHCP is enabled on the migration network, the system automatically assigns an IP address.
    • When DHCP is disabled on the migration network, you need to specify an IP address.
    • When IPAM is enabled on the migration network, manually specified IP address must be within the selected network segment.
  3. Review the configuration and click OK.

After deployment, the migration service page displays Migration Overview and Service Management. Continue by uploading the VDDK packages from Migration Overview.

Step 3: Upload VDDK Packages

VMware licensing requires you to obtain and upload the VDDK packages yourself. The migration service must be enabled and VDDK uploads must be complete before you can access the migration resource and task pages.

  • The migration service is deployed and enabled.
  • You have the original VDDK 6.7.3 and 8.0.3 packages for Linux. Both files must be in .tar.gz format.
  1. In the navigation pane, choose O&M Management > Migration Service > Migration Overview.
  2. Click Go to Upload in the VDDK notification or the VDDK item in the basic information.
  3. In the Upload VDDK dialog, select both original packages under VDDK Packages.
    Both versions are required. If an upload task is already running, wait for it to finish.
  4. Verify the files, click OK, and wait for the upload to complete.
    If the upload fails, reselect both original packages and try again. If the VDDK status is unavailable, refresh the page and try again.

On Migration Overview, confirm that the VDDK status is Uploaded. Before you add a source platform, also verify that VDDK 6.7.3 and 8.0.3 are ready on the data gateway you will use. A completed package upload does not mean that distribution to every data gateway is complete.

Upgrade the Migration Service

  • Ensure that no migration tasks are in progress. Otherwise, you cannot upgrade the migration service.
  • Ensure that the image storage has sufficient storage space before you upload the migration service upgrade package.
  • Prepare an upgrade package with a version higher than the current service version, in .tar.gz format.
  1. In the navigation pane, select O&M Management > Migration Service > Migration Overview.
  2. On the Migration Overview page, click Upgrade.
  3. In the Upgrade Migration Service dialog, configure the following options:
    Option Description
    Migration Service Version Displays the currently deployed service version.
    Upload By Select the method for uploading the installation package, including URL and local upload. Interrupted local uploads can be resumed.
    Note:
    • The system automatically retries recoverable upload errors. If an upload is paused due to a network interruption and the page remains open, the upload resumes automatically after the network recovers.
    • If the browser retains permission to access the original local file after the page is refreshed or you sign in again, the system automatically resumes an upload that was paused due to an error. If the browser prompts you to allow access to previously selected files or folders, grant access as needed.
    • If the browser does not have permission to access the file or the permission has expired, the upload cannot resume automatically. Click Pending Uploads at the top of the page. In the Pending Upload Tasks panel, locate the task, click Select to Continue, and reselect the same local file.
    • A manually paused task does not resume automatically. In the task details, click Continue.
    • If the local file has been modified, moved, or deleted, the original upload task cannot resume. Start a new upload.
    • If an upload error occurs, the platform automatically retries the upload up to five times. If all five retry attempts fail, the upload task enters the Failed state and cannot be resumed. Start a new upload.
    • Click View Upload History to view local file upload tasks.
    URL / Installation Package Enter a URL or upload the installation package file.
    Storage Path Specify a directory path to store the uploaded upgrade package and its decompressed files.
    Note:
    • Ensure that the directory has sufficient available space. Otherwise, the installation fails.
    • Do not use system directories such as /, /dev, /proc, /sys, /usr/bin, /bin, or /opt. Using these directories might cause server issues.
  4. Click OK.

Check the upgrade status on Migration Overview. If the upgrade fails, click Reupgrade:

  • If the package was uploaded successfully but upgrade execution failed, select Use Existing Upgrade Package or Reupload Upgrade Package under Upgrade Method.
  • If the upgrade package upload failed, upload the package again.

Review the configuration, click OK, and wait for the upgrade to finish.

Enable or Disable a Migration Gateway

Control the running state of a migration gateway VM from Service Management.

A disabled migration gateway can be enabled, and a running migration gateway can be disabled.
  1. In the navigation pane, select O&M Management > Migration Service > Service Management.
  2. On the Service Management page, select the target migration gateway. Under Actions, click Enabled or Disable as needed.
    A disabled gateway cannot process new migration tasks. When disabling a gateway, read the risk notice in the confirmation dialog and click OK.

Delete a Migration Gateway

Delete a migration gateway VM that is no longer needed from Service Management.

  • Only disabled migration gateways can be deleted.
  1. In the navigation pane, select O&M Management > Migration Service > Service Management.
  2. On the Service Management page, select the target migration gateway, and then click Actions > Delete.
    Note: Deleting a migration gateway cannot be undone and might affect related migration tasks. Proceed with caution.
  3. After you read and confirm the risk information, click OK.

Uninstall the Migration Service

When you no longer need the migration service, uninstall it from Migration Overview to remove its installation package and proxy configuration.

  1. In the navigation pane, choose O&M Management > Migration Service > Migration Overview.
  2. Click Uninstall Service.
    Note: Uninstalling removes the migration service package and proxy configuration. Proceed with caution.
  3. Read the risk notice in the confirmation dialog, enter uninstall, and click OK.

After uninstallation, the migration service page returns to the deployment entry point.

Add a Source Platform

The migration service is enabled and the required VDDK packages have been uploaded. The data gateway used to connect to the source platform must be available, with both VDDK 6.7.3 and 8.0.3 ready.

  1. In the navigation pane, select O&M Management > Migration Resources > Source Platform.
  2. On the Source Platform page, click Add Platform.
  3. In the Add Platform dialog, configure the following options:
    Option Description
    Name Set a name for the source platform.
    Data Gateway Configuration Method Choose Select Existing or Enter the server IP address to specify the data gateway used to connect to the source platform.
    Data Gateway Select an existing data gateway. The list includes only available gateways with VDDK ready. If the target gateway is missing, check its connection and VDDK status first.
    Data Gateway IP When selecting an existing gateway, verify its IP address. When entering the server IP address, enter the data gateway's IP address.
    Platform Type VMware.
    vCenter/ESXi Address Enter the address of the VMware environment.
    Username Enter the login username.
    Password Enter the password for the username.
    Connectivity Test Click Check to verify that the specified gateway can connect to the source platform. The check must pass before you can confirm the addition. Repeat the check after changing connection information such as the gateway, address, username, or password.
  4. Review the configuration and click OK.

Check ESXi Hosts

After adding the source platform, use ESXi Host Precheck to investigate connection issues between the data gateway and individual ESXi hosts:

  1. On the Source Platform page, select the target platform and click Actions > ESXi Host Precheck.
  2. In the precheck dialog, expand a host to review the results and descriptions for DNS resolution, HTTPS port connectivity, and NFC port connectivity.
  3. If a check fails, resolve the corresponding network or DNS issue and click Recheck.

Delete a Source Platform

  1. In the navigation pane, select O&M Management > Migration Resources > Source Platform.
  2. On the Source Platform page, select the target source platform, and then click Actions > Delete.
  3. Review the selected source platform and risk notice, then click OK to confirm deletion.

Add a Data Gateway

Deploy a data gateway as a new VM to connect to source platforms and transfer migration data.

  1. In the navigation pane, select O&M Management > Migration Resources > Data Gateway.
  2. On the Data Gateway page, click Add Data Gateway.
  3. In the Add Data Gateway dialog, configure the following options:
    Option Description
    Name Set a name for the data gateway.

    Configure resources and networking for the gateway VM:

    Option Description
    Data Center Select the data center where the VM resides.
    Location Select where the VM runs.
    CPU The default is 8 cores. Set the number of CPU cores.
    Memory The default is 8 GB. Set the memory size.
    Storage Location Specify the data storage.
    Storage Pool Select a storage pool when the storage location is Ceph distributed storage.
    Disk 1 The default is 100 GB. Set the system disk size.
    Network Specify a distributed port group. Ensure that the selected distributed port group has network connectivity with both the source and target platforms to support data transfer.
    IPv4 Address Specify an IP address.
    Note: The IP address allocation method depends on the configuration of the selected migration network:
    • When DHCP is enabled on the migration network, the system automatically assigns an IP address.
    • When DHCP is not enabled on the migration network, you must manually specify an IP address.
    • When IP address management is enabled on the migration network, if you manually specify an IP address, ensure that the address is within the selected network segment.
    Subnet Mask and IPv4 Gateway If DHCP is disabled on the network, enter the subnet mask and IPv4 gateway for the gateway VM.
  4. Review the configuration and click OK.

After the gateway VM is created and connected, the system distributes VDDK to it. In the data gateway list, verify the connection status and readiness of VDDK 6.7.3 and 8.0.3.

If VDDK shows Distributing, wait for distribution to finish. If it shows Not ready or Installation failed, click Retry. If the version is shown as "-" with a query failure or timeout message, click Refresh to query it again.

Delete a Data Gateway

  1. In the navigation pane, select O&M Management > Migration Resources > Data Gateway.
  2. On the Data Gateway page, select the target data gateway, and then click Actions > Delete.
  3. After you read and confirm the risk information, click OK.

Create a Migration Task

The source platform has been added. Make sure that the available migration license points and capacity licenses meet the requirements of this migration.
  1. In the navigation pane, select O&M Management > Migration Tasks > All Tasks.
  2. On the All Tasks page, click Create Migration Task.
  3. In the Create Migration Task dialog, configure the source platform:
    Option Description
    Source Platform Select the source platform.
    Source VM Add the source VMs to migrate.
    Note: For each source VM whose disk capacity exceeds the following allowance, sufficient capacity licenses are required for the excess capacity:
    • Trial: 1 TB.
    • Official License: 5 TB.
    Migration Authorization Type Select the license type and check the available points. Recreating a migration task for a source VM with an active license does not consume additional points while that license remains valid.
  4. Click Check to review precheck results for the selected source VMs.

    You cannot continue if the precheck fails, results are incomplete, or any item is Failed. Risk items alone do not prevent you from continuing, but review their descriptions first.

    Check ItemResult Description
    Snapshot CheckReports Risk if the source VM has snapshots.
    Snapshot Count (Under 5)Reports Risk if the snapshot count is 5 or higher.
    Snapshots and CBT CheckReports Risk if the source VM has snapshots and CBT is disabled.
    Disk Count CheckReports Failed if the disk count is 0.
    NIC Count CheckReports Failed if the NIC count is 0.

    After resolving issues, click Recheck. If you change the source platform or add VMs to the selection, check the currently selected VMs before proceeding.

  5. Click Next.
  6. Configure the target platform.
    1. Complete the VM configuration:
      Option Description
      Data Center Select the data center where the VM will reside after migration.
      Cluster Select the cluster where the VM will reside after migration.
      Host Select the host where the VM will reside after migration.
      Storage Location Select the data storage that the VM will use after migration.
      Bus Type Select the bus type for the VM disk device.
      CPU Mode Select the CPU mode for the VM after migration.
      Target Port Group Select the distributed port group that the VM will use.
      Security Group Select a security group.

      When configuring Target Port Group, use the following options:

      Option Description
      CIDR If IPAM is enabled on the selected target network, select the corresponding CIDR.
      NIC Configuration Select whether to clone the source VM's network configuration and MAC address.
      • Clone Network Configuration: Uses the source VM's IP address as the target IP. This option is available only when all selected source VMs have IP addresses and DHCP is disabled on the target network.
      • Clone MAC Address: The target VM retains the same MAC address as the source VM.
      Note:
      • Configure the target IP, subnet mask, default gateway, and temporary network for each VM on the subsequent confirmation page.
      • After cloning the network configuration, power off the source VM before starting the target VM or performing cutover to avoid IP address conflicts.
    2. Complete the cutover configuration by referring to the following example:
      Option Description
      Immediate Cutover When enabled, the system automatically performs cutover after the initial data synchronization is complete.
      Create Rollback Snapshot When enabled, the system creates a rollback snapshot for the target VM when cutover starts.

      Purpose of the rollback snapshot:

      • When enabled, tasks in Cutting Over or Cutover Failed status can use "Delete cutover program and roll back target instance" to restore the target instance to its pre-cutover state.
      • This rollback policy is not offered for tasks in Cutover Success status.
      Auto Shut Down Source VM When enabled, the system shuts down the source VM before cutover. Confirm activation as prompted and select a Shutdown Method:
      • Graceful Shutdown: Requires VMTools to be installed and running on the source VM. The operating system stops processes normally before powering off.
      • Power Off: Forcibly terminates running processes and powers off the VM. This might cause data loss or file system damage. Proceed with caution.
      Auto Install VMTools When enabled, the system automatically installs VMTools after the target VM operating system is converted.
  7. Click Next.
  8. On the confirmation page, review each VM's configuration. To make changes, click Edit Configuration for that VM.

    Verify resources, networking, and cutover settings for each VM. Configure network parameters according to the following conditions:

    OptionDescription
    Target IP AddressWhen cloning network configuration, the source VM's IP address is retained. Otherwise, verify or change the target IP. An address is required when DHCP is disabled on the target network and can be assigned automatically when DHCP is enabled. On IPAM-enabled networks, the address must be within the available range of the selected CIDR.
    Subnet Mask and Default GatewayVerify and complete these settings when cloning network configuration or when DHCP is disabled on the target network.
    Temporary Port GroupWhen cloning network configuration, select a temporary port group for temporary network connectivity during migration.
    Temporary IP AddressThe address can be assigned automatically when DHCP is enabled on the temporary network. Otherwise, specify the temporary IP, subnet mask, and temporary default gateway. If IPAM is enabled on the temporary network, select a CIDR and make sure that the address is within its available range.

    After saving each VM's configuration, review the messages in the confirmation list. Complete missing settings and resolve issues such as invalid addresses.

  9. Review the configuration and click OK to submit the migration tasks.

Synchronize a Migration Task

The migration task is in Sync Stopped or Ready for Cutover status.
  1. In the navigation pane, select O&M Management > Migration Tasks > All Tasks.
  2. On the All Tasks page, select the migration task that you want to synchronize, and then click Actions > Synchronize.
  3. In the Synchronize Migration Tasks dialog, select the synchronization mode.
    The following two synchronization modes are supported:
    • Incremental Sync: Only synchronizes data that has changed since the last synchronization.
    • Full Sync: Synchronizes all data of the VM. For migration tasks that have completed initial synchronization, the system performs a comparison scan before executing a full sync. This process may take a significant amount of time.
  4. Click OK to submit the synchronization task.

After submitting the synchronization task, monitor its progress in the task list and wait for synchronization to complete.

Create a Test VM

The migration task is in Ready for Cutover status.
  1. In the navigation pane, select O&M Management > Migration Tasks > All Tasks.
  2. On the All Tasks page, select the target migration task, and then click Actions > Test > Create Test VM.
  3. In the Create Test VM dialog, configure the following options:
    Option Description
    CPU Set the number of CPU cores for the VM.
    Memory Set the memory size for the VM.
    Network Select the distributed port group that the VM will use.
    CIDR If DHCP is enabled on the selected network, select an available CIDR.
    IPv4 Address Specify an IPv4 address for the test VM.
    • If DHCP is enabled on the network, select or specify an available address in the address selector.
    • If DHCP is disabled on the network, enter the IPv4 address manually.
    • If address ranges are configured for the network, the specified address must be within an available range.
    Subnet Mask and Default Gateway If DHCP is disabled on the network, verify and enter the subnet mask and default gateway.
    System Conversion Policy Specify the system conversion policy to apply before the VM starts.
    Data Recovery Point Use a snapshot or copy from a specific point in time to test VM recovery.

    When you configure System Conversion Policy, select one of the following options:

    Option Description
    Perform System Conversion Performs a full system conversion, including: driver replacement/injection, network adapter name and IP address configuration for the target VM, and post-script execution.
    Perform System Conversion Without Loading Target Drivers Skips driver replacement. Only configures the target VM's network adapter name and IP address, and executes post-scripts.
    Skip System Conversion No driver replacement, no network configuration (adapter name/IP address), and no post-script execution. You will need to log in to the target VM and manually perform these configurations.
  4. Review the configuration and click OK.

Perform Cutover

  • The migration task is in Ready for Cutover status.
  • If the source VM's network configuration is cloned, power off the source VM before cutover or verify that automatic source VM shutdown is configured to avoid IP address conflicts.
  1. In the navigation pane, select O&M Management > Migration Tasks > All Tasks.
  2. On the All Tasks page, select the target migration task, and then click Actions > Cutover.
    After cutover starts, VM workloads switch to the target platform. If Auto Shut Down Source VM is enabled for the migration task, the system shuts down the source VM by using the selected shutdown method.
  3. Read and confirm the risk information, enter cutover as prompted, and click Confirm to Cutover.

After submitting the cutover request, monitor its progress and result in the task list.

View and Delete Migration Snapshots

After a migration task's cutover succeeds or fails, you can view its migration snapshots by disk and delete them when they are no longer needed.

The migration task is in Cutover Success or Cutover Failed status. You can view snapshots for only one migration task at a time.

  1. In the navigation pane, choose O&M Management > Migration Tasks > All Tasks.
  2. Select the target migration task and click Actions > Snapshots.
  3. In the snapshots dialog, review Snapshot Name, Snapshot Time, and Snapshot Size for each disk.
    If you only need to view the snapshots, click Close when finished.
  4. To remove the snapshots, click Delete All.
    Note: This operation deletes all migration snapshots displayed for the current task. Make sure that you no longer need these snapshots.
  5. Review the snapshots and their count in the confirmation dialog, then click Delete.

After the snapshot deletion task finishes, check the list for any remaining snapshots. If a message indicates that the deletion result could not be confirmed, wait for the list to refresh and check again.

Delete a Migration Task

  • Tasks in Pending Sync, Syncing, Sync Stopped, Sync Failed, or Ready for Cutover status proceed directly to deletion confirmation. The migration tasks and associated target instances are deleted.
  • Tasks in Cutting Over, Cutover Success, or Cutover Failed status require a deletion policy first.
  • These two categories cannot be deleted together in one batch. Select and delete them separately.
  1. In the navigation pane, select O&M Management > Migration Tasks > All Tasks.
  2. On the All Tasks page, select the target migration task, and then click Actions > Delete.
  3. If the Deletion Policy dialog appears, select an applicable policy and click OK. If deletion confirmation appears directly, proceed to the next step.
    Option Description
    Retain target instance, delete migration task Retains the target instance, deletes the migration task and related records, and removes the task's associated migration snapshots. You must manage the target instance separately afterward.
    Delete target instance, delete migration task Deletes the migration task record and its associated target instance. You can reconfigure the source VM and create a new migration task later.
    Delete cutover program and roll back target instance Deletes the cutover program, restores the target instance to its pre-cutover state, and retains associated migration snapshots. State and data changes made during cutover are lost. Proceed with caution.

    This policy applies only to tasks in Cutting Over or Cutover Failed status with Create Rollback Snapshot enabled. It is not offered if a batch includes a task in Cutover Success status. It is unavailable if any selected task does not have rollback snapshots enabled.

  4. Review the tasks, risk notice, and associated snapshots in the confirmation dialog. If a confirmation word is required, enter delete, then click OK.
    When retaining target instances, the confirmation dialog lists the migration snapshots that will also be deleted. Check the deletion scope before confirming.