Chapter 11. Migrating virtual machines from the command line

11.1. Permissions needed by non-administrators to work with migration plan components
Copier lien

If you are an administrator, you can work with all components of migration plans (for example, providers, network mappings, and migration plans).

By default, non-administrators have limited ability to work with migration plans and their components. As an administrator, you can modify their roles to allow them full access to all components, or you can give them limited permissions.

For example, administrators can assign non-administrators one or more of the following cluster roles for migration plans:

Expand

Table 11.1. Example migration plan roles and their privileges
Role	Description
`plans.forklift.konveyor.io-v1beta1-view`	Can view migration plans but not to create, delete or modify them
`plans.forklift.konveyor.io-v1beta1-edit`	Can create, delete or modify (all parts of `edit` permissions) individual migration plans
`plans.forklift.konveyor.io-v1beta1-admin`	All `edit` privileges and the ability to delete the entire collection of migration plans

Note that pre-defined cluster roles include a resource (for example, plans), an API group (for example, forklift.konveyor.io-v1beta1) and an action (for example, view, edit).

As a more comprehensive example, you can grant non-administrators the following set of permissions per namespace:

Create and modify storage maps, network maps, and migration plans for the namespaces they have access to
Attach providers created by administrators to storage maps, network maps, and migration plans
Not be able to create providers or to change system settings

Expand

Table 11.2. Example permissions required for non-adminstrators to work with migration plan components but not create providers
Actions	API group	Resource
`get`, `list`, `watch`, `create`, `update`, `patch`, `delete`	`forklift.konveyor.io`	`plans`
`get`, `list`, `watch`, `create`, `update`, `patch`, `delete`	`forklift.konveyor.io`	`migrations`
`get`, `list`, `watch`, `create`, `update`, `patch`, `delete`	`forklift.konveyor.io`	`hooks`
`get`, `list`, `watch`	`forklift.konveyor.io`	`providers`
`get`, `list`, `watch`, `create`, `update`, `patch`, `delete`	`forklift.konveyor.io`	`networkmaps`
`get`, `list`, `watch`, `create`, `update`, `patch`, `delete`	`forklift.konveyor.io`	`storagemaps`
`get`, `list`, `watch`	`forklift.konveyor.io`	`forkliftcontrollers`
`create`, `patch`, `delete`	Empty string	`secrets`

Note

Non-administrators need to have the create permissions that are part of edit roles for network maps and for storage maps to create migration plans, even when using a template for a network map or a storage map.

11.2. Migrating virtual machines
Copier lien

You migrate virtual machines (VMs) using the command-line interface (CLI) by creating MTV custom resources (CRs). The CRs and the migration procedure vary by source provider.

Important

You must specify a name for cluster-scoped CRs.

You must specify both a name and a namespace for namespace-scoped CRs.

To migrate to or from an OpenShift cluster that is different from the one the migration plan is defined on, you must have an OpenShift Virtualization service account token with cluster-admin privileges.

11.3. Migrating from a VMware vSphere source provider
Copier lien

You can migrate from a VMware vSphere source provider by using the command-line interface (CLI).

Procedure

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: vsphere
    createdForResourceType: providers
type: Opaque
stringData:
  user: <user> 
  password: <password> 
  insecureSkipVerify: <"true"/"false"> 
  cacert: | 
    <ca_certificate>
  url: <api_end_point> 
EOF

$ cat << EOF | oc apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: <secret>
  namespace: <namespace>
  ownerReferences:

1


    - apiVersion: forklift.konveyor.io/v1beta1
      kind: Provider
      name: <provider_name>
      uid: <provider_uid>
  labels:
    createdForProviderType: vsphere
    createdForResourceType: providers
type: Opaque
stringData:
  user: <user>

2


  password: <password>

3


  insecureSkipVerify: <"true"/"false">

4


  cacert: |

5


    <ca_certificate>
  url: <api_end_point>

6

EOF

Copy to Clipboard

Toggle word wrap

1: The ownerReferences section is optional.
2: Specify the vCenter user or the ESX/ESXi user.
3: Specify the password of the vCenter user or the ESX/ESXi user.
4: Specify "true" to skip certificate verification, and specify "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.
5: When this field is not set and skip certificate verification is disabled, MTV attempts to use the system CA.
6: Specify the API endpoint URL of the vCenter or the ESX/ESXi, for example, https://<vCenter_host>/sdk.

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: vsphere
  url: <api_end_point> 
  settings:
    vddkInitImage: <VDDK_image> 
    sdkEndpoint: vcenter 
  secret:
    name: <secret> 
    namespace: <namespace>
EOF

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

1


  settings:
    vddkInitImage: <VDDK_image>

2


    sdkEndpoint: vcenter

3


  secret:
    name: <secret>

4


    namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Specify the URL of the API endpoint, for example, https://<vCenter_host>/sdk.
2: Optional, but it is strongly recommended to create a VDDK image to accelerate migrations. Follow OpenShift documentation to specify the VDDK image you created.
3: Options: vcenter or esxi.
4: Specify the name of the provider Secret CR.

Create a Host manifest:

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Host
metadata:
  name: <vmware_host>
  namespace: <namespace>
spec:
  provider:
    namespace: <namespace>
    name: <source_provider> 
  id: <source_host_mor> 
  ipAddress: <source_network_ip> 
EOF

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Host
metadata:
  name: <vmware_host>
  namespace: <namespace>
spec:
  provider:
    namespace: <namespace>
    name: <source_provider>

1


  id: <source_host_mor>

2


  ipAddress: <source_network_ip>

3

EOF

Copy to Clipboard

Toggle word wrap

1: Specify the name of the VMware vSphere Provider CR.
2: Specify the Managed Object Reference (moRef) of the VMware vSphere host. To retrieve the moRef, see Retrieving a VMware vSphere moRef.
3: Specify the IP address of the VMware vSphere migration network.

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: 
        id: <source_network_id>
        name: <source_network_name>
    - destination:
        name: <network_attachment_definition> 
        namespace: <network_attachment_definition_namespace> 
        type: multus
      source:
        id: <source_network_id>
        name: <source_network_name>
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

$  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

1


      source:

2


        id: <source_network_id>
        name: <source_network_name>
    - destination:
        name: <network_attachment_definition>

3


        namespace: <network_attachment_definition_namespace>

4


        type: multus
      source:
        id: <source_network_id>
        name: <source_network_name>
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Allowed values are pod and multus.
2: You can use either the id or the name parameter to specify the source network. For id, specify the VMware vSphere network Managed Object Reference (moRef). To retrieve the moRef, see Retrieving a VMware vSphere moRef.
3: Specify a network attachment definition for each additional OpenShift Virtualization network.
4: Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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:
        id: <source_datastore> 
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

$ 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>

1


      source:
        id: <source_datastore>

2


  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Allowed values are ReadWriteOnce and ReadWriteMany.
2: Specify the VMware vSphere datastore moRef. For example, f2737930-b567-451a-9ceb-2887f6207009. To retrieve the moRef, see Retrieving a VMware vSphere moRef.

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: quay.io/konveyor/hook-runner
  serviceAccount:<service account> 
  playbook: |
    LS0tCi0gbm... 
EOF

$  cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Hook
metadata:
  name: <hook>
  namespace: <namespace>
spec:
  image: quay.io/konveyor/hook-runner
  serviceAccount:<service account>

1


  playbook: |
    LS0tCi0gbm...

2

EOF

Copy to Clipboard

Toggle word wrap

1: (Optional) Red Hat OpenShift service account. The serviceAccount must be provided if you want to manipulate any resources of the cluster.
2: 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.

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:
  warm: false 
  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>
  preserveStaticIPs: 
  targetNamespace: <target_namespace>
  vms: 
    - id: <source_vm> 
    - name: <source_vm>
      hooks: 
        - hook:
            namespace: <namespace>
            name: <hook> 
          step: <step> 
EOF
```
```
$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Plan
metadata:
  name: <plan> 
```
1
```
  namespace: <namespace>
spec:
  warm: false 
```
2
```
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
  map: 
```
3
```
    network: 
```
4
```
      name: <network_map> 
```
5
```
      namespace: <namespace>
    storage: 
```
6
```
      name: <storage_map> 
```
7
```
      namespace: <namespace>
  preserveStaticIPs: 
```
8
```
  targetNamespace: <target_namespace>
  vms: 
```
9
```
    - id: <source_vm> 
```
10
```
    - name: <source_vm>
      hooks: 
```
11
```
        - hook:
            namespace: <namespace>
            name: <hook> 
```
12
```
          step: <step> 
```
13
```
EOF
```
Copy to Clipboard Toggle word wrap
1
Specify the name of the Plan CR.
2
Specify whether the migration is warm - true - or cold - false. If you specify a warm migration without specifying a value for the cutover parameter in the Migration manifest, only the precopy stage will run.
3
Specify only one network map and one storage map per plan.
4
Specify a network mapping even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.
5
Specify the name of the NetworkMap CR.
6
Specify a storage mapping even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.
7
Specify the name of the StorageMap CR.
8
By default, virtual network interface controllers (vNICs) change during the migration process. As a result, vNICs that are configured with a static IP linked to the interface name in the guest VM lose their IP. To avoid this, set preserveStaticIPs to true. MTV issues a warning message about any VMs for which vNIC properties are missing. To retrieve any missing vNIC properties, run those VMs in vSphere in order for the vNIC properties to be reported to MTV.
9
You can use either the id or the name parameter to specify the source VMs.
10
Specify the VMware vSphere VM moRef. To retrieve the moRef, see Retrieving a VMware vSphere moRef.
11
Optional: You can specify up to two hooks for a VM. Each hook must run during a separate migration step.
12
Specify the name of the Hook CR.
13
Allowed values are PreHook, before the migration plan starts, or PostHook, after the migration is complete.
Important
When you migrate a VMware 7 VM to an OpenShift 4.13+ platform that uses CentOS 7.9, the name of the network interfaces changes and the static IP configuration for the VM no longer works.

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

$ 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

Copy to Clipboard

Toggle word wrap

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.

Important

There is an issue with the forklift-controller consistently failing to reconcile a migration plan, and subsequently returning an HTTP 500 error. This issue is caused when you specify the user permissions only on the virtual machine (VM).

In MTV, you need to add permissions at the datacenter level, which includes storage, networks, switches, and so on, which are used by the VM. You must then propagate the permissions to the child elements.

If you do not want to add this level of permissions, you must manually add the permissions to each object on the VM host required.

11.3.1. Retrieving a VMware vSphere moRef
Copier lien

When you migrate VMs with a VMware vSphere source provider using Migration Toolkit for Virtualization (MTV) from the command line, you need to know the managed object reference (moRef) of certain entities in vSphere, such as datastores, networks, and VMs.

You can retrieve the moRef of one or more vSphere entities from the Inventory service. You can then use each moRef as a reference for retrieving the moRef of another entity.

Procedure

Retrieve the routes for the project:
```
oc get route -n openshift-mtv
```
```
oc get route -n openshift-mtv
```
Copy to Clipboard Toggle word wrap

Retrieve the Inventory service route:

oc get route <inventory_service> -n openshift-mtv

$ oc get route <inventory_service> -n openshift-mtv

Copy to Clipboard

Toggle word wrap

Retrieve the access token:
```
TOKEN=$(oc whoami -t)
```
```
$ TOKEN=$(oc whoami -t)
```
Copy to Clipboard Toggle word wrap

Retrieve the moRef of a VMware vSphere provider:

curl -H "Authorization: Bearer $TOKEN"  https://<inventory_service_route>/providers/vsphere -k

$ curl -H "Authorization: Bearer $TOKEN"  https://<inventory_service_route>/providers/vsphere -k

Copy to Clipboard

Toggle word wrap

Retrieve the datastores of a VMware vSphere source provider:

curl -H "Authorization: Bearer $TOKEN"  https://<inventory_service_route>/providers/vsphere/<provider id>/datastores/ -k

$ curl -H "Authorization: Bearer $TOKEN"  https://<inventory_service_route>/providers/vsphere/<provider id>/datastores/ -k

Copy to Clipboard

Toggle word wrap

Example output

[
  {
    "id": "datastore-11",
    "parent": {
      "kind": "Folder",
      "id": "group-s5"
    },
    "path": "/Datacenter/datastore/v2v_general_porpuse_ISCSI_DC",
    "revision": 46,
    "name": "v2v_general_porpuse_ISCSI_DC",
    "selfLink": "providers/vsphere/01278af6-e1e4-4799-b01b-d5ccc8dd0201/datastores/datastore-11"
  },
  {
    "id": "datastore-730",
    "parent": {
      "kind": "Folder",
      "id": "group-s5"
    },
    "path": "/Datacenter/datastore/f01-h27-640-SSD_2",
    "revision": 46,
    "name": "f01-h27-640-SSD_2",
    "selfLink": "providers/vsphere/01278af6-e1e4-4799-b01b-d5ccc8dd0201/datastores/datastore-730"
  },
 ...

[
  {
    "id": "datastore-11",
    "parent": {
      "kind": "Folder",
      "id": "group-s5"
    },
    "path": "/Datacenter/datastore/v2v_general_porpuse_ISCSI_DC",
    "revision": 46,
    "name": "v2v_general_porpuse_ISCSI_DC",
    "selfLink": "providers/vsphere/01278af6-e1e4-4799-b01b-d5ccc8dd0201/datastores/datastore-11"
  },
  {
    "id": "datastore-730",
    "parent": {
      "kind": "Folder",
      "id": "group-s5"
    },
    "path": "/Datacenter/datastore/f01-h27-640-SSD_2",
    "revision": 46,
    "name": "f01-h27-640-SSD_2",
    "selfLink": "providers/vsphere/01278af6-e1e4-4799-b01b-d5ccc8dd0201/datastores/datastore-730"
  },
 ...

Copy to Clipboard

Toggle word wrap

In this example, the moRef of the datastore v2v_general_porpuse_ISCSI_DC is datastore-11 and the moRef of the datastore f01-h27-640-SSD_2 is datastore-730.

11.3.2. Canceling a migration from the command-line interface
Copier lien

You can use the command-line interface (CLI) to cancel either an entire migration or the migration of specific virtual machines (VMs) while a migration is in progress.

Canceling an entire migration

Delete the Migration CR:
```
oc delete migration <migration> -n <namespace>
```
```
$ oc delete migration <migration> -n <namespace> 
```
1
Copy to Clipboard Toggle word wrap
1
Specify the name of the Migration CR.

Canceling the migration of specific VMs

Add the specific VMs to the spec.cancel block of the Migration manifest:

Example YAML for canceling the migrations of two VMs

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102 
  - id: vm-203
  - name: rhel8-vm
EOF

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102

1


  - id: vm-203
  - name: rhel8-vm
EOF

Copy to Clipboard

Toggle word wrap

1: You can specify a VM by using the id key or the name key.

The value of the id key is the managed object reference, for a VMware VM, or the VM UUID, for a RHV VM.

Retrieve the Migration CR to monitor the progress of the remaining VMs:
```
oc get migration/<migration> -n <namespace> -o yaml
```
```
$ oc get migration/<migration> -n <namespace> -o yaml
```
Copy to Clipboard Toggle word wrap

11.4. Migrating from a Red Hat Virtualization source provider
Copier lien

You can migrate from a Red Hat Virtualization (RHV) source provider by using the command-line interface (CLI).

Prerequisites

If you are migrating a virtual machine with a direct LUN disk, ensure that the nodes in the OpenShift Virtualization destination cluster that the VM is expected to run on can access the backend storage.

Note

Unlike disk images that are copied from a source provider to a target provider, LUNs are detached, but not removed, from virtual machines in the source provider and then attached to the virtual machines (VMs) that are created in the target provider.
LUNs are not removed from the source provider during the migration in case fallback to the source provider is required. However, before re-attaching the LUNs to VMs in the source provider, ensure that the LUNs are not used by VMs on the target environment at the same time, which might lead to data corruption.

Procedure

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: ovirt
    createdForResourceType: providers
type: Opaque
stringData:
  user: <user> 
  password: <password> 
  insecureSkipVerify: <"true"/"false"> 
  cacert: | 
    <ca_certificate>
  url: <api_end_point> 
EOF

$ cat << EOF | oc apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: <secret>
  namespace: <namespace>
  ownerReferences:

1


    - apiVersion: forklift.konveyor.io/v1beta1
      kind: Provider
      name: <provider_name>
      uid: <provider_uid>
  labels:
    createdForProviderType: ovirt
    createdForResourceType: providers
type: Opaque
stringData:
  user: <user>

2


  password: <password>

3


  insecureSkipVerify: <"true"/"false">

4


  cacert: |

5


    <ca_certificate>
  url: <api_end_point>

6

EOF

Copy to Clipboard

Toggle word wrap

1: The ownerReferences section is optional.
2: Specify the RHV Manager user.
3: Specify the user password.
4: Specify "true" to skip certificate verification, and specify "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.
5: Enter the Manager CA certificate, unless it was replaced by a third-party certificate, in which case, enter the Manager Apache CA certificate. You can retrieve the Manager CA certificate at https://<engine_host>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA.
6: Specify the API endpoint URL, for example, https://<engine_host>/ovirt-engine/api.

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: ovirt
  url: <api_end_point> 
  secret:
    name: <secret> 
    namespace: <namespace>
EOF

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

1


  secret:
    name: <secret>

2


    namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Specify the URL of the API endpoint, for example, https://<engine_host>/ovirt-engine/api.
2: Specify the name of provider Secret CR.

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: 
        id: <source_network_id>
        name: <source_network_name>
    - destination:
        name: <network_attachment_definition> 
        namespace: <network_attachment_definition_namespace> 
        type: multus
      source:
        id: <source_network_id>
        name: <source_network_name>
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

$  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

1


      source:

2


        id: <source_network_id>
        name: <source_network_name>
    - destination:
        name: <network_attachment_definition>

3


        namespace: <network_attachment_definition_namespace>

4


        type: multus
      source:
        id: <source_network_id>
        name: <source_network_name>
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Allowed values are pod and multus.
2: You can use either the id or the name parameter to specify the source network. For id, specify the RHV network Universal Unique ID (UUID).
3: Specify a network attachment definition for each additional OpenShift Virtualization network.
4: Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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:
        id: <source_storage_domain> 
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

$ 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>

1


      source:
        id: <source_storage_domain>

2


  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Allowed values are ReadWriteOnce and ReadWriteMany.
2: Specify the RHV storage domain UUID. For example, f2737930-b567-451a-9ceb-2887f6207009.

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: quay.io/konveyor/hook-runner
  serviceAccount:<service account> 
  playbook: |
    LS0tCi0gbm... 
EOF

$  cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Hook
metadata:
  name: <hook>
  namespace: <namespace>
spec:
  image: quay.io/konveyor/hook-runner
  serviceAccount:<service account>

1


  playbook: |
    LS0tCi0gbm...

2

EOF

Copy to Clipboard

Toggle word wrap

1: (Optional) Red Hat OpenShift service account. The serviceAccount must be provided if you want to manipulate any resources of the cluster.
2: 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.

Create a Plan manifest for the migration:
```
$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Plan
metadata:
  name: <plan> 
  namespace: <namespace>
  preserveClusterCpuModel: true 
spec:
  warm: false 
  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>
  vms: 
    - id: <source_vm> 
    - name: <source_vm>
      hooks: 
        - hook:
            namespace: <namespace>
            name: <hook> 
          step: <step> 
EOF
```
```
$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Plan
metadata:
  name: <plan> 
```
1
```
  namespace: <namespace>
  preserveClusterCpuModel: true 
```
2
```
spec:
  warm: false 
```
3
```
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
  map: 
```
4
```
    network: 
```
5
```
      name: <network_map> 
```
6
```
      namespace: <namespace>
    storage: 
```
7
```
      name: <storage_map> 
```
8
```
      namespace: <namespace>
  targetNamespace: <target_namespace>
  vms: 
```
9
```
    - id: <source_vm> 
```
10
```
    - name: <source_vm>
      hooks: 
```
11
```
        - hook:
            namespace: <namespace>
            name: <hook> 
```
12
```
          step: <step> 
```
13
```
EOF
```
Copy to Clipboard Toggle word wrap
1
Specify the name of the Plan CR.
2
See note below.
3
Specify whether the migration is warm or cold. If you specify a warm migration without specifying a value for the cutover parameter in the Migration manifest, only the precopy stage will run.
4
Specify only one network map and one storage map per plan.
5
Specify a network mapping even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.
6
Specify the name of the NetworkMap CR.
7
Specify a storage mapping even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.
8
Specify the name of the StorageMap CR.
9
You can use either the id or the name parameter to specify the source VMs.
10
Specify the RHV VM UUID.
11
Optional: You can specify up to two hooks for a VM. Each hook must run during a separate migration step.
12
Specify the name of the Hook CR.
13
Allowed values are PreHook, before the migration plan starts, or PostHook, after the migration is complete.
Note
- If the migrated machine is set with a custom CPU model, it will be set with that CPU model in the destination cluster, regardless of the setting of preserveClusterCpuModel.
- If the migrated machine is not set with a custom CPU model:
  If preserveClusterCpuModel is set to 'true`, MTV checks the CPU model of the VM when it runs in RHV, based on the cluster’s configuration, and then sets the migrated VM with that CPU model.
  If preserveClusterCpuModel is set to 'false`, MTV does not set a CPU type and the VM is set with the default CPU model of the destination cluster.

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

$ 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

Copy to Clipboard

Toggle word wrap

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.

11.4.1. Canceling a migration from the command-line interface
Copier lien

You can use the command-line interface (CLI) to cancel either an entire migration or the migration of specific virtual machines (VMs) while a migration is in progress.

Canceling an entire migration

Delete the Migration CR:
```
oc delete migration <migration> -n <namespace>
```
```
$ oc delete migration <migration> -n <namespace> 
```
1
Copy to Clipboard Toggle word wrap
1
Specify the name of the Migration CR.

Canceling the migration of specific VMs

Add the specific VMs to the spec.cancel block of the Migration manifest:

Example YAML for canceling the migrations of two VMs

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102 
  - id: vm-203
  - name: rhel8-vm
EOF

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102

1


  - id: vm-203
  - name: rhel8-vm
EOF

Copy to Clipboard

Toggle word wrap

1: You can specify a VM by using the id key or the name key.

The value of the id key is the managed object reference, for a VMware VM, or the VM UUID, for a RHV VM.

Retrieve the Migration CR to monitor the progress of the remaining VMs:
```
oc get migration/<migration> -n <namespace> -o yaml
```
```
$ oc get migration/<migration> -n <namespace> -o yaml
```
Copy to Clipboard Toggle word wrap

11.5. Migrating from an OpenStack source provider
Copier lien

You can migrate from an OpenStack source provider by using the command-line interface (CLI).

Procedure

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: openstack
    createdForResourceType: providers
type: Opaque
stringData:
  user: <user> 
  password: <password> 
  insecureSkipVerify: <"true"/"false"> 
  domainName: <domain_name>
  projectName: <project_name>
  regionName: <region_name>
  cacert: | 
    <ca_certificate>
  url: <api_end_point> 
EOF

$ cat << EOF | oc apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: <secret>
  namespace: <namespace>
  ownerReferences:

1


    - apiVersion: forklift.konveyor.io/v1beta1
      kind: Provider
      name: <provider_name>
      uid: <provider_uid>
  labels:
    createdForProviderType: openstack
    createdForResourceType: providers
type: Opaque
stringData:
  user: <user>

2


  password: <password>

3


  insecureSkipVerify: <"true"/"false">

4


  domainName: <domain_name>
  projectName: <project_name>
  regionName: <region_name>
  cacert: |

5


    <ca_certificate>
  url: <api_end_point>

6

EOF

Copy to Clipboard

Toggle word wrap

1: The ownerReferences section is optional.
2: Specify the OpenStack user.
3: Specify the user OpenStack password.
4: Specify "true" to skip certificate verification, and specify "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.
5: When this field is not set and skip certificate verification is disabled, MTV attempts to use the system CA.
6: Specify the API endpoint URL, for example, https://<identity_service>/v3.

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: openstack
  url: <api_end_point> 
  secret:
    name: <secret> 
    namespace: <namespace>
EOF

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

1


  secret:
    name: <secret>

2


    namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Specify the URL of the API endpoint.
2: Specify the name of provider Secret CR.

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:
        id: <source_network_id>
        name: <source_network_name>
    - destination:
        name: <network_attachment_definition> 
        namespace: <network_attachment_definition_namespace> 
        type: multus
      source:
        id: <source_network_id>
        name: <source_network_name>
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

$  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

1


      source:

2


        id: <source_network_id>
        name: <source_network_name>
    - destination:
        name: <network_attachment_definition>

3


        namespace: <network_attachment_definition_namespace>

4


        type: multus
      source:
        id: <source_network_id>
        name: <source_network_name>
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Allowed values are pod and multus.
2: You can use either the id or the name parameter to specify the source network. For id, specify the OpenStack network UUID.
3: Specify a network attachment definition for each additional OpenShift Virtualization network.
4: Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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:
        id: <source_volume_type> 
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

$ 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>

1


      source:
        id: <source_volume_type>

2


  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Allowed values are ReadWriteOnce and ReadWriteMany.
2: Specify the OpenStack volume_type UUID. For example, f2737930-b567-451a-9ceb-2887f6207009.

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: quay.io/konveyor/hook-runner
  serviceAccount:<service account> 
  playbook: |
    LS0tCi0gbm... 
EOF

$  cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Hook
metadata:
  name: <hook>
  namespace: <namespace>
spec:
  image: quay.io/konveyor/hook-runner
  serviceAccount:<service account>

1


  playbook: |
    LS0tCi0gbm...

2

EOF

Copy to Clipboard

Toggle word wrap

1: (Optional) Red Hat OpenShift service account. The serviceAccount must be provided if you want to manipulate any resources of the cluster.
2: 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.

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>
  vms: 
    - id: <source_vm> 
    - name: <source_vm>
      hooks: 
        - hook:
            namespace: <namespace>
            name: <hook> 
          step: <step> 
EOF

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Plan
metadata:
  name: <plan>

1


  namespace: <namespace>
spec:
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
  map:

2


    network:

3


      name: <network_map>

4


      namespace: <namespace>
    storage:

5


      name: <storage_map>

6


      namespace: <namespace>
  targetNamespace: <target_namespace>
  vms:

7


    - id: <source_vm>

8


    - name: <source_vm>
      hooks:

9


        - hook:
            namespace: <namespace>
            name: <hook>

10


          step: <step>

11

EOF

Copy to Clipboard

Toggle word wrap

1: Specify the name of the Plan CR.
2: Specify only one network map and one storage map per plan.
3: Specify a network mapping, even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.
4: Specify the name of the NetworkMap CR.
5: Specify a storage mapping, even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.
6: Specify the name of the StorageMap CR.
7: You can use either the id or the name parameter to specify the source VMs.
8: Specify the OpenStack VM UUID.
9: Optional: You can specify up to two hooks for a VM. Each hook must run during a separate migration step.
10: Specify the name of the Hook CR.
11: Allowed values are PreHook, before the migration plan starts, or PostHook, after the migration is complete.

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

$ 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

Copy to Clipboard

Toggle word wrap

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.

11.5.1. Canceling a migration from the command-line interface
Copier lien

You can use the command-line interface (CLI) to cancel either an entire migration or the migration of specific virtual machines (VMs) while a migration is in progress.

Canceling an entire migration

Delete the Migration CR:
```
oc delete migration <migration> -n <namespace>
```
```
$ oc delete migration <migration> -n <namespace> 
```
1
Copy to Clipboard Toggle word wrap
1
Specify the name of the Migration CR.

Canceling the migration of specific VMs

Add the specific VMs to the spec.cancel block of the Migration manifest:

Example YAML for canceling the migrations of two VMs

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102 
  - id: vm-203
  - name: rhel8-vm
EOF

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102

1


  - id: vm-203
  - name: rhel8-vm
EOF

Copy to Clipboard

Toggle word wrap

1: You can specify a VM by using the id key or the name key.

The value of the id key is the managed object reference, for a VMware VM, or the VM UUID, for a RHV VM.

Retrieve the Migration CR to monitor the progress of the remaining VMs:
```
oc get migration/<migration> -n <namespace> -o yaml
```
```
$ oc get migration/<migration> -n <namespace> -o yaml
```
Copy to Clipboard Toggle word wrap

11.6. Migrating from an Open Virtual Appliance (OVA) source provider
Copier lien

You can migrate from Open Virtual Appliance (OVA) files that were created by VMware vSphere as a source provider by using the command-line interface (CLI).

Procedure

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: ova
    createdForResourceType: providers
type: Opaque
stringData:
  url: <nfs_server:/nfs_path> 
EOF

$ cat << EOF | oc apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: <secret>
  namespace: <namespace>
  ownerReferences:

1


    - apiVersion: forklift.konveyor.io/v1beta1
      kind: Provider
      name: <provider_name>
      uid: <provider_uid>
  labels:
    createdForProviderType: ova
    createdForResourceType: providers
type: Opaque
stringData:
  url: <nfs_server:/nfs_path>

2

EOF

Copy to Clipboard

Toggle word wrap

1: The ownerReferences section is optional.
2: where: nfs_server is an IP or hostname of the server where the share was created and nfs_path is the path on the server where the OVA files are stored.

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: ova
  url:  <nfs_server:/nfs_path> 
  secret:
    name: <secret> 
    namespace: <namespace>
EOF

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

1


  secret:
    name: <secret>

2


    namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: where: nfs_server is an IP or hostname of the server where the share was created and nfs_path is the path on the server where the OVA files are stored.
2: Specify the name of provider Secret CR.

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:
        id: <source_network_id> 
    - destination:
        name: <network_attachment_definition> 
        namespace: <network_attachment_definition_namespace> 
        type: multus
      source:
        id: <source_network_id>
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

$  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

1


      source:
        id: <source_network_id>

2


    - destination:
        name: <network_attachment_definition>

3


        namespace: <network_attachment_definition_namespace>

4


        type: multus
      source:
        id: <source_network_id>
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Allowed values are pod and multus.
2: Specify the OVA network Universal Unique ID (UUID).
3: Specify a network attachment definition for each additional OpenShift Virtualization network.
4: Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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:  Dummy storage for source provider <provider_name> 
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

$ 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>

1


      source:
        name:  Dummy storage for source provider <provider_name>

2


  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Allowed values are ReadWriteOnce and ReadWriteMany.
2: For OVA, the StorageMap can map only a single storage, which all the disks from the OVA are associated with, to a storage class at the destination. For this reason, the storage is referred to in the UI as "Dummy storage for source provider <provider_name>". In the YAML, write the phrase as it appears above, without the quotation marks and replacing <provider_name> with the actual name of the provider.

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: quay.io/konveyor/hook-runner
  serviceAccount:<service account> 
  playbook: |
    LS0tCi0gbm... 
EOF

$  cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Hook
metadata:
  name: <hook>
  namespace: <namespace>
spec:
  image: quay.io/konveyor/hook-runner
  serviceAccount:<service account>

1


  playbook: |
    LS0tCi0gbm...

2

EOF

Copy to Clipboard

Toggle word wrap

1: (Optional) Red Hat OpenShift service account. The serviceAccount must be provided if you want to manipulate any resources of the cluster.
2: 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.

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>
  vms: 
    - id: <source_vm> 
    - name: <source_vm>
      hooks: 
        - hook:
            namespace: <namespace>
            name: <hook> 
          step: <step> 
EOF

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Plan
metadata:
  name: <plan>

1


  namespace: <namespace>
spec:
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
  map:

2


    network:

3


      name: <network_map>

4


      namespace: <namespace>
    storage:

5


      name: <storage_map>

6


      namespace: <namespace>
  targetNamespace: <target_namespace>
  vms:

7


    - id: <source_vm>

8


    - name: <source_vm>
      hooks:

9


        - hook:
            namespace: <namespace>
            name: <hook>

10


          step: <step>

11

EOF

Copy to Clipboard

Toggle word wrap

1: Specify the name of the Plan CR.
2: Specify only one network map and one storage map per plan.
3: Specify a network mapping, even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.
4: Specify the name of the NetworkMap CR.
5: Specify a storage mapping even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.
6: Specify the name of the StorageMap CR.
7: You can use either the id or the name parameter to specify the source VMs.
8: Specify the OVA VM UUID.
9: Optional: You can specify up to two hooks for a VM. Each hook must run during a separate migration step.
10: Specify the name of the Hook CR.
11: Allowed values are PreHook, before the migration plan starts, or PostHook, after the migration is complete.

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

$ 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

Copy to Clipboard

Toggle word wrap

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.

11.6.1. Canceling a migration from the command-line interface
Copier lien

You can use the command-line interface (CLI) to cancel either an entire migration or the migration of specific virtual machines (VMs) while a migration is in progress.

Canceling an entire migration

Delete the Migration CR:
```
oc delete migration <migration> -n <namespace>
```
```
$ oc delete migration <migration> -n <namespace> 
```
1
Copy to Clipboard Toggle word wrap
1
Specify the name of the Migration CR.

Canceling the migration of specific VMs

Add the specific VMs to the spec.cancel block of the Migration manifest:

Example YAML for canceling the migrations of two VMs

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102 
  - id: vm-203
  - name: rhel8-vm
EOF

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102

1


  - id: vm-203
  - name: rhel8-vm
EOF

Copy to Clipboard

Toggle word wrap

1: You can specify a VM by using the id key or the name key.

The value of the id key is the managed object reference, for a VMware VM, or the VM UUID, for a RHV VM.

Retrieve the Migration CR to monitor the progress of the remaining VMs:
```
oc get migration/<migration> -n <namespace> -o yaml
```
```
$ oc get migration/<migration> -n <namespace> -o yaml
```
Copy to Clipboard Toggle word wrap

11.7. Migrating from a Red Hat OpenShift Virtualization source provider
Copier lien

You can use a Red Hat OpenShift Virtualization provider as either a source provider or as a destination provider. You can migrate from an OpenShift Virtualization source provider by using the command-line interface (CLI).

Procedure

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

$ cat << EOF | oc apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: <secret>
  namespace: <namespace>
  ownerReferences:

1


    - apiVersion: forklift.konveyor.io/v1beta1
      kind: Provider
      name: <provider_name>
      uid: <provider_uid>
  labels:
    createdForProviderType: openshift
    createdForResourceType: providers
type: Opaque
stringData:
  token: <token>

2


  password: <password>

3


  insecureSkipVerify: <"true"/"false">

4


  cacert: |

5


    <ca_certificate>
  url: <api_end_point>

6

EOF

Copy to Clipboard

Toggle word wrap

1: The ownerReferences section is optional.
2: Specify a token for a service account with cluster-admin privileges. If both token and url are left blank, the local OpenShift cluster is used.
3: Specify the user password.
4: Specify "true" to skip certificate verification, and specify "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.
5: When this field is not set and skip certificate verification is disabled, MTV attempts to use the system CA.
6: Specify the URL of the endpoint of the API server.

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

$ 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>

1


  secret:
    name: <secret>

2


    namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Specify the URL of the endpoint of the API server.
2: Specify the name of provider Secret CR.

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

$  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

1


      source:
        name: <network_name>
        type: pod
    - destination:
        name: <network_attachment_definition>

2


        namespace: <network_attachment_definition_namespace>

3


        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

Copy to Clipboard

Toggle word wrap

1: Allowed values are pod and multus.
2: Specify a network attachment definition for each additional OpenShift Virtualization network. Specify the namespace either by using the namespace property or with a name built as follows: <network_namespace>/<network_name>.
3: Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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

$ 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>

1


      source:
        name: <storage_class>
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
EOF

Copy to Clipboard

Toggle word wrap

1: Allowed values are ReadWriteOnce and ReadWriteMany.

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: quay.io/konveyor/hook-runner
  serviceAccount:<service account> 
  playbook: |
    LS0tCi0gbm... 
EOF

$  cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Hook
metadata:
  name: <hook>
  namespace: <namespace>
spec:
  image: quay.io/konveyor/hook-runner
  serviceAccount:<service account>

1


  playbook: |
    LS0tCi0gbm...

2

EOF

Copy to Clipboard

Toggle word wrap

1: (Optional) Red Hat OpenShift service account. The serviceAccount must be provided if you want to manipulate any resources of the cluster.
2: 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.

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>
  vms:
    - name: <source_vm>
      namespace: <namespace>
      hooks: 
        - hook:
            namespace: <namespace>
            name: <hook> 
          step: <step> 
EOF

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Plan
metadata:
  name: <plan>

1


  namespace: <namespace>
spec:
  provider:
    source:
      name: <source_provider>
      namespace: <namespace>
    destination:
      name: <destination_provider>
      namespace: <namespace>
  map:

2


    network:

3


      name: <network_map>

4


      namespace: <namespace>
    storage:

5


      name: <storage_map>

6


      namespace: <namespace>
  targetNamespace: <target_namespace>
  vms:
    - name: <source_vm>
      namespace: <namespace>
      hooks:

7


        - hook:
            namespace: <namespace>
            name: <hook>

8


          step: <step>

9

EOF

Copy to Clipboard

Toggle word wrap

1: Specify the name of the Plan CR.
2: Specify only one network map and one storage map per plan.
3: Specify a network mapping, even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.
4: Specify the name of the NetworkMap CR.
5: Specify a storage mapping, even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.
6: Specify the name of the StorageMap CR.
7: Optional: You can specify up to two hooks for a VM. Each hook must run during a separate migration step.
8: Specify the name of the Hook CR.
9: Allowed values are PreHook, before the migration plan starts, or PostHook, after the migration is complete.

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

$ 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

Copy to Clipboard

Toggle word wrap

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.

11.7.1. Canceling a migration from the command-line interface
Copier lien

You can use the command-line interface (CLI) to cancel either an entire migration or the migration of specific virtual machines (VMs) while a migration is in progress.

Canceling an entire migration

Delete the Migration CR:
```
oc delete migration <migration> -n <namespace>
```
```
$ oc delete migration <migration> -n <namespace> 
```
1
Copy to Clipboard Toggle word wrap
1
Specify the name of the Migration CR.

Canceling the migration of specific VMs

Add the specific VMs to the spec.cancel block of the Migration manifest:

Example YAML for canceling the migrations of two VMs

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102 
  - id: vm-203
  - name: rhel8-vm
EOF

$ cat << EOF | oc apply -f -
apiVersion: forklift.konveyor.io/v1beta1
kind: Migration
metadata:
  name: <migration>
  namespace: <namespace>
...
spec:
  cancel:
  - id: vm-102

1


  - id: vm-203
  - name: rhel8-vm
EOF

Copy to Clipboard

Toggle word wrap

1: You can specify a VM by using the id key or the name key.

The value of the id key is the managed object reference, for a VMware VM, or the VM UUID, for a RHV VM.

Retrieve the Migration CR to monitor the progress of the remaining VMs:
```
oc get migration/<migration> -n <namespace> -o yaml
```
```
$ oc get migration/<migration> -n <namespace> -o yaml
```
Copy to Clipboard Toggle word wrap

Ce contenu n'est pas disponible dans la langue sélectionnée.

11.1. Permissions needed by non-administrators to work with migration plan components
Copier lien

11.2. Migrating virtual machines
Copier lien

11.3. Migrating from a VMware vSphere source provider
Copier lien

11.3.1. Retrieving a VMware vSphere moRef
Copier lien

11.3.2. Canceling a migration from the command-line interface
Copier lien

11.4. Migrating from a Red Hat Virtualization source provider
Copier lien

11.4.1. Canceling a migration from the command-line interface
Copier lien

11.5. Migrating from an OpenStack source provider
Copier lien

11.5.1. Canceling a migration from the command-line interface
Copier lien

11.6. Migrating from an Open Virtual Appliance (OVA) source provider
Copier lien

11.6.1. Canceling a migration from the command-line interface
Copier lien

11.7. Migrating from a Red Hat OpenShift Virtualization source provider
Copier lien

11.7.1. Canceling a migration from the command-line interface
Copier lien

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Rendre l’open source plus inclusif

À propos de Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 11. Migrating virtual machines from the command line

11.1. Permissions needed by non-administrators to work with migration plan componentsCopier lienLien copié sur presse-papiers!

11.2. Migrating virtual machinesCopier lienLien copié sur presse-papiers!

11.3. Migrating from a VMware vSphere source providerCopier lienLien copié sur presse-papiers!

11.3.1. Retrieving a VMware vSphere moRefCopier lienLien copié sur presse-papiers!

11.3.2. Canceling a migration from the command-line interfaceCopier lienLien copié sur presse-papiers!

11.4. Migrating from a Red Hat Virtualization source providerCopier lienLien copié sur presse-papiers!

11.4.1. Canceling a migration from the command-line interfaceCopier lienLien copié sur presse-papiers!

11.5. Migrating from an OpenStack source providerCopier lienLien copié sur presse-papiers!

11.5.1. Canceling a migration from the command-line interfaceCopier lienLien copié sur presse-papiers!

11.6. Migrating from an Open Virtual Appliance (OVA) source providerCopier lienLien copié sur presse-papiers!

11.6.1. Canceling a migration from the command-line interfaceCopier lienLien copié sur presse-papiers!

11.7. Migrating from a Red Hat OpenShift Virtualization source providerCopier lienLien copié sur presse-papiers!

11.7.1. Canceling a migration from the command-line interfaceCopier lienLien copié sur presse-papiers!

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Rendre l’open source plus inclusif

À propos de Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

11.1. Permissions needed by non-administrators to work with migration plan components
Copier lien

11.2. Migrating virtual machines
Copier lien

11.3. Migrating from a VMware vSphere source provider
Copier lien

11.3.1. Retrieving a VMware vSphere moRef
Copier lien

11.3.2. Canceling a migration from the command-line interface
Copier lien

11.4. Migrating from a Red Hat Virtualization source provider
Copier lien

11.4.1. Canceling a migration from the command-line interface
Copier lien

11.5. Migrating from an OpenStack source provider
Copier lien

11.5.1. Canceling a migration from the command-line interface
Copier lien

11.6. Migrating from an Open Virtual Appliance (OVA) source provider
Copier lien

11.6.1. Canceling a migration from the command-line interface
Copier lien

11.7. Migrating from a Red Hat OpenShift Virtualization source provider
Copier lien

11.7.1. Canceling a migration from the command-line interface
Copier lien