Migrating VMs to zCompute

The V2Z migration tool supports easy migration from supported virtualization platforms to zCompute VPC projects, with enhanced logging, human readable error messages and a complete rollback on migration failure.

Supported virtualization platforms

  • Hyper-V 2019

  • vSphere 6.7, 7.0 and later.

Supported guest VM OSes

  • Windows 2016 and 2019

  • Ubuntu 20.04

  • CentOS 7

V2Z migration prerequisites


Migration using the V2Z tool requires infrastructure preparations.

Contact Zadara’s Operations team for coordinating the migration’s planning and infrastructure setup stages.

zCompute importer VM prerequisites

The V2Z migration process runs on a VM instance referred to as the importer VM, configured on the destination cluster for the purpose of the migration.

  • The importer VM must have free space that amounts to double the used capacity of the VMs that are being migrated.

  • The importer VM must have network connectivity to the customer hypervisor as specified below.

  • The importer VM’s username and password must be configured in the V2Z config file.

Network prerequisites

The V2Z migration tool requires that the importer VM has access to the importer VM’s own zCompute API address or URL. This can be done by:

  • Using an Elastic-IP on the VM so it can access the cloud’s API via a public IP.

  • Using a direct subnet configured with an external router attached to it, and routing through this external router defined on the VPC’s route table.

  • Using a NAT gateway:

    • Creating a NAT gateway in a public facing subnet

    • In the private route table, add an entry with the NAT gateway as the destination

To run the migration, SSH access is required from the end user’s workstation to the importer VM. To enable SSH access, the security group associated with the importer VM must be updated, by adding an ingress rule that allows port 22/TCP (SSH port) from the end user’s workstation IP. See Security Groups in the Networking Guide.

Prerequites for migrating from VMware

  • Required port: 443

    V2Z migration via the vSphere API requires HTTP/S access between the zCompute toolbox VM and the vCenter and the ESXi hosts that are hosting the VMs to be migrated. This method uses HTTP GET to migrate the vmdk directly from the VMware environment.

  • The VMs to be migrated must be without snapshots.

  • The VMs to be migrated must be gracefully shut down from the VM guest operating system, as opposed to being forced power-off from the VMware management, for the migration process to succeed.

    If the NFS share (see below) option is implemented, the VM can be shut down after the NFS phase, reducing downtime.

The fastest migration option requires an NFS volume accessible to both the source virtualization platform (e.g. as a datastore for VMware ESXi hosts) and to the importer VM over a direct subnet to which it’s attached.


In order to reduce downtime, as an optional pre-import phase you can run storage vMotion to an NFS share residing on a VPSA, which will then be mounted as read-only onto the importer VM. Note that this will require accessing the NFS share via a direct subnet.

Using the NFS share option does not require the migrating VM to be shut down during this phase, as a result, reducing downtime.

Other, slower options involve copying the source VM’s virtual disks to the zCompute cloud from the virtualization platform’s management interface (e.g. HTTP copy of vmdk files from vCenter or ESXi hosts).

Prerequisites for migrating from Hyper-V

  • Windows Remote Management Service (WinRM)

    • Ports: 5985/TCP and 5986/TCP: The toolbox VM (migration VM) should be able to access the Hyper-V host over these ports.

    • WinRM must be installed, started and enabled (service to be enabled, allowed by group policy and local host firewall opened). See Installation and configuration for Windows Remote Management.

  • SSH (for SCP - secure copy) access from the Hyper-V to the importer VM (port 22/TCP).

  • PuTTY PSCP (secure copy client) must be installed on the Hyper-V environment.

  • The VMs to be migrated must be gracefully shut down from the VM guest operating system, as opposed to being forced power-off from the Hyper-V management, for the migration process to succeed.

  • All vhd/vhdxs must be fixed-size disks.

Importer user prerequisites

The migration process requires a user on the the target zCompute account project. The importer user’s details will be configured in a config file, and injected as environment variables in the migration process. A new user or an existing user can be used for the migration process.

Minimum permissions for the importer user:

  • Roles: Member

  • Symp API Policies:

    • ImagesReadOnlyAccess

    • StorageReadOnlyAccess

    • VMFullAccess

    • VolumesFullAccess

If the project is MFA-enforced, the MFA secret should be saved and added as an environment variable in the toolbox VM:

  1. Go to My Account > Details > Configure MFA.

  2. Follow the instructions to configure MFA for the account.

  3. Copy the MFA Key (Secret) to the clipboard before completing the MFA configuration.

  4. In the toolbox VM configure the MFA secret as an environment variable:

    export SYMP_MFA_SECRET=<MFA secret>

Installing the V2Z migration tool

From zCompute 22.09, the V2Z migration tool is supplied as part of the zCompute Toolbox.

  1. In the zCompute UI, go to Machine Images > Marketplace. If there are two zCompute Toolbox images, use the the v2.2.0 (or above) image.


    Do not use the Toolbox v21.0.0 image. It is deprecated and exists only for backward compatibility.

  2. In the Zadara apps list, click the zCompute Toolbox icon.

    In the dialog box that opens:


    If you connected as an account admin, it is recommended that the Scope is set to Account.

    Click Download.


    The image download takes a few minutes to finish. The download process is complete when the image appears with the status Ready in the Images UI screen. The zCompute Toolbox image is named “fedora-3x-zadara-toolbox-xxxxx” or similar. The image name can be modified at any time.

  3. Go to Compute > Instances > Create.

    • Enter the Compute parameters:

      • Name: A name for the importer VM

      • Create from: Image

      • Image: The zcompute-toolbox image downloaded in the previous step

      • Instance type: z4.xlarge 4 CPUs/16GB RAM and above


        z4.xlarge 4 CPUs/16GB RAM is the minimum instance type supported for the migration process.

      • Key Pair: Select the key pair sign to in to the VM over SSH. If no key pair exists for the user, create one using the + sign and follow the instructions to save the private key file.

      • Click Next.

    • Enter the Storage parameters:


      • The importer VM must have an additional data volume with free space that amounts to double the used capacity of the largest boot disk.

      • Boot Volume - disk size (GB) and volume type that will be used for the boot volume of the VM instance.

      • Data Volumes - add new or existing data volumes. To add a new volume, click Add and + and configure the following:

        • Name - volume name.

        • Description - description of volume.

        • Volume Type - select the volume type from the dropdown list.

        • Size - volume size (GB).

        • Protection Group - protection group for the volume.

      • Click Next.

    • Enter the Networking tab parameters according to the specific environment, and click Next.

    • In the Config tab you can optionally configure a cloud-config for cloud-init. For example:

      password: heychangeme
      chpasswd: {expire: False}
      ssh_pwauth: True

      Click Finish, and the VM will start.

  4. When the importer VM instance is ready:

    • Launch the importer VM in the target project, if it wasn’t started yet:

      • In the zCompute UI, go to Compute > Instances.

      • Select the migrated VM, and click Start.

    • Connect to the importer VM instance via ssh and the username fedora.

  5. Install Symp on the importer VM by running the following command:

    symp-update -c <Cluster IP> -k

  6. For migrations from Hyper-V only, enable SSH authentication using a password:

    • Sign in to the toolbox VM using ssh, with the user fedora and the private key of the key pair provided at the VM creation.

    • In the terminal window, edit /etc/ssh/sshd_config as root, e.g.:

      sudo vi /etc/ssh/sshd_config

    • Search for the entry PasswordAuthentication, and remove the leading # character (remark) from the begining of the line. The line should look like this:

      PasswordAuthentication yes

    • Save the update, and exit the editor.

    • Restart the SSH daemon:

      sudo systemctl restart sshd.service

    • Exit the ssh session, and sign on using the password you’ve just created.

  7. At the importer VM, configure V2Z for first usage by running:

    v2z config

    The following is an example of a configuration for a vCenter migration:

    [fedora@v2z-atp ~]# v2z config
    Logs for this migration will be available in /var/log/v2z/20220816083635.log
    20220816083635|INFO|ID:27101756-c316-4f67-8e3d-4c5208c39177|Getting config data from user
    Select V2Z source type:
    1 - vSphere
    2 - Hyper-V
    Please select source type (1 or 2): 1
    vCenter Host Name or IP  [<IP address>]:
    vCenter username  [root]:
    vCenter password  []:
    zCompute hostname or IP  [<hostname or IP address>]:
    zCompute user  [<username>]:
    zCompute password  []:
    zCompute project name  [default]:
    zCompute storage pool  [Zadara_VPSA_Compute]:
    zCompute Domain Name  [zadara]:
    zCompute importer VM Id [36d51e0b-8cf7-4b60-b9e9-018d4d223a3c]:
    20220816083706|INFO|ID:27101756-c316-4f67-8e3d-4c5208c39177|Successfully get the config from user
    20220816083706|INFO|ID:27101756-c316-4f67-8e3d-4c5208c39177|Modifying V2Z config file
    20220816083706|INFO|ID:27101756-c316-4f67-8e3d-4c5208c39177|Successfully modified V2Z config file
    [fedora@v2z-atp ~]#


    From zCompute 23.08, the zCompute storage pool parameter in the config file must have the Volume Type value.

  8. Test the importer VM’s connections, by running the following commands at the importer VM’s command line:

    • zCompute connection:

      The ability to run symp-update in an earlier step, and symp on the cluster confirms the connection.

    • vSphere connection:

      Run the command v2z vsphere vm-info <VM_NAME> to display information of a VM that you want to migrate.

    • Hyper-V connection:

      Run the command v2z hyperv vm-info <VM_NAME> to display information of a VM that you want to migrate.

    • NFS connection:

      Run the cat command on any text file in the NFS share.

Migrating VMs