MTV user guide reorganization: Rearranging prerequisites

RichardHoch · RichardHoch · commit de72aeba68cf · 2025-02-17T10:45:20.000+02:00
Signed-off-by: RichardHoch &lt;rhoch@redhat.com&gt;
diff --git a/documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc b/documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc
@@ -46,20 +46,53 @@ include::modules/about-cold-warm-migration.adoc[leveloffset=+2]
 
 Review the following prerequisites to ensure that your environment is prepared for migration.
 
-[id="software-requirements_{context}"]
-=== Software requirements
+These prerequisites apply to all migrations. Prerequisites that apply only to a specific provider are discussed in the section dedicated to that source provider.
 
-You must install xref:compatibility-guidelines_{context}[compatible versions] of {ocp} and {virt}.
+include::modules/compatibility-guidelines.adoc[leveloffset=+2]
 
 include::modules/storage-support.adoc[leveloffset=+2]
-include::modules/network-prerequisites.adoc[leveloffset=+2]
+
 include::modules/source-vm-prerequisites.adoc[leveloffset=+2]
-include::modules/rhv-prerequisites.adoc[leveloffset=+2]
-include::modules/openstack-prerequisites.adoc[leveloffset=+2]
+
+=== Provider-specific prerequisites
+:!mtv:
+:context: vmware
+:vmware:
+
+include::modules/vmware-prerequisites.adoc[leveloffset=+3]
+include::modules/creating-vddk-image.adoc[leveloffset=+4]
+include::modules/increasing-nfc-memory-vmware-host.adoc[leveloffset=+4]
+include::modules/vddk-validator-containers.adoc[leveloffset=+4]
+include::modules/network-prerequisites.adoc[leveloffset=+4]
+
+:!vmware:
+:context: rhv
+:rhv:
+
+include::modules/rhv-prerequisites.adoc[leveloffset=+3]
+include::modules/file-system-overhead.adoc[leveloffset=+4]
+include::modules/network-prerequisites.adoc[leveloffset=+4]
+
+:!rhv:
+:context: ostack
+:ostack:
+
+include::modules/openstack-prerequisites.adoc[leveloffset=+3]
+
+[NOTE]
+====
+When migrating from OpenStack or running a cold-migration from RHV to the OCP cluster that MTV is deployed on, the migration allocates persistent volumes without CDI. In these cases, you might need to adjust the file system overhead.
+
+If the configured file system overhead, which has a default value of 10%, is too low, the disk transfer will fail due to lack of space. In such a case, you would want to increase the file system overhead.
+
+In some cases, however, you might want to decrease the file system overhead to reduce storage consumption.
+
+You can change the file system overhead by changing the value of the `controller_filesystem_overhead` in the `spec` portion of the `forklift-controller` CR, as described in xref:configuring-mtv-operator_mtv[Configuring the MTV Operator].
+====
 
 
 [id="additional-authentication-for-osp_{context}"]
-==== Additional authentication methods for migrations with {osp} source providers
+===== Additional authentication methods for migrations with {osp} source providers
 
 {project-short} versions 2.6 and later support the following authentication methods for migrations with {osp} source providers in addition to the standard username and password credential set:
 
@@ -68,25 +101,29 @@ include::modules/openstack-prerequisites.adoc[leveloffset=+2]
 
 You can use these methods to migrate virtual machines with {osp} source providers using the CLI the same way you migrate other virtual machines, except for how you prepare the `Secret` manifest.
 
-:!mtv:
-:context: ostack
-:ostack:
-
-include::modules/ostack-token-auth.adoc[leveloffset=+4]
-include::modules/ostack-app-cred-auth.adoc[leveloffset=+4]
+include::modules/ostack-token-auth.adoc[leveloffset=+5]
+include::modules/ostack-app-cred-auth.adoc[leveloffset=+5]
+include::modules/network-prerequisites.adoc[leveloffset=+4]
 
 :!ostack:
-:context: mtv
-:mtv:
+:context: ova
+:ova:
 
-include::modules/vmware-prerequisites.adoc[leveloffset=+2]
-include::modules/creating-vddk-image.adoc[leveloffset=+3]
-include::modules/increasing-nfc-memory-vmware-host.adoc[leveloffset=+3]
+include::modules/ova-prerequisites.adoc[leveloffset=+3]
+include::modules/network-prerequisites.adoc[leveloffset=+4]
 
-include::modules/vddk-validator-containers.adoc[leveloffset=+3]
+:!ova:
+:context: cnv
+:cnv:
 
-include::modules/ova-prerequisites.adoc[leveloffset=+2]
-include::modules/compatibility-guidelines.adoc[leveloffset=+2]
+==== {virt} prerequisites
+
+include::modules/snip_ocp_version_for_virt_source.adoc[]
+include::modules/network-prerequisites.adoc[leveloffset=+4]
+
+:!cnv:
+:context: mtv
+:mtv:
 
 [id="installing-the-operator_{context}"]
 == Installing and configuring the {operator-name}
@@ -126,9 +163,9 @@ You can migrate virtual machines (VMs) by using the {ocp} web console to:
 ====
 You must ensure that all xref:prerequisites_{context}[prerequisites] are met.
 
-VMware only: You must have the minimal set of xref:vmware-privileges_{context}[VMware privileges].
+// VMware only: You must have the minimal set of xref:vmware-privileges[VMware privileges].
 
-VMware only: Creating a xref:creating-vddk-image_{context}[VMware Virtual Disk Development Kit (VDDK)] image will increase migration speed.
+// VMware only: Creating a xref:creating-vddk-image[VMware Virtual Disk Development Kit (VDDK)] image will increase migration speed.
 ====
 
 include::modules/mtv-ui.adoc[leveloffset=+2]
diff --git a/documentation/modules/adding-source-provider.adoc b/documentation/modules/adding-source-provider.adoc
@@ -15,7 +15,11 @@ EMS enforcement is disabled for migrations with VMware vSphere source providers
 
 .Prerequisites
 
-* It is strongly recommended to create a VMware Virtual Disk Development Kit (VDDK) image in a secure registry that is accessible to all clusters. A VDDK image accelerates migration and reduces the risk of a plan failing. If you are not using VDDK and a plan fails, then please retry with VDDK installed. For more information, see xref:../master.adoc#creating-vddk-image_mtv[Creating a VDDK image].
+[NOTE]
+====
+It is strongly recommended to create a VMware Virtual Disk Development Kit (VDDK) image in a secure registry that is accessible to all clusters. A VDDK image accelerates migration and reduces the risk of a plan failing. If you are not using VDDK and a plan fails, then retry with VDDK installed. For more information, see xref:../master.adoc#creating-vddk-image_vmware[Creating a VDDK image].
+====
+
 endif::[]
 ifdef::rhv[]
 = Adding {a-rhv} source provider
@@ -88,7 +92,7 @@ ifdef::vmware[]
 * *Provider resource name*: Name of the source provider.
 * *Endpoint type*: Select the vSphere provider endpoint type. Options: *vCenter* or *ESXi*. You can migrate virtual machines from vCenter, an ESX/ESXi server that is not managed by vCenter, or from an ESX/ESXi server that is managed by vCenter but does not go through vCenter.
 * *URL*: URL of the SDK endpoint of the vCenter on which the source VM is mounted. Ensure that the URL includes the `sdk` path, usually `/sdk`. For example, `https://vCenter-host-example.com/sdk`. If a certificate for FQDN is specified, the value of this field needs to match the FQDN in the certificate.
-* *VDDK init image*: `VDDKInitImage` path. It is strongly recommended to create a VDDK init image to accelerate migrations. For more information, see xref:../master.adoc#creating-vddk-image_mtv[Creating a VDDK image].
+* *VDDK init image*: `VDDKInitImage` path. It is strongly recommended to create a VDDK init image to accelerate migrations. For more information, see xref:../master.adoc#creating-vddk-image_vmware[Creating a VDDK image].
 
 +
 *Provider credentials*
diff --git a/documentation/modules/additional-auth-methods-ostack.adoc b/documentation/modules/additional-auth-methods-ostack.adoc
@@ -0,0 +1,9 @@
+[id="additional-authentication-methods-osp_{context}"]
+= Additional authentication methods for migrations with {osp} source providers
+
+{project-short} versions 2.6 and later support the following authentication methods for migrations with {osp} source providers in addition to the standard username and password credential set:
+
+* Token authentication
+* Application credential authentication
+
+You can use these methods to migrate virtual machines with {osp} source providers using the CLI the same way you migrate other virtual machines with one exception: You need to prepare the `Secret` manifest as described in xref:openstack-token-authentication_ostack[Using token authentication with an {osp} source provider] or xref:openstack-application-credential-authentication_ostack[Using application credential authentication with an {osp} source provider].
diff --git a/documentation/modules/compatibility-guidelines.adoc b/documentation/modules/compatibility-guidelines.adoc
@@ -4,9 +4,9 @@
 
 :_content-type: REFERENCE
 [id="compatibility-guidelines_{context}"]
-= Software compatibility guidelines
+= Software compatibility requirements
 
-You must install compatible software versions.
+You must install compatible software versions of {ocp}, {virt}, and any software related to your source provider. The table that follows lists the correct software versions.
 
 
 // check OCP version
diff --git a/documentation/modules/creating-vddk-image.adoc b/documentation/modules/creating-vddk-image.adoc
@@ -8,12 +8,7 @@
 
 It is strongly recommended that {project-first} should be used with the VMware Virtual Disk Development Kit (VDDK) SDK when transferring virtual disks from VMware vSphere.
 
-[NOTE]
-====
-Creating a VDDK image, although optional, is highly recommended. Using {project-short} without VDDK is not recommended and could result in significantly lower migration speeds.
-====
-
-To make use of this feature, you download the VMware Virtual Disk Development Kit (VDDK), build a VDDK image, and push the VDDK image to your image registry.
+To make use of this feature, you download the VMware Virtual Disk Development Kit (VDDK), build a VDDK image, and push the VDDK image to a secure registry that is accessible to all clusters.
 
 The VDDK package contains symbolic links, therefore, the procedure of creating a VDDK image must be performed on a file system that preserves symbolic links (symlinks).
 
@@ -40,12 +35,11 @@ $ mkdir /tmp/<dir_name> && cd /tmp/<dir_name>
 
 . In a browser, navigate to the link:https://developer.vmware.com/web/sdk/8.0/vddk[VMware VDDK version 8 download page].
 . Select version 8.0.1 and click *Download*.
-
++
 [NOTE]
 ====
 In order to migrate to {virt} 4.12, download VDDK version 7.0.3.2 from the link:https://developer.vmware.com/web/sdk/7.0/vddk[VMware VDDK version 7 download page].
 ====
-
 // On 17 January 2025, remove this note unless the OpenShift Container Platform's life cycle is extended.
 
 . Save the VDDK archive file in the temporary directory.
diff --git a/documentation/modules/file-system-overhead.adoc b/documentation/modules/file-system-overhead.adoc
@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc
+
+:_content-type: CONCEPT
+[id="file-system-overhead_{context}"]
+= File system overhead
+ifdef::rhv[]
+When you run a cold migration from {rhv-full} to the {ocp} cluster that {project-full} is deployed on, the migration allocates persistent volumes without Customized Data Importer (CDI). In these cases, for  volumes on a persistent volume claim that use the `volumeMode` file system, you might need to adjust the file system overhead.
+endif::[]
+
+
+ifdef::ostack[]
+When you migrate from {osp} to the {ocp} cluster that {project-full} is deployed on, the migration allocates persistent volumes without Customized Data Importer (CDI).In these cases, for  volumes on a persistent volume claim that use the `volumeMode` file system, you might need to adjust the file system overhead.
+endif::[]
+
+The configured file system overhead has a default value of 10%. If that is too low, the disk transfer fails due to lack of space. In this case, increase the file system overhead.
+
+You can change the file system overhead by changing the value of the `controller_filesystem_overhead` in the `spec` portion of the `forklift-controller` CR, as described in xref:configuring-mtv-operator_mtv[Configuring the MTV Operator].
+
diff --git a/documentation/modules/network-prerequisites.adoc b/documentation/modules/network-prerequisites.adoc
@@ -4,9 +4,8 @@
 
 :_content-type: REFERENCE
 [id="network-prerequisites_{context}"]
-= Network prerequisites
 
-The following prerequisites apply to all migrations:
+= Network prerequisites
 
 * IP addresses, VLANs, and other network configuration settings must not be changed before or during migration. The MAC addresses of the virtual machines are preserved during migration.
 * The network connections between the source environment, the {virt} cluster, and the replication repository must be reliable and uninterrupted.
@@ -17,6 +16,8 @@ The following prerequisites apply to all migrations:
 
 The firewalls must enable traffic over the following ports:
 
+ifdef::vmware[]
+
 [cols="1,1,1,1,2a",options="header"]
 .Network ports required for migrating from VMware vSphere
 |===
@@ -43,8 +44,12 @@ Disk transfer authentication
 |Disk transfer data copy
 |===
 
+
+endif::[]
+ifdef::rhv[]
+
 [cols="1,1,1,1,2a",options="header"]
-.Network ports required for migrating from {rhv-full}
+.Network ports required for migrating from {rhv-full} {rhv-short}
 |===
 |Port |Protocol |Source |Destination |Purpose
 
@@ -68,3 +73,25 @@ Disk transfer authentication
 |{rhv-short} hosts
 |Disk transfer data copy
 |===
+endif::[]
+ifdef::ostack[]
+
+.Network ports required for migrating from OpenStack
+
+TBD
+
+endif::[]
+ifdef::ova[]
+
+.Network ports required for migrating from OVA
+
+TBD
+
+endif::[]
+ifdef::cnv[]
+
+.Network ports required for migrating from {virt}
+
+TBD
+
+endif::[]
diff --git a/documentation/modules/openstack-prerequisites.adoc b/documentation/modules/openstack-prerequisites.adoc
@@ -8,5 +8,5 @@
 
 The following prerequisites apply to {osp} migrations:
 
-* You must use a xref:compatibility-guidelines_{context}[compatible version] of {osp}.
+* You must use a xref:compatibility-guidelines_mtv[compatible version] of {osp}.
 
diff --git a/documentation/modules/ostack-app-cred-auth.adoc b/documentation/modules/ostack-app-cred-auth.adoc
@@ -93,3 +93,4 @@ stringData:
 EOF
 ----
 . Continue migrating your virtual machine according to the procedure in xref:new-migrating-virtual-machines-cli_ostack[Migrating virtual machines], starting with step 2, "Create a `Provider` manifest for the source provider."
+
diff --git a/documentation/modules/rhv-prerequisites.adoc b/documentation/modules/rhv-prerequisites.adoc
@@ -6,7 +6,7 @@
 [id="rhv-prerequisites_{context}"]
 = {rhv-full} prerequisites
 
-The following prerequisites apply to {rhv-full} migrations:
+The following prerequisites apply to {rhv-full} ({rhv-short}) migrations:
 
 * To create a source provider, you must have at least the `UserRole` and `ReadOnlyAdmin` roles assigned to you. These are the minimum required permissions, however, any other administrator or superuser permissions will also work.
 
@@ -20,7 +20,7 @@ You must keep the `UserRole` and `ReadOnlyAdmin` roles until the virtual machine
 *** {rhv-short} admin permissions. These permissions allow you to migrate any virtual machine in the system.
 *** `DiskCreator` and `UserVmManager` permissions on every virtual machine you want to migrate.
 
-** You must use a xref:compatibility-guidelines_{context}[compatible version] of {rhv-full}.
+** You must use a xref:compatibility-guidelines_mtv[compatible version] of {rhv-full}.
 ** You must have the {manager} CA certificate, unless it was replaced by a third-party certificate, in which case, specify the {manager} Apache CA certificate.
 +
 You can obtain the {manager} CA certificate by navigating to https://<engine_host>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA in a browser.
diff --git a/documentation/modules/snip_ocp_version_for_virt_source.adoc b/documentation/modules/snip_ocp_version_for_virt_source.adoc
@@ -0,0 +1,4 @@
+[NOTE]
+====
+The {ocp} cluster version of the source provider must be 4.13 or later.
+====
diff --git a/documentation/modules/storage-support.adoc b/documentation/modules/storage-support.adoc
@@ -77,13 +77,4 @@ See link:https://access.redhat.com/documentation/en-us/openshift_container_platf
 If your migration uses block storage and persistent volumes created with an EXT4 file system, increase the file system overhead in CDI to be more than 10%. The default overhead that is assumed by CDI does not completely include the reserved place for the root partition. If you do not increase the file system overhead in CDI by this amount, your migration might fail.
 ====
 
-[NOTE]
-====
-When migrating from OpenStack or running a cold-migration from RHV to the OCP cluster that MTV is deployed on, the migration allocates persistent volumes without CDI. In these cases, you might need to adjust the file system overhead.
-
-If the configured file system overhead, which has a default value of 10%, is too low, the disk transfer will fail due to lack of space. In such a case, you would want to increase the file system overhead.
 
-In some cases, however, you might want to decrease the file system overhead to reduce storage consumption.
-
-You can change the file system overhead by changing the value of the `controller_filesystem_overhead` in the `spec` portion of the `forklift-controller` CR, as described in xref:configuring-mtv-operator_{context}[Configuring the MTV Operator].
-====
diff --git a/documentation/modules/vmware-prerequisites.adoc b/documentation/modules/vmware-prerequisites.adoc
@@ -5,27 +5,34 @@
 [id="vmware-prerequisites_{context}"]
 = VMware prerequisites
 
-It is strongly recommended to create a VDDK image to accelerate migrations. For more information, see xref:../master.adoc#creating-vddk-image_mtv[Creating a VDDK image].
-
 The following prerequisites apply to VMware migrations:
 
-* You must use a xref:compatibility-guidelines_{context}[compatible version] of VMware vSphere.
+* You must use a xref:compatibility-guidelines_mtv[compatible version] of VMware vSphere.
 * You must be logged in as a user with at least the minimal set of xref:vmware-privileges_{context}[VMware privileges].
 * To access the virtual machine using a pre-migration hook, link:https://www.vmware.com/support/ws5/doc/new_guest_tools_ws.html[VMware Tools] must be installed on the source virtual machine.
 * The VM operating system must be certified and supported for use as a link:https://access.redhat.com/articles/973163#ocpvirt[guest operating system with {virt}] _and_ for link:https://access.redhat.com/articles/1351473[conversion to KVM with `virt-v2v`].
 * If you are running a warm migration, you must enable link:https://kb.vmware.com/s/article/1020128[changed block tracking (CBT)] on the VMs and on the VM disks.
 * If you are migrating more than 10 VMs from an ESXi host in the same migration plan, you must increase the NFC service memory of the host.
-* It is strongly recommended to disable hibernation because {project-first} does not support migrating hibernated VMs.
 
 
 [IMPORTANT]
 ====
-In the event of a power outage, data might be lost for a VM with disabled hibernation. However, if hibernation is not disabled, migration will fail
+In the event of a power outage, data might be lost for a VM with disabled hibernation. However, if hibernation is not disabled, migration will fail.
+====
+
+[NOTE]
+====
+Neither {project-short} nor {virt} support conversion of Btrfs for migrating VMs from VMWare.
 ====
 
 [NOTE]
 ====
-Neither {project-short} nor OpenShift Virtualization support conversion of Btrfs for migrating VMs from VMWare.
+It is strongly recommended to create a VMware Virtual Disk Development Kit (VDDK) image in a secure registry that is accessible to all clusters. A VDDK image accelerates migration and reduces the risk of a plan failing. If you are not using VDDK and a plan fails, then retry with VDDK installed. For more information, see xref:../master.adoc#creating-vddk-image_vmware[Creating a VDDK image].
+====
+
+[TIP]
+====
+It is strongly recommended to disable hibernation because {project-first} does not support migrating hibernated VMs.
 ====
 
 [discrete]

Original file line number	Diff line number	Diff line change
`@@ -8,5 +8,5 @@`
`8`	`8`
`9`	`9`	`The following prerequisites apply to {osp} migrations:`
`10`	`10`
`11`		`-* You must use a xref:compatibility-guidelines_{context}[compatible version] of {osp}.`
	`11`	`+* You must use a xref:compatibility-guidelines_mtv[compatible version] of {osp}.`
`12`	`12`
-Original file line number
+Diff line change
 EOF
 ----
 . Continue migrating your virtual machine according to the procedure in xref:new-migrating-virtual-machines-cli_ostack[Migrating virtual machines], starting with step 2, "Create a `Provider` manifest for the source provider."
++