# 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

<a id="v2z-prerequisites-ref"></a>

## V2Z migration prerequisites

### 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
    0.0.0.0/0 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](security-groups.md).

#### VPC Endpoint

From zCompute 23.08, a VPC endpoint allows a VM to access the system APIs
using an internal VPC IP address.

The API is available on the internal IP addresses 169.254.64.2 and
169.254.64.3, assuming that the cluster has more than 2 nodes.
The system also provides a DNS record resolvable to these IPs when the VPC
DNS service (coredns) is up, and a valid certificate is installed.

The DNS name:

* When a valid certificate with a wildcard CN is used, the DNS name is:
  `cloud.<parent-domain>`.

  For example, the DNS name for
  CN `*.example.com` is `cloud.example.com`.
* When a valid certificate with a regular CN is used, the DNS name is the
  same as the CN.

  For example, the DNS name for
  CN `test.example.com` is also `test.example.com`.

The cluster’s DNS name is returned in the `cluster_url` property of the
VM’s metadata response. For example, for a cluster with a certificate with
the CN `*.example.com`:

```console
curl -s http://169.254.169.254/openstack/latest/meta_data.json | jq -c .cluster_url

"https://cloud.example.com"
```

### 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.

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](https://docs.microsoft.com/en-us/windows/win32/winrm/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>`

<a id="v2z-installation-ref"></a>

## 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.
2. In the Zadara apps list, click the **zCompute Toolbox** icon.

   In the dialog box that opens:

   Click **Download**.
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
     - **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:
     * **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:
     ```console
     #cloud-config
     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:
   ```console
   [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 ~]#
   ```
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.

## Replacing Toolbox Windows VirtIO Driver

The zCompute Toolbox base image includes two versions of the Windows VirtIO
driver Red Hat Package Manager (RPM) files, located in the
`/virtio-win-rpms` directory:

* `virtio-win-0.1.171-1`
* `virtio-win-0.1.262-2` (default)

The following setup process replaces the virtio-win driver for the boot
volume of the input machine without requiring internet access.

This is particularly helpful for migrating legacy operating systems,
including end-of-life (EOL) OS versions, which might not support or be
compatible with the latest virtio-win driver.

### Switching the Virtio-Win Driver

* To switch to `virtio-win-0.1.171-1`:

  Run the following command:
  ```default
  sudo dnf install /virtio-win-rpms/virtio-win-0.1.171-1.noarch.rpm -y
  ```
* To revert to the default `virtio-win-0.1.262-2`:

  Run the following command:

  `sudo dnf install /virtio-win-rpms/virtio-win-0.1.262-2.noarch.rpm -y`

## Migrating VMs

See:

- [Migrating VMware VMs to zCompute](v2z-vmware-migration.md#migrating-vmware-to-zcompute)
- [Migrating Hyper-V VMs to zCompute](v2z-hyper-v-migration.md#migrating-hyperv-to-zcompute)