Chapter 5. Migration

This section describes the actual migration process, while you are running the migration plan.

5.1. Workflow

The diagram below provides a high-level view of the infrastructure migration workflow. An understanding of this workflow will greatly simplify troubleshooting.

Migration Workflow

migration workflow

  1. The Infrastructure Admin creates an infrastructure mapping and a virtual machine migration plan in CloudForms and runs the migration plan.
  2. CloudForms locates the virtual machines to be migrated based on the infrastructure mapping.
  3. The ESXi host fingerprint is captured for authentication during the conversion process if the VDDK transport method is used. If SSH is used, a shared SSH key is used to connect to the ESX host where the virtual machine resides.
  4. Using the RHV attributes for the target environment, CloudForms initiates communication with the RHV conversion host.
  5. The RHV conversion host connects to the source datastore through the ESX host, using virt-v2v-wrapper.py, and streams the disk to be converted to the target data domain chosen in the infrastructure mapping using virt-v2v.
  6. After the disk is converted, the target virtual machine is created in RHV. During creation, the target virtual machine uses the source virtual machine’s metadata to maintain the virtual machine’s attributes (tags, power state, MAC address, CPU count, memory, disks, and virtual machine name) after migration.
  7. After the virtual machine is created, the disk is attached to the target virtual machine.

The virtual machine migration is complete and its status is displayed in CloudForms.

Note

Depending on the source virtual machine’s power state before migration, the virtual machine is either left powered off after migration or is powered on.

5.2. Troubleshooting

5.2.1. Retrying a Failed Migration Plan

If one or more virtual machines in a migration plan fails to migrate, the plan’s migration status is Failed. You can retry a migration plan to migrate the virtual machines that failed to migrate:

  1. Click the migration plan to go to the details page to identify the virtual machines that failed to migrate.
  2. Delete the target virtual machines corresponding to the source virtual machines that failed to migrate. Otherwise, the retry will fail because a target machine with the same name already exists.
  3. Click Compute → Migration, select Failed Migrations, select the failed migration plan, and click Retry.

5.2.2. Remigrating Virtual Machines

If a migration fails or if your migration goals have changed, you can remigrate previously migrated virtual machines:

  1. Delete the target virtual machines corresponding to the source virtual machines that you are remigrating. Otherwise, the remigration will fail because a target machine with the same name already exists.
  2. Delete the disks belonging to these virtual machines, which were created in the target datastore during the earlier migration, to free up space.

  3. Create a CSV file with the names and, optionally, the providers, of the source virtual machines.

    Note

    The virtual machines cannot be discovered automatically by the migration plan because they are marked in the CloudForms VMDB as migrated.

  4. Create and run a new migration plan, using the CSV file to import the virtual machines.

5.2.3. Log Files

If a migration plan does not complete successfully, you can check the logs for errors:

  • CloudForms migration log: /var/www/miq/vmdb/log/automation.log
  • Conversion host logs: /var/log/vdsm/import/

  • Virtual machine migration log: Click Compute → Migrate, click the migration plan to go to the details page, and click Download Log.

    Migrated Virtual Machine Logs

    Migrated VM details

5.2.4. Common Issues and Mistakes

Infrastructure mapping is missing datastores or clusters
If you create an infrastructure mapping and subsequently add or remove providers or provider objects, the infrastructure mapping displays Datastores missing or Clusters missing error messages because the object IDs of the providers and their objects have changed. You must delete the infrastructure mapping and re-create it.
Infrastructure mapping is missing networks

If the infrastructure mapping displays a Networks missing error message, you must authenticate the RHV conversion hosts and create a new infrastructure mapping.

Mapping missing network

Incorrect attributes in the virtual machine CSV import file
Create a new migration plan, import the correct CSV file, and run the migration plan.
Migration fails immediately
If a migration fails immediately, before the progress bar is displayed, this is often caused by a configuration error in the environment. Check the automation.log file on the CloudForms appliance.
Migration fails at virtual machine conversion
If a migration fails when the virtual machines are being converted (the progress bar updates), click the migration plan to go to the details page, and download the conversion log for the the virtual machine(s) that failed to migrate.
SSH transformation fails

If you are using SSSD with single sign-on for RHV, SSH fails for the vdsm account.

Reinstall ipa-client without configuring the OpenSSH client: 

# ipa-client-install --uninstall
# ipa-client-install --no-ssh

Changing the configuration file is not recommended because it is restored during upgrades. See https://bugzilla.redhat.com/show_bug.cgi?id=1544379 for details.