Error handling

Migrate to Containers can detect two types of errors during a migration: retryable and terminal. When Migrate to Containers detects an error, the action it takes depends on the type of error detected:

  • Retryable error: Migrate to Containers attempts the operation again. When detected, the status of the operation is set to Retrying.

  • Terminal error: Migrate to Containers halts the operation because this type of error typically requires manual intervention to resolve. When detected, the status of the operation is set to Error.

Viewing the status of an operation

Use the migctl tool or the Google Cloud console to view the progress of a migration. In the Google Cloud console, use the Status column of the migration to check the current status of the migration.

You can also use the following migctl command:

migctl migration status my-migration

The output is in the form:

NAME            CURRENT-OPERATION       PROGRESS        STEP            STATUS   AGE
my-migration    GenerateArtifacts       [1/1]           ExtractImage    Retrying 12m2s

With migctl, you can also get a verbose status output. At the bottom of the verbose output are a list of events and additional error information. For example, the following command specific the -v option to get the verbose status of the migration:

migctl migration status my-migration -v

The output contains the events and an error message to help you diagnose the error:

  Type     Reason             Age                     From                                           Message
  ----     ------             ----                    ----                                           -------
  Warning  GetInstanceFailed  2m39s (x91 over 5h32m)  SourceSnapshot sourcesnapshot-58a2405a-603ba2  Failed quering VM my-vm, with error: googleapi: got HTTP response code 404 with body:

In this example, the message indicates that the VM named my-vm cannot be found.

Retryable errors

A retryable error is a type of error that might be resolved by another attempt at the operation or by user intervention. If the operation succeeds on the retry, then processing continues.

For example, before you create a migration for a Compute Engine VM, you must first shut down the VM. If the VM is not shut down and you try to execute the migration, Migrate to Containers detects the error and retries the migration. Migrate to Containers continues to retry the operation until you either shut down the VM or cancel the migration.

Terminal errors

A terminal error is an error that cannot be resolved by retrying the operation. Typically a terminal error can only be resolved by user interaction.

How you handle a terminal error depends on the error and where in the migration process the error occurred:

  • For a terminal error when creating a migration, you must delete the migration, fix the error, and then recreate the migration.

  • For a terminal error when generating migration artifacts in the executing a migration operation, you can resolve the error manually and then retry the operation.

For example, you attempt to migrate a Windows VM without IIS being installed on the VM. This scenario causes a terminal error because Migrate to Containers requires Windows VMs to have Microsoft IIS 7 or higher installed. You must resolve this issue on the VM before you can proceed with migration.

Along with displaying a status of Error, terminal errors can display additional information specific to the error which you can use to diagnose the error.