Chapter 8. Migrating from OpenShift Virtualization

Procedure

1. In the Red Hat OpenShift web console, click Migration for Virtualization > Migration plans.

   The Plans list displays the source and target providers, the number of virtual machines (VMs) being migrated, the status, the date that the migration started, and the description of each plan.

2. Click Start beside a migration plan to start the migration.

3. Click Start in the confirmation window that opens.

   The plan’s Status changes to Running, and the migration’s progress is displayed.

   Warning

   Do not take a snapshot of a VM after you start a migration. Taking a snapshot after a migration starts might cause the migration to fail.

4. Optional: Click the links in the migration’s Status to see its overall status and the status of each VM:

   • The link on the left indicates whether the migration failed, succeeded, or is ongoing. It also reports the number of VMs whose migration succeeded, failed, or was canceled.

   • The link on the right opens the Virtual machines tab of the Plan details page. For each VM, the tab displays the following data:

     • The name of the VM
     • The start and end times of the migration
     • The amount of data copied
     • A progress pipeline for the VM’s migration

5. To view your migration’s logs, either as it is running or after it is completed:

   1. Click the Virtual machines tab.
   2. Click the arrow (>) before the name of the virtual machine whose migration progress you want to check.

   3. In the Pods section, in the Pod links column, click the Logs link.

      The Logs tab opens.

      Note

      Logs might not be available for the following common reasons:

      • The migration is from OpenShift Virtualization to OpenShift Virtualization. In this case, the virt-v2v utility is not involved, so no pod is required.
      • No pod was created.
      • The pod was deleted.
      • The migration failed before running the pod.
   4. To see the raw logs, click the Raw link.
   5. To download the logs, click the Download link.

Procedure

1. Create a Secret manifest for the source provider credentials:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret>
     namespace: <namespace>
     ownerReferences:
       - apiVersion: forklift.konveyor.io/v1beta1
         kind: Provider
         name: <provider_name>
         uid: <provider_uid>
     labels:
       createdForProviderType: openshift
       createdForResourceType: providers
   type: Opaque
   stringData:
     token: <token>
     password: <password>
     insecureSkipVerify: <"true"/"false">
     cacert: |
       <ca_certificate>
     url: <api_end_point>
   EOF

   where:

   <namespace>

   Specifies the namespace for the resource. Use openshift-mtv for the MTV namespace, or specify a custom namespace if you have configured providers in a different project.

   ownerReferences

   Is an optional section in which you can specify a provider’s name and uid.

   <token>

   Specifies a token for a service account with cluster-admin privileges. If both token and url are left blank, the local OpenShift cluster is used.

   <password>

   Specifies the user password.

   <"true"/"false">

   Specifies "true" to skip certificate verification, and specifies "false" to verify the certificate. Defaults to "false" if not specified. Skipping certificate verification proceeds with an insecure migration and then the certificate is not required. Insecure migration means that the transferred data is sent over an insecure connection and potentially sensitive data could be exposed.

   cacert

   Specifies the CA cert object. When this field is not set and skip certificate verification is disabled, MTV attempts to use the system CA.

   <api_end_point>

   Specifies the URL of the endpoint of the API server.

2. Create a Provider manifest for the source provider:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Provider
   metadata:
     name: <source_provider>
     namespace: <namespace>
   spec:
     type: openshift
     url: <api_end_point>
     secret:
       name: <secret>
       namespace: <namespace>
   EOF

   where:

   <namespace>

   Specifies the namespace for the resource. Use openshift-mtv for the MTV namespace, or specify a custom namespace if you have configured providers in a different project.

   <api_end_point>

   Specifies the URL of the endpoint of the API server.

   <secret>

   Specifies the name of the provider Secret CR.

3. Create a NetworkMap manifest to map the source and destination networks:

   $  cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: NetworkMap
   metadata:
     name: <network_map>
     namespace: <namespace>
   spec:
     map:
       - destination:
           name: <network_name>
           type: pod
         source:
           name: <network_name>
           type: pod
       - destination:
           name: <network_attachment_definition>
           namespace: <network_attachment_definition_namespace>
           type: multus
         source:
           name: <network_attachment_definition>
           namespace: <network_attachment_definition_namespace>
           type: multus
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   where:

   <namespace>

   Specifies the namespace for the resource. Use openshift-mtv for the MTV namespace, or specify a custom namespace if you have configured providers in a different project.

   type

   Specifies the network type. Allowed values are pod, ignored, and multus.

   <network_attachment_definition>

   Specifies the network name. When the type is multus, use the OpenShift Virtualization (NAD) name.

   <network_attachment_definition_namespace>

   Specifies the namespace of the OpenShift Virtualization NAD. Required only when the type is multus.

4. Create a StorageMap manifest to map source and destination storage:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: StorageMap
   metadata:
     name: <storage_map>
     namespace: <namespace>
   spec:
     map:
       - destination:
           storageClass: <storage_class>
           accessMode: <access_mode>
         source:
           name: <storage_class>
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   where:

   <namespace>

   Specifies the namespace for the resource. Use openshift-mtv for the MTV namespace, or specify a custom namespace if you have configured providers in a different project.

   <access_mode>

   Specifies the access mode. Allowed values are ReadWriteOnce and ReadWriteMany.

5. Optional: Create a Hook manifest to run custom code on a VM during the phase specified in the Plan CR:

   $  cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Hook
   metadata:
     name: <hook>
     namespace: <namespace>
   spec:
     image: registry.redhat.io/rhmtc/openshift-migration-hook-runner-rhel8
     serviceAccount:<service account>
     playbook: |
       LS0tCi0gbm...
   EOF

   where:

   <namespace>

   Specifies the namespace for the resource. Use openshift-mtv for the MTV namespace, or specify a custom namespace if you have configured providers in a different project.

   <service account>

   Specifies the Red Hat OpenShift service account. This is an optional field. Use the serviceAccount parameter to modify any cluster resources.

   playbook

   Specifies the Base64-encoded Ansible Playbook. If you specify a playbook, the image must include an ansible-runner.

   Note

   You can use the default hook-runner image or specify a custom image. If you specify a custom image, you do not have to specify a playbook.

6. Enter the following command to create the network attachment definition (NAD) of the transfer network used for MTV migrations.

   You use this definition to configure an IP address for the interface, either from the Dynamic Host Configuration Protocol (DHCP) or statically.

   Configuring the IP address enables the interface to reach the configured gateway.

   $ oc edit NetworkAttachmentDefinitions <name_of_the_NAD_to_edit>
   apiVersion: k8s.cni.cncf.io/v1
   kind: NetworkAttachmentDefinition
   metadata:
     name: <name_of_transfer_network>
     namespace: <namespace>
     annotations:
       forklift.konveyor.io/route: <IP_address>

7. Create a Plan manifest for the migration:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Plan
   metadata:
     name: <plan>
     namespace: <namespace>
   spec:
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
     map:
       network:
         name: <network_map>
         namespace: <namespace>
       storage:
         name: <storage_map>
         namespace: <namespace>
     targetNamespace: <target_namespace>
     pvcNameTemplate: <pvc_name_template>
     vms:
       - name: <source_vm>
         namespace: <namespace>
         pvcNameTemplate: <pvc_name_template_for_this_vm>
         hooks:
           - hook:
               namespace: <namespace>
               name: <hook>
             step: <step>
   EOF

   where:

   <plan>

   Specifies the name of the Plan CR.

   <namespace>

   Specifies the namespace for the resource. Use openshift-mtv for the MTV namespace, or specify a custom namespace if you have configured providers in a different project.

   map

   Specifies the network map and storage map used by the plan.

   <source_provider>

   Specifies the name of the source Provider CR.

   <destination_provider>

   Specifies the name of the destination Provider CR.

   <network_map>

   Specifies the name of the NetworkMap CR.

   <storage_map>

   Specifies the name of the StorageMap CR.

   <target_namespace>

   Specifies the target namespace in the destination cluster.

   <pvc_name_template>

   Specifies a template for the persistent volume claim (PVC) name for all VMs in the plan. This is an optional field. For a list of available variables, template functions, and examples, see PVC name template variables for OpenShift Virtualization-to-OpenShift Virtualization migrations.

   <source_vm>

   Specifies the name of the source VM to migrate.

   <pvc_name_template_for_this_vm>

   Specifies a template for the PVC name for this specific VM, overriding the plan-level template. This is an optional field.

   hooks

   Specifies up to two hooks for a VM. Each hook must run during a separate migration step. This is an optional field.

   <hook>

   Specifies the name of the Hook CR.

   <step>

   Specifies the type of hook. Allowed values are PreHook, before the migration plan starts, or PostHook, after the migration is complete.

8. Create a Migration manifest to run the Plan CR:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Migration
   metadata:
     name: <name_of_migration_cr>
     namespace: <namespace>
   spec:
     plan:
       name: <name_of_plan_cr>
       namespace: <namespace>
     cutover: <optional_cutover_time>
   EOF

   Note

   If you specify a cutover time, use the ISO 8601 format with the UTC time offset, for example, 2024-04-04T01:23:45.678+09:00.

Procedure

1. Create a Secret manifest for the source provider credentials:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret>
     namespace: <namespace>
     ownerReferences:
       - apiVersion: forklift.konveyor.io/v1beta1
         kind: Provider
         name: <provider_name>
         uid: <provider_uid>
     labels:
       createdForProviderType: openshift
       createdForResourceType: providers
   type: Opaque
   stringData:
     token: <token>
     password: <password>
     insecureSkipVerify: <"true"/"false">
     cacert: |
       <ca_certificate>
     url: <api_end_point>
   EOF

   where:

   ownerReferences

   Is an optional section in which you can specify a provider’s name and uid.

   <token>

   Specifies a token for a service account with cluster-admin privileges. If both token and url are left blank, the local OpenShift cluster is used.

   <password>

   Specifies the user password.

   <"true"/"false">

   Specifies "true" to skip certificate verification, and specifies "false" to verify the certificate. Defaults to "false" if not specified. Skipping certificate verification proceeds with an insecure migration and then the certificate is not required. Insecure migration means that the transferred data is sent over an insecure connection and potentially sensitive data could be exposed.

   cacert

   Specifies the CA cert object. When this field is not set and skip certificate verification is disabled, MTV attempts to use the system CA.

   <api_end_point>

   Specifies the URL of the endpoint of the API server.

2. Create a Provider manifest for the source provider:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Provider
   metadata:
     name: <source_provider>
     namespace: <namespace>
   spec:
     type: openshift
     url: <api_end_point>
     secret:
       name: <secret>
       namespace: <namespace>
   EOF

   where:

   <api_end_point>

   Specifies the URL of the endpoint of the API server.

   <secret>

   Specifies the name of the provider Secret CR.

3. Create a NetworkMap manifest to map the source and destination networks:

   $  cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: NetworkMap
   metadata:
     name: <network_map>
     namespace: <namespace>
   spec:
     map:
       - destination:
           name: <network_name>
           type: pod
         source:
           name: <network_name>
           type: pod
       - destination:
           name: <network_attachment_definition>
           namespace: <network_attachment_definition_namespace>
           type: multus
         source:
           name: <network_attachment_definition>
           namespace: <network_attachment_definition_namespace>
           type: multus
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   where:

   type

   Specifies the network type. Allowed values are pod, ignored, and multus.

   <network_attachment_definition>

   Specifies the network name. When the type is multus, use the name of the OpenShift Virtualization network attachment (NAD) definition.

   <network_attachment_definition_namespace>

   Specifies the namespace of the OpenShift Virtualization NAD. Required only when the type is multus.

4. Create a StorageMap manifest to map source and destination storage:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: StorageMap
   metadata:
     name: <storage_map>
     namespace: <namespace>
   spec:
     map:
       - destination:
           storageClass: <storage_class>
           accessMode: <access_mode>
         source:
           name: <storage_class>
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   where:

   <access_mode>

   Specifies the access mode. Allowed values are ReadWriteOnce and ReadWriteMany.

5. Optional: Create a Hook manifest to run custom code on a VM during the phase specified in the Plan CR:

   $  cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Hook
   metadata:
     name: <hook>
     namespace: <namespace>
   spec:
     image: registry.redhat.io/rhmtc/openshift-migration-hook-runner-rhel8
     serviceAccount: <service_account>
     playbook: |
       LS0tCi0gbm...
   EOF

   where:

   serviceAccount

   Specifies the Red Hat OpenShift service account. This is an optional label. Use the serviceAccount parameter to modify any cluster resources.

   playbook

   Specifies the Base64-encoded Ansible Playbook. If you specify a playbook, the image must include an ansible-runner.

   Note

   You can use the default hook-runner image or specify a custom image. If you specify a custom image, you do not have to specify a playbook.

6. Create a Plan manifest for the migration:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Plan
   metadata:
     name: <plan>
     namespace: <namespace>
   spec:
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
     map:
       network:
         name: <network_map>
         namespace: <namespace>
       storage:
         name: <storage_map>
         namespace: <namespace>
     type: live
     targetNamespace: <target_namespace>
     pvcNameTemplate: <pvc_name_template>
     vms:
       - name: <source_vm>
         namespace: <namespace>
         pvcNameTemplate: <pvc_name_template_for_this_vm>
         hooks:
           - hook:
               namespace: <namespace>
               name: <hook>
             step: <step>
   EOF

   where:

   <plan>

   Specifies the name of the Plan CR.

   <namespace>

   Specifies the namespace for the resource. Use openshift-mtv for the MTV namespace, or specify a custom namespace if you have configured providers in a different project.

   <source_provider>

   Specifies the name of the source Provider CR.

   <destination_provider>

   Specifies the name of the destination Provider CR.

   <network_map>

   Specifies the name of the NetworkMap CR.

   <storage_map>

   Specifies the name of the StorageMap CR.

   type

   Specifies the type of migration. Must be set to live.

   <target_namespace>

   Specifies the target namespace in the destination cluster.

   <pvc_name_template>

   Specifies a template for the persistent volume claim (PVC) name for all VMs in the plan. This is an optional field. For a list of available variables, template functions, and examples, see PVC name template variables for OpenShift Virtualization-to-OpenShift Virtualization migrations.

   <source_vm>

   Specifies the name of the source VM to migrate.

   <pvc_name_template_for_this_vm>

   Specifies a template for the PVC name for this specific VM, overriding the plan-level template. This is an optional field.

   <hook>

   Specifies the name of the Hook CR.

   <step>

   Specifies the hook step. Allowed values are PreHook, before the migration plan starts, or PostHook, after the migration is complete.

7. Create a Migration manifest to run the Plan CR:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Migration
   metadata:
     name: <name_of_migration_cr>
     namespace: <namespace>
   spec:
     plan:
       name: <name_of_plan_cr>
       namespace: <namespace>
   EOF

   Note

   The cutover field is irrelevant for live migrations, so it is not included in the Migration CR of this procedure.