From c5fbfcf7e94dc4e6075493c6118b4b1e783e018e Mon Sep 17 00:00:00 2001 From: "A.Arnold" Date: Wed, 11 Mar 2026 17:22:05 +0000 Subject: [PATCH 1/2] CQA 11th March - TOC fix Signed-off-by: A.Arnold --- .../assembly_advanced-migration-options.adoc | 2 + .../assembly_migrating-from-vmware.adoc | 4 +- .../assembly_troubleshooting-migration.adoc | 2 + .../assembly_understanding-mtv-migration.adoc | 4 + .../assembly_cold-warm-migration.adoc | 4 + .../assembly_migrating-vms-web-console.adoc | 4 + .../assembly_planning-migration-vmware.adoc | 6 + ...r-specific-requirements-for-migration.adoc | 4 + ...y_software-requirements-for-migration.adoc | 2 + ...bout-cold-warm-migration-toc-sections.adoc | 26 ++++ .../modules/about-cold-warm-migration.adoc | 25 ---- ...ing-target-vm-scheduling-toc-sections.adoc | 8 ++ ...bout-configuring-target-vm-scheduling.adoc | 8 -- ...out-storage-copy-offload-toc-sections.adoc | 41 ++++++ .../modules/about-storage-copy-offload.adoc | 40 ------ ...compatibility-guidelines-toc-sections.adoc | 4 + .../modules/compatibility-guidelines.adoc | 3 - .../con_copy-methods-sco-toc-sections.adoc | 10 ++ .../modules/con_copy-methods-sco.adoc | 10 -- ...ing-storage-copy-offload-toc-sections.adoc | 91 +++++++++++++ ..._troubleshooting-storage-copy-offload.adoc | 90 ------------- .../modules/mtv-aio-buffer-toc-sections.adoc | 22 +++ .../mtv-esxi-performance-toc-sections.adoc | 110 +++++++++++++++ .../mtv-overview-page-toc-sections.adoc | 103 +++++++++++++++ documentation/modules/mtv-overview-page.adoc | 102 -------------- ...v-resources-and-services-toc-sections.adoc | 28 ++++ .../modules/mtv-resources-and-services.adoc | 28 ---- ...shared-disks-workarounds-toc-sections.adoc | 27 ++++ .../modules/mtv-shared-disks-workarounds.adoc | 28 ---- .../modules/mtv-ui-toc-sections.adoc | 18 +++ documentation/modules/mtv-ui.adoc | 17 --- .../network-prerequisites-toc-sections.adoc | 125 ++++++++++++++++++ .../modules/network-prerequisites.adoc | 124 ----------------- ...fload-general-ssh-set-up-toc-sections.adoc | 16 +++ ...orage-copy-offload-general-ssh-set-up.adoc | 15 --- documentation/modules/ref_mtv-aio-buffer.adoc | 21 --- .../modules/ref_mtv-esxi-performance.adoc | 6 +- .../modules/virt-v2v-mtv-toc-sections.adoc | 49 +++++++ documentation/modules/virt-v2v-mtv.adoc | 48 ------- .../vmware-prerequisites-toc-sections.adoc | 65 +++++++++ .../modules/vmware-prerequisites.adoc | 64 --------- .../warm-migration-stages-toc-sections.adoc | 18 +++ .../modules/warm-migration-stages.adoc | 18 --- 43 files changed, 797 insertions(+), 643 deletions(-) create mode 100644 documentation/modules/about-cold-warm-migration-toc-sections.adoc create mode 100644 documentation/modules/about-configuring-target-vm-scheduling-toc-sections.adoc create mode 100644 documentation/modules/about-storage-copy-offload-toc-sections.adoc create mode 100644 documentation/modules/compatibility-guidelines-toc-sections.adoc create mode 100644 documentation/modules/con_copy-methods-sco-toc-sections.adoc create mode 100644 documentation/modules/con_troubleshooting-storage-copy-offload-toc-sections.adoc create mode 100644 documentation/modules/mtv-aio-buffer-toc-sections.adoc create mode 100644 documentation/modules/mtv-esxi-performance-toc-sections.adoc create mode 100644 documentation/modules/mtv-overview-page-toc-sections.adoc create mode 100644 documentation/modules/mtv-resources-and-services-toc-sections.adoc create mode 100644 documentation/modules/mtv-shared-disks-workarounds-toc-sections.adoc create mode 100644 documentation/modules/mtv-ui-toc-sections.adoc create mode 100644 documentation/modules/network-prerequisites-toc-sections.adoc create mode 100644 documentation/modules/proc_storage-copy-offload-general-ssh-set-up-toc-sections.adoc create mode 100644 documentation/modules/virt-v2v-mtv-toc-sections.adoc create mode 100644 documentation/modules/vmware-prerequisites-toc-sections.adoc create mode 100644 documentation/modules/warm-migration-stages-toc-sections.adoc diff --git a/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_advanced-migration-options.adoc b/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_advanced-migration-options.adoc index 44265162d11..4d7558f9809 100644 --- a/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_advanced-migration-options.adoc +++ b/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_advanced-migration-options.adoc @@ -45,6 +45,8 @@ include::../modules/con_scheduling-target-vms-intro.adoc[leveloffset=+1] include::../modules/about-configuring-target-vm-scheduling.adoc[leveloffset=+2] +include::../modules/about-configuring-target-vm-scheduling-toc-sections.adoc[leveloffset=+1] + include::../modules/target-vm-scheduling-prerequisites.adoc[leveloffset=+2] include::../modules/target-vm-scheduling-options.adoc[leveloffset=+2] diff --git a/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-vmware.adoc b/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-vmware.adoc index 658a73e91a4..d1ea4d3c5a5 100644 --- a/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-vmware.adoc +++ b/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-vmware.adoc @@ -38,6 +38,8 @@ include::../modules/mtv-shared-disks-known-issues.adoc[leveloffset=+3] include::../modules/mtv-shared-disks-workarounds.adoc[leveloffset=+3] +include::../modules/mtv-shared-disks-workarounds-toc-sections.adoc[leveloffset=+1] + include::../modules/mtv-template-utility.adoc[leveloffset=+2] include::../modules/canceling-migration-cli.adoc[leveloffset=+2] @@ -49,4 +51,4 @@ include::../modules/canceling-migration-cli-specific.adoc[leveloffset=+3] :vmware!: ifdef::parent-context[:context: {parent-context}] -ifndef::parent-context[:!context:] \ No newline at end of file +ifndef::parent-context[:!context:] diff --git a/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_troubleshooting-migration.adoc b/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_troubleshooting-migration.adoc index d424cd1a3e5..973147ef7c1 100644 --- a/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_troubleshooting-migration.adoc +++ b/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_troubleshooting-migration.adoc @@ -32,6 +32,8 @@ include::../modules/proc_troubleshooting-vddk-required-vsan.adoc[leveloffset=+2] include::../modules/con_troubleshooting-storage-copy-offload.adoc[leveloffset=+1] +include::../modules/con_troubleshooting-storage-copy-offload-toc-sections.adoc[leveloffset=+1] + include::../modules/using-must-gather.adoc[leveloffset=+1] include::../modules/collected-logs-cr-info.adoc[leveloffset=+1] diff --git a/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_understanding-mtv-migration.adoc b/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_understanding-mtv-migration.adoc index d9592760487..9a969c08a2a 100644 --- a/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_understanding-mtv-migration.adoc +++ b/documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_understanding-mtv-migration.adoc @@ -16,10 +16,14 @@ Understand the {project-first} custom resources, services, and workflows that en include::../modules/mtv-resources-and-services.adoc[leveloffset=+1] +include::../modules/mtv-resources-and-services-toc-sections.adoc[leveloffset=+1] + include::../modules/mtv-workflow.adoc[leveloffset=+1] include::../modules/virt-migration-workflow.adoc[leveloffset=+2] +include::../modules/virt-v2v-mtv-toc-sections.adoc[leveloffset=+1] + include::../modules/virt-v2v-mtv.adoc[leveloffset=+2] include::../modules/raw-copy-mode.adoc[leveloffset=+2] diff --git a/documentation/doc-Planning_your_migration/assemblies/assembly_cold-warm-migration.adoc b/documentation/doc-Planning_your_migration/assemblies/assembly_cold-warm-migration.adoc index 389b07534ab..0ce0c8fd374 100644 --- a/documentation/doc-Planning_your_migration/assemblies/assembly_cold-warm-migration.adoc +++ b/documentation/doc-Planning_your_migration/assemblies/assembly_cold-warm-migration.adoc @@ -16,6 +16,10 @@ ifdef::context[:parent-context: {context}] include::../modules/about-cold-warm-migration.adoc[leveloffset=+1] +include::../modules/about-cold-warm-migration-toc-sections.adoc[leveloffset=+1] + +include::../modules/warm-migration-stages-toc-sections.adoc[leveloffset=+1] + include::../modules/warm-migration-stages.adoc[leveloffset=+1] include::../modules/mtv-migration-speed-comparison.adoc[leveloffset=+1] diff --git a/documentation/doc-Planning_your_migration/assemblies/assembly_migrating-vms-web-console.adoc b/documentation/doc-Planning_your_migration/assemblies/assembly_migrating-vms-web-console.adoc index e7c1f3fb2f4..a6d6c545ef9 100644 --- a/documentation/doc-Planning_your_migration/assemblies/assembly_migrating-vms-web-console.adoc +++ b/documentation/doc-Planning_your_migration/assemblies/assembly_migrating-vms-web-console.adoc @@ -26,8 +26,12 @@ include::../modules/con_navigating-mtv-pages.adoc[leveloffset=+1] include::../modules/mtv-ui.adoc[leveloffset=+1] +include::../modules/mtv-ui-toc-sections.adoc[leveloffset=+1] + include::../modules/mtv-overview-page.adoc[leveloffset=+1] +include::../modules/mtv-overview-page-toc-sections.adoc[leveloffset=+1] + include::../modules/proc_choosing-different-controller-transfer-network.adoc[leveloffset=+2] include::../modules/con_preparing-vms-for-migration.adoc[leveloffset=+1] diff --git a/documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc b/documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc index 7b6b65bf773..d11ab68ba2c 100644 --- a/documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc +++ b/documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc @@ -25,10 +25,16 @@ include::../modules/creating-yaml-based-storage-maps-ui-vmware.adoc[leveloffset= include::../modules/about-storage-copy-offload.adoc[leveloffset=+1] +include::../modules/about-storage-copy-offload-toc-sections.adoc[leveloffset=+1] + include::../modules/proc_storage-copy-offload-steps.adoc[leveloffset=+2] +include::../modules/con_copy-methods-sco-toc-sections.adoc[leveloffset=+1] + include::../modules/con_copy-methods-sco.adoc[leveloffset=+2] +include::../modules/proc_storage-copy-offload-general-ssh-set-up-toc-sections.adoc[leveloffset=+1] + include::../modules/proc_storage-copy-offload-vib-set-up.adoc[leveloffset=+3] include::../modules/proc_storage-copy-offload-general-ssh-set-up.adoc[leveloffset=+3] diff --git a/documentation/doc-Planning_your_migration/assemblies/assembly_provider-specific-requirements-for-migration.adoc b/documentation/doc-Planning_your_migration/assemblies/assembly_provider-specific-requirements-for-migration.adoc index 439d94d1d90..97af550cef4 100644 --- a/documentation/doc-Planning_your_migration/assemblies/assembly_provider-specific-requirements-for-migration.adoc +++ b/documentation/doc-Planning_your_migration/assemblies/assembly_provider-specific-requirements-for-migration.adoc @@ -22,6 +22,8 @@ include::../modules/ostack-app-cred-auth.adoc[leveloffset=+2] include::../modules/vmware-prerequisites.adoc[leveloffset=+1] +include::../modules/vmware-prerequisites-toc-sections.adoc[leveloffset=+1] + include::../modules/creating-vmware-role-mtv-permissions.adoc[leveloffset=+2] include::../modules/creating-vddk-image.adoc[leveloffset=+2] @@ -38,6 +40,8 @@ include::../modules/cnv-cnv-live-prerequisites.adoc[leveloffset=+2] include::../modules/compatibility-guidelines.adoc[leveloffset=+1] +include::../modules/compatibility-guidelines-toc-sections.adoc[leveloffset=+1] + ifdef::parent-context[:context: {parent-context}] ifndef::parent-context[:!context:] diff --git a/documentation/doc-Planning_your_migration/assemblies/assembly_software-requirements-for-migration.adoc b/documentation/doc-Planning_your_migration/assemblies/assembly_software-requirements-for-migration.adoc index 1c6160ff80d..9e4e651fa46 100644 --- a/documentation/doc-Planning_your_migration/assemblies/assembly_software-requirements-for-migration.adoc +++ b/documentation/doc-Planning_your_migration/assemblies/assembly_software-requirements-for-migration.adoc @@ -20,6 +20,8 @@ include::../modules/storage-support.adoc[leveloffset=+1] include::../modules/network-prerequisites.adoc[leveloffset=+1] +include::../modules/network-prerequisites-toc-sections.adoc[leveloffset=+1] + include::../modules/ref_source-vm-prerequisites.adoc[leveloffset=+1] include::../modules/ref_source-vm-migration-considerations.adoc[leveloffset=+1] diff --git a/documentation/modules/about-cold-warm-migration-toc-sections.adoc b/documentation/modules/about-cold-warm-migration-toc-sections.adoc new file mode 100644 index 00000000000..ae710c480af --- /dev/null +++ b/documentation/modules/about-cold-warm-migration-toc-sections.adoc @@ -0,0 +1,26 @@ += Cold migration + + +Cold migration is the default migration type. The source virtual machines are shut down while the data is copied. + +Cold migration converts each VM to be compatible with {ocp-short} before transferring it. If a VM cannot be converted, the migration fails immediately (fail fast). All disk blocks are copied once in a sequential process. + +[NOTE] +==== +VMware only: In cold migrations, in situations in which a package manager cannot be used during the migration, {project-short} does not install the `qemu-guest-agent` daemon on the migrated VMs. This has some impact on the functionality of the migrated VMs, but overall, they are still expected to function. + +To enable {project-short} to automatically install `qemu-guest-agent` on the migrated VMs, ensure that your package manager can install the daemon during the first boot of the VM after migration. + +If that is not possible, use your preferred automated or manual procedure to install `qemu-guest-agent` manually. +==== + +== Warm migration + +Warm migration copies most of the data while the source virtual machines (VMs) remain running, minimizing downtime. + +The migration process has two stages: + +* *Precopy stage*: Most data is copied while VMs continue running. VM disks are copied incrementally using link:https://kb.vmware.com/s/article/1020128[changed block tracking (CBT)] snapshots. +* *Cutover stage*: VMs are shut down and the remaining data is migrated. Data stored in RAM is not migrated. + +Warm migration transfers snapshots to {ocp-short} first, then converts the VM during the cutover stage. This means disk blocks may be copied multiple times if the VM has high utilization, but VMs remain available during most of the migration process. You must enable CBT for each source VM and each VM disk before starting a warm migration. diff --git a/documentation/modules/about-cold-warm-migration.adoc b/documentation/modules/about-cold-warm-migration.adoc index 6ad1399bc38..ef310a90290 100644 --- a/documentation/modules/about-cold-warm-migration.adoc +++ b/documentation/modules/about-cold-warm-migration.adoc @@ -16,28 +16,3 @@ OVA migration is validated for migrating supported guest operating systems expor ==== [id="cold-migration_{context}"] -== Cold migration - -Cold migration is the default migration type. The source virtual machines are shut down while the data is copied. - -Cold migration converts each VM to be compatible with {ocp-short} before transferring it. If a VM cannot be converted, the migration fails immediately (fail fast). All disk blocks are copied once in a sequential process. - -[NOTE] -==== -VMware only: In cold migrations, in situations in which a package manager cannot be used during the migration, {project-short} does not install the `qemu-guest-agent` daemon on the migrated VMs. This has some impact on the functionality of the migrated VMs, but overall, they are still expected to function. - -To enable {project-short} to automatically install `qemu-guest-agent` on the migrated VMs, ensure that your package manager can install the daemon during the first boot of the VM after migration. - -If that is not possible, use your preferred automated or manual procedure to install `qemu-guest-agent` manually. -==== - -== Warm migration - -Warm migration copies most of the data while the source virtual machines (VMs) remain running, minimizing downtime. - -The migration process has two stages: - -* *Precopy stage*: Most data is copied while VMs continue running. VM disks are copied incrementally using link:https://kb.vmware.com/s/article/1020128[changed block tracking (CBT)] snapshots. -* *Cutover stage*: VMs are shut down and the remaining data is migrated. Data stored in RAM is not migrated. - -Warm migration transfers snapshots to {ocp-short} first, then converts the VM during the cutover stage. This means disk blocks may be copied multiple times if the VM has high utilization, but VMs remain available during most of the migration process. You must enable CBT for each source VM and each VM disk before starting a warm migration. diff --git a/documentation/modules/about-configuring-target-vm-scheduling-toc-sections.adoc b/documentation/modules/about-configuring-target-vm-scheduling-toc-sections.adoc new file mode 100644 index 00000000000..ba4232383d7 --- /dev/null +++ b/documentation/modules/about-configuring-target-vm-scheduling-toc-sections.adoc @@ -0,0 +1,8 @@ += Use cases + + +Target VM scheduling is designed to help you with the following use cases, among others: + +* *Business continuity and disaster recovery*: You can use scheduling rules to migrate and power up critical VMs to several sites, in different time zones or otherwise geographically separated by significant distances. This allows you to deploy these VMs as strategic assets for business continuity, such as disaster recovery. + +* *Working with fluctuating demands*: In situations where demand for a service might vary significantly, rules for scheduling when to spin up VMs based upon demand allows you to use your resources more efficiently. diff --git a/documentation/modules/about-configuring-target-vm-scheduling.adoc b/documentation/modules/about-configuring-target-vm-scheduling.adoc index 53a7e0d5a55..e517c312835 100644 --- a/documentation/modules/about-configuring-target-vm-scheduling.adoc +++ b/documentation/modules/about-configuring-target-vm-scheduling.adoc @@ -10,11 +10,3 @@ Starting with {project-first} 2.10, you can use the _target VM scheduling_ feature to direct {project-short} to migrate virtual machines (VMs) to specific nodes of {virt} as well as to schedule when to power on the VMs. Using the feature, you can design and enforce rules that you set using either the UI or command-line interface. Previously, when you migrated VMs to {virt}, {virt} automatically determined the node the VMs would be migrated to. Although this served many customers' needs, there are certain situations in which it is useful to be able to specify the target node of a VM or the conditions under which the VM is powered on, regardless of the type of migration involved. - -== Use cases - -Target VM scheduling is designed to help you with the following use cases, among others: - -* *Business continuity and disaster recovery*: You can use scheduling rules to migrate and power up critical VMs to several sites, in different time zones or otherwise geographically separated by significant distances. This allows you to deploy these VMs as strategic assets for business continuity, such as disaster recovery. - -* *Working with fluctuating demands*: In situations where demand for a service might vary significantly, rules for scheduling when to spin up VMs based upon demand allows you to use your resources more efficiently. diff --git a/documentation/modules/about-storage-copy-offload-toc-sections.adoc b/documentation/modules/about-storage-copy-offload-toc-sections.adoc new file mode 100644 index 00000000000..37f2ec19532 --- /dev/null +++ b/documentation/modules/about-storage-copy-offload-toc-sections.adoc @@ -0,0 +1,41 @@ += How storage copy offload works + + +Without storage copy offload, {project-short} migrates a virtual disk as follows: + +. {project-short} reads the disk from the source storage. +. {project-short} sends the data over a network to {virt}. +. {virt} writes the data to its storage. ++ +This method can be slow and consume significant network and host resources. + +With storage copy offload, the process is streamlined: + +. {project-short} initiates a disk transfer request. +. Instead of sending the data, {project-short} instructs the storage array in which the vSphere Virtual Machine File System (VMFS) datastore holds the source VMs to perform a direct copy from the source storage to the target volume, on the same array, in the correct storage class. ++ +The storage array handles the cloning of the VM disk internally, often at a much higher speed than a network-based transfer. + +The Forklift project, a key component of {project-short}, includes a specialized volume populator named `vsphere-xcopy-volume-populator` that directly interacts with {vmw}'s VAAI. This allows {project-short} to trigger the high-speed, array-level data copy operation for supported storage systems. + +[IMPORTANT] +==== +The storage arrays must be the ones specified above. Otherwise, XCOPY performs a fallback network disk copy on the ESXi. Although a fallback network disk copy on the ESXi is usually considerably faster than a standard migration using a VDDK image over the network, it is not as quick as a properly configured storage copy offload migration. +==== + +[id="storage-copy-offload-works-supported-providers_{context}"] +== Supported storage providers + +The following storage providers support storage copy offload: + +* Hitachi Vantara +* NetApp ONTAP +* Pure Storage FlashArray +* Dell PowerMax +* Dell PowerFlex +* Dell PowerStore +* HPE 3PAR +* HPE Primera +* Infinidat Infinibox +* IBM Flashsystem + diff --git a/documentation/modules/about-storage-copy-offload.adoc b/documentation/modules/about-storage-copy-offload.adoc index 3db48d76fa1..60f75ab2cfb 100644 --- a/documentation/modules/about-storage-copy-offload.adoc +++ b/documentation/modules/about-storage-copy-offload.adoc @@ -30,43 +30,3 @@ features, see https://access.redhat.com/support/offerings/techpreview/[Technolog ==== [id="how-storage-copy-offload-works_{context}"] -== How storage copy offload works - -Without storage copy offload, {project-short} migrates a virtual disk as follows: - -. {project-short} reads the disk from the source storage. -. {project-short} sends the data over a network to {virt}. -. {virt} writes the data to its storage. -+ -This method can be slow and consume significant network and host resources. - -With storage copy offload, the process is streamlined: - -. {project-short} initiates a disk transfer request. -. Instead of sending the data, {project-short} instructs the storage array in which the vSphere Virtual Machine File System (VMFS) datastore holds the source VMs to perform a direct copy from the source storage to the target volume, on the same array, in the correct storage class. -+ -The storage array handles the cloning of the VM disk internally, often at a much higher speed than a network-based transfer. - -The Forklift project, a key component of {project-short}, includes a specialized volume populator named `vsphere-xcopy-volume-populator` that directly interacts with {vmw}'s VAAI. This allows {project-short} to trigger the high-speed, array-level data copy operation for supported storage systems. - -[IMPORTANT] -==== -The storage arrays must be the ones specified above. Otherwise, XCOPY performs a fallback network disk copy on the ESXi. Although a fallback network disk copy on the ESXi is usually considerably faster than a standard migration using a VDDK image over the network, it is not as quick as a properly configured storage copy offload migration. -==== - -[id="storage-copy-offload-works-supported-providers_{context}"] -== Supported storage providers - -The following storage providers support storage copy offload: - -* Hitachi Vantara -* NetApp ONTAP -* Pure Storage FlashArray -* Dell PowerMax -* Dell PowerFlex -* Dell PowerStore -* HPE 3PAR -* HPE Primera -* Infinidat Infinibox -* IBM Flashsystem - diff --git a/documentation/modules/compatibility-guidelines-toc-sections.adoc b/documentation/modules/compatibility-guidelines-toc-sections.adoc new file mode 100644 index 00000000000..c7184ef4e10 --- /dev/null +++ b/documentation/modules/compatibility-guidelines-toc-sections.adoc @@ -0,0 +1,4 @@ += OpenShift Operator Life Cycles + + +For more information about the software maintenance Life Cycle classifications for Operators shipped by Red Hat for use with OpenShift Container Platform, see link:https://access.redhat.com/support/policy/updates/openshift_operators#platform-agnostic[OpenShift Operator Life Cycles]. diff --git a/documentation/modules/compatibility-guidelines.adoc b/documentation/modules/compatibility-guidelines.adoc index 84e843a7669..e476d879b71 100644 --- a/documentation/modules/compatibility-guidelines.adoc +++ b/documentation/modules/compatibility-guidelines.adoc @@ -31,6 +31,3 @@ However, migrations from {rhv-short} 4.3.11 were tested with {project-short} 2.3 ==== [id="openshift-operator-life-cycles"] -== OpenShift Operator Life Cycles - -For more information about the software maintenance Life Cycle classifications for Operators shipped by Red Hat for use with OpenShift Container Platform, see link:https://access.redhat.com/support/policy/updates/openshift_operators#platform-agnostic[OpenShift Operator Life Cycles]. diff --git a/documentation/modules/con_copy-methods-sco-toc-sections.adoc b/documentation/modules/con_copy-methods-sco-toc-sections.adoc new file mode 100644 index 00000000000..e95640e635a --- /dev/null +++ b/documentation/modules/con_copy-methods-sco-toc-sections.adoc @@ -0,0 +1,10 @@ += Advantages of the SSH method + + +The SSH method offers you the following advantages: + +- No VIB installation: Does not require custom VIB deployment on ESXi hosts +- Standard SSH: Uses the standard ESXi SSH service with no custom components +- Security: Uses secure key-based authentication with command restrictions +- Compatibility: Works with any ESXi version that supports SSH +- Flexibility: Easier to troubleshoot and monitor SSH connections diff --git a/documentation/modules/con_copy-methods-sco.adoc b/documentation/modules/con_copy-methods-sco.adoc index 249b82530e7..17accc5f349 100644 --- a/documentation/modules/con_copy-methods-sco.adoc +++ b/documentation/modules/con_copy-methods-sco.adoc @@ -12,13 +12,3 @@ You can use either of the following two cloning (copying) methods to run storage vSphere Installation on Bundle (VIB) is the default method. This method uses a custom VIB installed on ESXi hosts to expose `vmkfstools` operations via the vSphere API. SSH is the recommended method. This method uses SSH to directly run `vmkfstools` commands on ESXi hosts. This method is useful when VIB installation is not possible and for the advantages that follow. - -== Advantages of the SSH method - -The SSH method offers you the following advantages: - -- No VIB installation: Does not require custom VIB deployment on ESXi hosts -- Standard SSH: Uses the standard ESXi SSH service with no custom components -- Security: Uses secure key-based authentication with command restrictions -- Compatibility: Works with any ESXi version that supports SSH -- Flexibility: Easier to troubleshoot and monitor SSH connections diff --git a/documentation/modules/con_troubleshooting-storage-copy-offload-toc-sections.adoc b/documentation/modules/con_troubleshooting-storage-copy-offload-toc-sections.adoc new file mode 100644 index 00000000000..914b6f03b62 --- /dev/null +++ b/documentation/modules/con_troubleshooting-storage-copy-offload-toc-sections.adoc @@ -0,0 +1,91 @@ += vSphere-ESXi connectivity issues + + +Remote ESXi connection fails with a SOAP error:: ++ +*Description*: Sometimes a remote ESXi execution fails, returning a SOAP error with no apparent root cause message. ++ +*Explanation*: Because vSphere invokes some SOAP/REST endpoints on the ESXi, a connection can fail because of standard error reasons that vanish after the next try. ++ +*Solution*: If the populator fails, the migration can be restarted. Try to restart or retry the populator, or restart the migration. + +VIB issues returned with a CLI error:: ++ +*Description*: {project-first} returns the following error: ++ +[source,terminal] +---- +CLI Fault: The object or item referred to could not be found. The object or item referred to could not be found. +---- ++ +*Explanation*: If the VIB is installed, but `/etc/init.d/hostd` did not restart, then the `vmkfstools` namespace in `esxcli` is either not updated or does not exist. If that namespace does not exist, it means that this is the first usage, probably right after the first use. ++ +*Solution*: Use SSH to log in to the ESXi and run `/etc/init.d/hostd restart`. Wait for a few seconds until the ESXi renews the connection with vSphere. + +[id=sco-ssh-issues_{context}] +== SSH error messages + +Manual SSH key connection errors:: ++ +*Description*: {project-short} returns one of the following errors: `Manual SSH key configuration required`, `Failed to connect via SSH`, or `SSH connection timeout`. ++ +*Explanation*: The SSH connection is not running on the ESXi host for one of the following reasons: + +** The SSH is disabled. ++ +*Solution*: Manually enable an SSH connection on the ESXi host by using the commands in {mtv-mig}assembly_planning-migration-vmware_mtv#proc_storage-copy-offload-manual-ssh-set-up_vmware[Setting up storage copy offload using manually generated SSH keys]. + +** There is a problem with the network connectivity. ++ +*Solution*: Verify that the ESXi management network is accessible from the migration pods. + +** Timeout issue (least likely issue) ++ +*Solution*: Increase the value of `SSH_TIMEOUT_SECONDS` in the provider `Secret`: ++ +... Edit the provider Secret: ++ +[source,terminal] +---- +$ oc edit secret -n openshift-mtv +---- ++ +... Add or update the `SSH_TIMEOUT_SECONDS` field with a higher value (for example, `300` for 5 minutes). ++ +... Save and close the editor. ++ +Verification steps for the preceding solutions: ++ +** To verify that the SSH service is running on an ESXi host, run the following command: ++ +[source,terminal] +---- +$ vim-cmd hostsvc/get_ssh_status +---- ++ +** To manually test SSH connectivity from a migration pod, run the following command: ++ +[source,terminal] +---- +$ ssh -i /path/to/ root@ +---- + +[id=sco-netapp-issues_{context}] +== NetApp Error + +*Description*: {project-short} returns the following error: + +`Cannot derive SVM to use; please specify SVM in config file` + +*Explanation*: ONTAP is not configured correctly. + +*Solution*: Configure your default ONTAP Storage Virtual Machine (SVM) by running the following commands: + +. Show the current configuration for the SVM by running the following command on the ONTAP server: ++ +[source,terminal] +---- +$ vserver show -vserver ${NAME_OF_SVM} +---- + +. Set a management interface for the SVM and enter its `hostname` in the `STORAGE_HOSTNAME` by following the instructions in the NetApp Knowledge Base article, link: https://kb.netapp.com/Cloud/Astra/Trident/Trident_fails_to_access_ONTAP_on_SVM_level_and_on_Cluster_level[Trident fails to access ONTAP on SVM level and on Cluster level]. The link requires you to log in. diff --git a/documentation/modules/con_troubleshooting-storage-copy-offload.adoc b/documentation/modules/con_troubleshooting-storage-copy-offload.adoc index 14223ca30e8..f5d7b2e9755 100644 --- a/documentation/modules/con_troubleshooting-storage-copy-offload.adoc +++ b/documentation/modules/con_troubleshooting-storage-copy-offload.adoc @@ -9,93 +9,3 @@ This section describes problems that are unique to storage copy offload and how you can resolve them. [id=sco-vsphere-esxi-connectivity_{context}] -== vSphere-ESXi connectivity issues - -Remote ESXi connection fails with a SOAP error:: -+ -*Description*: Sometimes a remote ESXi execution fails, returning a SOAP error with no apparent root cause message. -+ -*Explanation*: Because vSphere invokes some SOAP/REST endpoints on the ESXi, a connection can fail because of standard error reasons that vanish after the next try. -+ -*Solution*: If the populator fails, the migration can be restarted. Try to restart or retry the populator, or restart the migration. - -VIB issues returned with a CLI error:: -+ -*Description*: {project-first} returns the following error: -+ -[source,terminal] ----- -CLI Fault: The object or item referred to could not be found. The object or item referred to could not be found. ----- -+ -*Explanation*: If the VIB is installed, but `/etc/init.d/hostd` did not restart, then the `vmkfstools` namespace in `esxcli` is either not updated or does not exist. If that namespace does not exist, it means that this is the first usage, probably right after the first use. -+ -*Solution*: Use SSH to log in to the ESXi and run `/etc/init.d/hostd restart`. Wait for a few seconds until the ESXi renews the connection with vSphere. - -[id=sco-ssh-issues_{context}] -== SSH error messages - -Manual SSH key connection errors:: -+ -*Description*: {project-short} returns one of the following errors: `Manual SSH key configuration required`, `Failed to connect via SSH`, or `SSH connection timeout`. -+ -*Explanation*: The SSH connection is not running on the ESXi host for one of the following reasons: - -** The SSH is disabled. -+ -*Solution*: Manually enable an SSH connection on the ESXi host by using the commands in {mtv-mig}assembly_planning-migration-vmware_mtv#proc_storage-copy-offload-manual-ssh-set-up_vmware[Setting up storage copy offload using manually generated SSH keys]. - -** There is a problem with the network connectivity. -+ -*Solution*: Verify that the ESXi management network is accessible from the migration pods. - -** Timeout issue (least likely issue) -+ -*Solution*: Increase the value of `SSH_TIMEOUT_SECONDS` in the provider `Secret`: -+ -... Edit the provider Secret: -+ -[source,terminal] ----- -$ oc edit secret -n openshift-mtv ----- -+ -... Add or update the `SSH_TIMEOUT_SECONDS` field with a higher value (for example, `300` for 5 minutes). -+ -... Save and close the editor. -+ -Verification steps for the preceding solutions: -+ -** To verify that the SSH service is running on an ESXi host, run the following command: -+ -[source,terminal] ----- -$ vim-cmd hostsvc/get_ssh_status ----- -+ -** To manually test SSH connectivity from a migration pod, run the following command: -+ -[source,terminal] ----- -$ ssh -i /path/to/ root@ ----- - -[id=sco-netapp-issues_{context}] -== NetApp Error - -*Description*: {project-short} returns the following error: - -`Cannot derive SVM to use; please specify SVM in config file` - -*Explanation*: ONTAP is not configured correctly. - -*Solution*: Configure your default ONTAP Storage Virtual Machine (SVM) by running the following commands: - -. Show the current configuration for the SVM by running the following command on the ONTAP server: -+ -[source,terminal] ----- -$ vserver show -vserver ${NAME_OF_SVM} ----- - -. Set a management interface for the SVM and enter its `hostname` in the `STORAGE_HOSTNAME` by following the instructions in the NetApp Knowledge Base article, link: https://kb.netapp.com/Cloud/Astra/Trident/Trident_fails_to_access_ONTAP_on_SVM_level_and_on_Cluster_level[Trident fails to access ONTAP on SVM level and on Cluster level]. The link requires you to log in. \ No newline at end of file diff --git a/documentation/modules/mtv-aio-buffer-toc-sections.adoc b/documentation/modules/mtv-aio-buffer-toc-sections.adoc new file mode 100644 index 00000000000..16f4563b2f2 --- /dev/null +++ b/documentation/modules/mtv-aio-buffer-toc-sections.adoc @@ -0,0 +1,22 @@ += Key findings + + +* The best migration performance was achieved by migrating multiple (10) virtual machines (VMs) on a single ESXi host with the following values: +** `VixDiskLib.nfcAio.Session.BufSizeIn64KB=16` +** `vixDiskLib.nfcAio.Session.BufCount=4` + +* The following improvements were noted when using AIO buffer settings (asynchronous buffer counts): +** Migration time was reduced by *31.1%*, from 0:24:32 to 0:16:54. +** Read rate was increased from 347.83 MB/s to 504.93 MB/s. + +* There was no significant improvement observed when using AIO buffer settings with a single VM. + +* There was no significant improvement observed when using AIO buffer settings with multiple VMs from multiple hosts. + +[id="mtv-aio-buffer-key-requirements_{context}"] +== Key requirements for support for AIO sizes and buffer counts + +Support is based upon tests performed using the following versions: + +* vSphere 7.0.3 +* VDDK 7.0.3 diff --git a/documentation/modules/mtv-esxi-performance-toc-sections.adoc b/documentation/modules/mtv-esxi-performance-toc-sections.adoc new file mode 100644 index 00000000000..ff9f64537fa --- /dev/null +++ b/documentation/modules/mtv-esxi-performance-toc-sections.adoc @@ -0,0 +1,110 @@ += Single ESXi host performance + + +Test migration by using the same ESXi host. + +In each iteration, the total VMs increase to display the impact of concurrent migration on the duration. + +The results show that migration time is linear when increasing the total VMs (50 GiB disk, Utilization 70%). + +The optimal number of VMs per ESXi is 10. + +.Single ESXi host tests +[width="100%",cols="45%,9%,9%,13%,12%,12%",options="header",] +|=== +| Test Case Description +| MTV +| VDDK +| max_vm inflight +| Migration Type +| Total Duration + + +|Cold migration, 10 VMs, Single ESXi, Private Network +(non-management network) +|2.6 +|7.0.3 +|100 +|cold +|0:21:39 + +|cold migration, 20 VMs, Single ESXi, Private Network +|2.6 +|7.0.3 +|100 +|cold +|0:41:16 + +|Cold migration, 30 VMs, Single ESXi, Private Network +|2.6 +|7.0.3 +|100 +|cold +|1:00:59 + +|Cold migration, 40 VMs, Single ESXi, Private Network +|2.6 +|7.0.3 +|100 +|cold +|1:23:02 + +|Cold migration, 50 VMs, Single ESXi, Private Network +|2.6 +|7.0.3 +|100 +|cold +|1:46:24 + +|Cold migration, 80 VMs, Single ESXi, Private Network +|2.6 +|7.0.3 +|100 +|cold +|2:42:49 + +|Cold migration, 100 VMs, Single ESXi, Private Network +|2.6 +|7.0.3 +|100 +|cold +|3:25:15 +|=== + +[id="mtv-multiple-esxi-host-performance_{context}"] +== Multiple ESXi hosts and a single data store + +In each iteration, the number of ESXi hosts was increased, to show that increasing the number of ESXi hosts improves the migration time (50 GiB disk, Utilization 70%). + +.Multiple ESXi hosts and single data store +[width="100%",cols="45%,9%,9%,13%,12%,12%",options="header",] +|=== +|Test Case Description +|MTV +|VDDK +|max_vm inflight +|Migration Type +|Total Duration + +|Cold migration, 100 VMs, Single ESXi, Private Network +(non-management network) +|2.6 +|7.0.3 +|100 +|cold +|3:25:15 + +|Cold migration, 100 VMs, 4 ESXs (25 VMs per ESX), Private Network +|2.6 +|7.0.3 +|100 +|cold +|1:22:27 + +|Cold migration, 100 VMs, 5 ESXs (20 VMs per ESX), Private Network, 1 Data Store +|2.6 +|7.0.3 +|100 +|cold +|1:04:57 +|=== diff --git a/documentation/modules/mtv-overview-page-toc-sections.adoc b/documentation/modules/mtv-overview-page-toc-sections.adoc new file mode 100644 index 00000000000..decf5e59335 --- /dev/null +++ b/documentation/modules/mtv-overview-page-toc-sections.adoc @@ -0,0 +1,103 @@ += Overview tab + + +The *Overview* tab is to help you quickly create providers and find information about the whole system: + +* In the upper pane, is the *Welcome* section, which includes buttons that let you open the *Create provider* UI for each vendor ({vmw}, Open Virtual Appliance, OpenStack, {rhv-full}, and {virt}). You can close this section by clicking the {kebab} in the upper-right corner and selecting *Hide from view*. You can reopen it by clicking *Show the welcome card* in the upper-right corner. + +* In the center-left pane is a "donut" chart named *Virtual machines*. This chart shows the number of running, failed, and successful virtual machine migrations that {project-short} ran for the time interval that you select. You can choose a different interval by clicking the list in the upper-right corner of the pane. You can select a different interval by clicking the list. The options are: Last 24 hours, Last 10 days, Last 31 days, and All. By clicking on each division of the chart, you can navigate to the *History* tab for information about the migrations. ++ +[NOTE] +==== +Data for this chart includes only the most recent run of a migration plan that was modified due to a failure. For example, if a plan with 3 VMs fails 4 times, then this chart shows that 3 VMs failed, not 12. +==== + +* In the center-right pane is an area chart named *Migration history*. This chart shows the number of migrations that succeeded, failed, or were running during the interval shown in the title of the chart. You can choose a different interval by clicking the {kebab} in the upper-right corner of the pane. The options are: Last 24 hours, Last 10 days, and Last 31 days. By clicking on each division of the chart, you can navigate to the *History* tab for information about the migrations. + +* In the lower-left pane is a "donut" chart named *Migration plans*. This chart shows the current number of migration plans grouped by their status. This includes plans that were not started, cannot be started, are incomplete, archived, paused, or have an unknown status. By clicking the *Show all plans* link, you can quickly navigate to the *Migration plans* page. ++ +[NOTE] +==== +Since a single migration might involve many virtual machines, the number of migrations performed using {project-short} might vary significantly from the number of migrated virtual machines. +==== + +* In the lower-right pane is a table named *{project-short} health*. This table lists all of the {project-short} pods. The most important one, `forklift-controller`, is first. The remaining pods are listed in alphabetical order. The *View all* link opens the *Health* tab. The status and creation time of each pod are listed. You can also see a link to the logs of each pod. + +[id="overview-yaml-tab_{context}"] +== YAML tab + +The *YAML* tab displays the `ForkliftController` custom resource (CR) that defines the operation of the {project-short} Operator. You can modify the CR in this tab. + +[id="overview-health-tab_{context}"] +== Health tab + +The *Health* tab has two panes: + +* In the upper pane, there is a table named *Health*. It lists all the {project-short} pods. The most important one, `forklift-controller`, is first. The remaining pods are listed in alphabetical order. For each pod, the status, and creation time of the pod are listed, and there is a link to the logs of the pod. + +* In the lower pane, there is a table named *Conditions*. It lists the following possible types (states) of the {project-short} Operator, the status of the type, the last time the condition was updated, the reason for the update, and a message about the condition. + +[id="overview-history-tab_{context}"] +== History tab + +The *History* tab displays information about migrations. + +* In the upper-left of the page, there is a filter that you can use to display only migrations of a certain status, for example, *Succeeded*. + +* To the right of the filter is the *Group by plan* toggle switch, which lets you display either all migrations or view only the most recent migration run per plan within the specified time range. + +[id="overview-settings-tab_{context}"] +== Settings tab + +The table that follows describes the settings that are visible in the *Settings* tab, their default values, and other possible values that can be set or chosen, if needed. + +[cols="1,1,1,1",options="header"] +.{project-short} settings +|=== +|Setting |Description |Default value |Additional values + +|Maximum concurrent VM migrations +a|Varies with provider as follows: + +* For all migrations except OVA or VMware migrations: The maximum number of disks that {project-short} can transfer simultaneously. +* For OVA migrations: The maximum number of VMs that {project-short} can migrate simultaneously. +* For VMware migrations, the setting has the following meanings: +** Cold migration: + +*** To local {virt}: VMs for each ESXi host that can migrate simultaneously. +*** To remote {virt}: Disks for each ESXi host that can migrate simultaneously. +** Warm migration: Disks for each ESXi host that can migrate simultaneously. ++ +See xref:ref_max-concurrent-vms_{context}[Configuring the controller_max_vm_inflight parameter] for a detailed explanation of this setting. +|20. +|Adjustable by either using the *+* and *-* keys to set a different value or by clicking the textbox and entering a new value. +|Controller main container CPU limit +|The CPU limit that is allocated to the main controller container, in milliCPUs (m). +|500 m. +|Adjustable by selecting another value from the list. Options: 200 m, 500 m, 2000 m, 8000 m. + +|Controller main container memory limit +|The memory limit that is allocated to the main controller container in mebibytes (Mi). +|800 Mi. +|Adjustable by selecting another value from the list. Options: 200 Mi, 800 Mi, 2000 Mi, 8000 Mi. + +|Controller inventory container memory limit +|The memory limit that is allocated to the inventory controller container in mebibytes (Mi). +|1000 Mi. +|Adjustable by selecting another value from the list. Options: 400 Mi, 1000 Mi, 2000 Mi, 8000 Mi. + +|Precopy internal (minutes) +|The interval in minutes at which a new snapshot is requested before initiating a warm migration. +|60 minutes. +|Adjustable by selecting another value from the list. Options: 5 minutes, 30 minutes, 60 minutes, 120 minutes. + +|Snapshot polling interval +|The interval in seconds between which the system checks the status of snapshot creation or removal during a warm migration. +|10 seconds. +|Adjustable by choosing another value from the list. Options: 1 second, 5 seconds, 10 seconds, 60 seconds. + +|Controller transfer network +|The `NetworkAttachmentDefinition` used for data transmission. +|Default transfer network +|Adjustable by choosing another value from the list. +|=== diff --git a/documentation/modules/mtv-overview-page.adoc b/documentation/modules/mtv-overview-page.adoc index 030bfc4f0f7..6bed6ff197d 100644 --- a/documentation/modules/mtv-overview-page.adoc +++ b/documentation/modules/mtv-overview-page.adoc @@ -20,105 +20,3 @@ The *Overview* page has 3 tabs: * Settings [id="overview-tab_{context}"] -== Overview tab - -The *Overview* tab is to help you quickly create providers and find information about the whole system: - -* In the upper pane, is the *Welcome* section, which includes buttons that let you open the *Create provider* UI for each vendor ({vmw}, Open Virtual Appliance, OpenStack, {rhv-full}, and {virt}). You can close this section by clicking the {kebab} in the upper-right corner and selecting *Hide from view*. You can reopen it by clicking *Show the welcome card* in the upper-right corner. - -* In the center-left pane is a "donut" chart named *Virtual machines*. This chart shows the number of running, failed, and successful virtual machine migrations that {project-short} ran for the time interval that you select. You can choose a different interval by clicking the list in the upper-right corner of the pane. You can select a different interval by clicking the list. The options are: Last 24 hours, Last 10 days, Last 31 days, and All. By clicking on each division of the chart, you can navigate to the *History* tab for information about the migrations. -+ -[NOTE] -==== -Data for this chart includes only the most recent run of a migration plan that was modified due to a failure. For example, if a plan with 3 VMs fails 4 times, then this chart shows that 3 VMs failed, not 12. -==== - -* In the center-right pane is an area chart named *Migration history*. This chart shows the number of migrations that succeeded, failed, or were running during the interval shown in the title of the chart. You can choose a different interval by clicking the {kebab} in the upper-right corner of the pane. The options are: Last 24 hours, Last 10 days, and Last 31 days. By clicking on each division of the chart, you can navigate to the *History* tab for information about the migrations. - -* In the lower-left pane is a "donut" chart named *Migration plans*. This chart shows the current number of migration plans grouped by their status. This includes plans that were not started, cannot be started, are incomplete, archived, paused, or have an unknown status. By clicking the *Show all plans* link, you can quickly navigate to the *Migration plans* page. -+ -[NOTE] -==== -Since a single migration might involve many virtual machines, the number of migrations performed using {project-short} might vary significantly from the number of migrated virtual machines. -==== - -* In the lower-right pane is a table named *{project-short} health*. This table lists all of the {project-short} pods. The most important one, `forklift-controller`, is first. The remaining pods are listed in alphabetical order. The *View all* link opens the *Health* tab. The status and creation time of each pod are listed. You can also see a link to the logs of each pod. - -[id="overview-yaml-tab_{context}"] -== YAML tab - -The *YAML* tab displays the `ForkliftController` custom resource (CR) that defines the operation of the {project-short} Operator. You can modify the CR in this tab. - -[id="overview-health-tab_{context}"] -== Health tab - -The *Health* tab has two panes: - -* In the upper pane, there is a table named *Health*. It lists all the {project-short} pods. The most important one, `forklift-controller`, is first. The remaining pods are listed in alphabetical order. For each pod, the status, and creation time of the pod are listed, and there is a link to the logs of the pod. - -* In the lower pane, there is a table named *Conditions*. It lists the following possible types (states) of the {project-short} Operator, the status of the type, the last time the condition was updated, the reason for the update, and a message about the condition. - -[id="overview-history-tab_{context}"] -== History tab - -The *History* tab displays information about migrations. - -* In the upper-left of the page, there is a filter that you can use to display only migrations of a certain status, for example, *Succeeded*. - -* To the right of the filter is the *Group by plan* toggle switch, which lets you display either all migrations or view only the most recent migration run per plan within the specified time range. - -[id="overview-settings-tab_{context}"] -== Settings tab - -The table that follows describes the settings that are visible in the *Settings* tab, their default values, and other possible values that can be set or chosen, if needed. - -[cols="1,1,1,1",options="header"] -.{project-short} settings -|=== -|Setting |Description |Default value |Additional values - -|Maximum concurrent VM migrations -a|Varies with provider as follows: - -* For all migrations except OVA or VMware migrations: The maximum number of disks that {project-short} can transfer simultaneously. -* For OVA migrations: The maximum number of VMs that {project-short} can migrate simultaneously. -* For VMware migrations, the setting has the following meanings: -** Cold migration: - -*** To local {virt}: VMs for each ESXi host that can migrate simultaneously. -*** To remote {virt}: Disks for each ESXi host that can migrate simultaneously. -** Warm migration: Disks for each ESXi host that can migrate simultaneously. -+ -See xref:ref_max-concurrent-vms_{context}[Configuring the controller_max_vm_inflight parameter] for a detailed explanation of this setting. -|20. -|Adjustable by either using the *+* and *-* keys to set a different value or by clicking the textbox and entering a new value. -|Controller main container CPU limit -|The CPU limit that is allocated to the main controller container, in milliCPUs (m). -|500 m. -|Adjustable by selecting another value from the list. Options: 200 m, 500 m, 2000 m, 8000 m. - -|Controller main container memory limit -|The memory limit that is allocated to the main controller container in mebibytes (Mi). -|800 Mi. -|Adjustable by selecting another value from the list. Options: 200 Mi, 800 Mi, 2000 Mi, 8000 Mi. - -|Controller inventory container memory limit -|The memory limit that is allocated to the inventory controller container in mebibytes (Mi). -|1000 Mi. -|Adjustable by selecting another value from the list. Options: 400 Mi, 1000 Mi, 2000 Mi, 8000 Mi. - -|Precopy internal (minutes) -|The interval in minutes at which a new snapshot is requested before initiating a warm migration. -|60 minutes. -|Adjustable by selecting another value from the list. Options: 5 minutes, 30 minutes, 60 minutes, 120 minutes. - -|Snapshot polling interval -|The interval in seconds between which the system checks the status of snapshot creation or removal during a warm migration. -|10 seconds. -|Adjustable by choosing another value from the list. Options: 1 second, 5 seconds, 10 seconds, 60 seconds. - -|Controller transfer network -|The `NetworkAttachmentDefinition` used for data transmission. -|Default transfer network -|Adjustable by choosing another value from the list. -|=== diff --git a/documentation/modules/mtv-resources-and-services-toc-sections.adoc b/documentation/modules/mtv-resources-and-services-toc-sections.adoc new file mode 100644 index 00000000000..d583b0d9998 --- /dev/null +++ b/documentation/modules/mtv-resources-and-services-toc-sections.adoc @@ -0,0 +1,28 @@ += {project-short} custom resources + + +* `Provider` CR stores attributes that enable {project-short} to connect to and interact with the source and target providers. +* `NetworkMapping` CR maps the networks of the source and target providers. +* `StorageMapping` CR maps the storage of the source and target providers. +* `Plan` CR contains a list of VMs with the same migration parameters and associated network and storage mappings. +* `Migration` CR runs a migration plan. ++ +Only one `Migration` CR per migration plan can run at a given time. You can create multiple `Migration` CRs for a single `Plan` CR. + +== {project-short} services + +* The `Inventory` service performs the following actions: +** Connects to the source and target providers. +** Maintains a local inventory for mappings and plans. +** Stores VM configurations. +** Runs the `Validation` service if a VM configuration change is detected. + +* The `Validation` service checks the suitability of a VM for migration by applying rules. +* The `Migration Controller` service orchestrates migrations. ++ +When you create a migration plan, the `Migration Controller` service validates the plan and adds a status label. If the plan fails validation, the plan status is `Not ready` and the plan cannot be used to perform a migration. If the plan passes validation, the plan status is `Ready` and it can be used to perform a migration. After a successful migration, the `Migration Controller` service changes the plan status to `Completed`. + +* The `Populator Controller` service orchestrates disk transfers using Volume Populators. + +* The `Kubevirt Controller` and `Containerized Data Import (CDI) Controller` services handle most technical operations. + diff --git a/documentation/modules/mtv-resources-and-services.adoc b/documentation/modules/mtv-resources-and-services.adoc index 79467648b0f..b8eefd0525b 100644 --- a/documentation/modules/mtv-resources-and-services.adoc +++ b/documentation/modules/mtv-resources-and-services.adoc @@ -8,31 +8,3 @@ [role="_abstract"] The {operator-name} is provided as a {ocp} Operator. It creates and manages the following custom resources (CRs) and services. - -== {project-short} custom resources - -* `Provider` CR stores attributes that enable {project-short} to connect to and interact with the source and target providers. -* `NetworkMapping` CR maps the networks of the source and target providers. -* `StorageMapping` CR maps the storage of the source and target providers. -* `Plan` CR contains a list of VMs with the same migration parameters and associated network and storage mappings. -* `Migration` CR runs a migration plan. -+ -Only one `Migration` CR per migration plan can run at a given time. You can create multiple `Migration` CRs for a single `Plan` CR. - -== {project-short} services - -* The `Inventory` service performs the following actions: -** Connects to the source and target providers. -** Maintains a local inventory for mappings and plans. -** Stores VM configurations. -** Runs the `Validation` service if a VM configuration change is detected. - -* The `Validation` service checks the suitability of a VM for migration by applying rules. -* The `Migration Controller` service orchestrates migrations. -+ -When you create a migration plan, the `Migration Controller` service validates the plan and adds a status label. If the plan fails validation, the plan status is `Not ready` and the plan cannot be used to perform a migration. If the plan passes validation, the plan status is `Ready` and it can be used to perform a migration. After a successful migration, the `Migration Controller` service changes the plan status to `Completed`. - -* The `Populator Controller` service orchestrates disk transfers using Volume Populators. - -* The `Kubevirt Controller` and `Containerized Data Import (CDI) Controller` services handle most technical operations. - diff --git a/documentation/modules/mtv-shared-disks-workarounds-toc-sections.adoc b/documentation/modules/mtv-shared-disks-workarounds-toc-sections.adoc new file mode 100644 index 00000000000..d50c5b71339 --- /dev/null +++ b/documentation/modules/mtv-shared-disks-workarounds-toc-sections.adoc @@ -0,0 +1,27 @@ += Duplicate a shared disk + + +In the figure that follows, VMs 2 and 3 are migrated with the shared disks in the first plan, and VM 1 is migrated in the second plan. This eliminates the cyclic dependencies, but there is a disadvantage to this workaround: it duplicates shared disk 3. The solution is to remove the duplicated PV and migrate VM 1 again. + +.Duplicated shared disk +image::cyclic_workaround1.png[Duplicate a shared disk] + +Advantage: The source VMs are not affected. + +Disadvantage: One shared disk gets transferred twice, so you need to manually delete the duplicate disk and reconnect VM 3 to shared disk 3 in Red Hat OpenShift after the migration. + +[id="remove-shared-link_{context}"] +== "Remove" a shared disk + +The figure that follows shows an alternative solution: Remove the link to one of the shared disks from one source VM. Doing this breaks the cyclic dependencies. Note that in the current {vmw} UI, removing the link is referred to as "removing" the disk. + +."Removed" shared disk +image::draft_workaround2.png[Remove a shared disk] + +In this case, VM 2 and 3 are migrated with the shared disks in the first plan, but the link between VM 3 and shared disk 3 is removed. As before, VM 1 is migrated in the second plan. + +Doing this breaks the cyclic dependencies, but this workaround has a drawback: VM 3 is disconnected from shared disk 3 and remains disconnected after the migration. The solution is to manually reattach shared disk 3 to VM 3 after the migration finishes. + +Advantage: No disks are duplicated. + +Disadvantage: You need to modify VM 3 by removing its link to shared disk 3 before the migration, and you need to manually reconnect VM 3 to shared disk 3 in {ocp} after the migration. diff --git a/documentation/modules/mtv-shared-disks-workarounds.adoc b/documentation/modules/mtv-shared-disks-workarounds.adoc index 89ee189e76d..4dd136f99ae 100644 --- a/documentation/modules/mtv-shared-disks-workarounds.adoc +++ b/documentation/modules/mtv-shared-disks-workarounds.adoc @@ -11,31 +11,3 @@ As discussed previously, it is important to try to create 2 `Plan` CRs in which * Duplicate one of the shared disks * "Remove" one of the shared disks - -[id="duplicate-shared-disk_{context}"] -== Duplicate a shared disk - -In the figure that follows, VMs 2 and 3 are migrated with the shared disks in the first plan, and VM 1 is migrated in the second plan. This eliminates the cyclic dependencies, but there is a disadvantage to this workaround: it duplicates shared disk 3. The solution is to remove the duplicated PV and migrate VM 1 again. - -.Duplicated shared disk -image::cyclic_workaround1.png[Duplicate a shared disk] - -Advantage: The source VMs are not affected. - -Disadvantage: One shared disk gets transferred twice, so you need to manually delete the duplicate disk and reconnect VM 3 to shared disk 3 in Red Hat OpenShift after the migration. - -[id="remove-shared-link_{context}"] -== "Remove" a shared disk - -The figure that follows shows an alternative solution: Remove the link to one of the shared disks from one source VM. Doing this breaks the cyclic dependencies. Note that in the current {vmw} UI, removing the link is referred to as "removing" the disk. - -."Removed" shared disk -image::draft_workaround2.png[Remove a shared disk] - -In this case, VM 2 and 3 are migrated with the shared disks in the first plan, but the link between VM 3 and shared disk 3 is removed. As before, VM 1 is migrated in the second plan. - -Doing this breaks the cyclic dependencies, but this workaround has a drawback: VM 3 is disconnected from shared disk 3 and remains disconnected after the migration. The solution is to manually reattach shared disk 3 to VM 3 after the migration finishes. - -Advantage: No disks are duplicated. - -Disadvantage: You need to modify VM 3 by removing its link to shared disk 3 before the migration, and you need to manually reconnect VM 3 to shared disk 3 in {ocp} after the migration. diff --git a/documentation/modules/mtv-ui-toc-sections.adoc b/documentation/modules/mtv-ui-toc-sections.adoc new file mode 100644 index 00000000000..ede4d76e839 --- /dev/null +++ b/documentation/modules/mtv-ui-toc-sections.adoc @@ -0,0 +1,18 @@ += The Tips and tricks panel + + +The *Tips and tricks* panel provides contextual guidance and best practices to help you plan and execute your migrations successfully. + +You can access the panel by clicking the *Tips and tricks* link in the upper-right corner of all {project-short} pages in the web console. + +The panel includes a dropdown menu where you can select from the following topics: + +* Creating a provider +* Migrating your virtual machines +* Choosing the right migration type +* Creating a network mapping +* Creating a storage mapping +* Optimizing migration speed +* Troubleshooting + +Each topic includes explanations of key terminology and considerations, with links to {project-short} documentation, {project-short} performance recommendations, Red Hat Customer Support, and Red Hat {virt} Administration training. diff --git a/documentation/modules/mtv-ui.adoc b/documentation/modules/mtv-ui.adoc index 8c96e56d79d..ccad28e7b26 100644 --- a/documentation/modules/mtv-ui.adoc +++ b/documentation/modules/mtv-ui.adoc @@ -14,20 +14,3 @@ In the left panel, you can choose a page related to a component of the migration In pages related to components, you can click on the *Projects* list, which is in the upper-left portion of the page, and see which projects (namespaces) you are allowed to work with. [id="tips-and-tricks-panel_{context}"] -== The Tips and tricks panel - -The *Tips and tricks* panel provides contextual guidance and best practices to help you plan and execute your migrations successfully. - -You can access the panel by clicking the *Tips and tricks* link in the upper-right corner of all {project-short} pages in the web console. - -The panel includes a dropdown menu where you can select from the following topics: - -* Creating a provider -* Migrating your virtual machines -* Choosing the right migration type -* Creating a network mapping -* Creating a storage mapping -* Optimizing migration speed -* Troubleshooting - -Each topic includes explanations of key terminology and considerations, with links to {project-short} documentation, {project-short} performance recommendations, Red Hat Customer Support, and Red Hat {virt} Administration training. diff --git a/documentation/modules/network-prerequisites-toc-sections.adoc b/documentation/modules/network-prerequisites-toc-sections.adoc new file mode 100644 index 00000000000..170668ada46 --- /dev/null +++ b/documentation/modules/network-prerequisites-toc-sections.adoc @@ -0,0 +1,125 @@ += Ports + + +The firewalls must enable traffic over the following ports: + +[cols="1,1,1,1,2a",options="header"] +.Network ports required for migrating from VMware vSphere +|=== +|Port |Protocol |Source |Destination |Purpose + +|443 +|TCP +|{ocp-short} nodes +|{vmw} vCenter +|{vmw} provider inventory + +Disk transfer authentication + +|443 +|TCP +|{ocp-short} nodes +|{vmw} ESXi hosts +|Disk transfer authentication + +|902 +|TCP +|{ocp-short} nodes +|{vmw} ESXi hosts +|Disk transfer data copy +|=== + +[cols="1,1,1,1,2a",options="header"] +.Network ports required for migrating from {rhv-full} +|=== +|Port |Protocol |Source |Destination |Purpose + +|443 +|TCP +|{ocp-short} nodes +|{rhv-short} Engine +|{rhv-short} provider inventory + +Disk transfer authentication + +|54322 +|TCP +|{ocp-short} nodes +|{rhv-short} hosts +|Disk transfer data copy +|=== + +[cols="1,1,1,1,2a",options="header"] +.Network ports required for migrating from {osp} +|=== +|Port |Protocol |Source |Destination |Purpose + +|8776 +|Cinder +|{ocp-short} nodes +|{osp} hosts +|Block storage API + +|8774 +|Nova +|{ocp-short} nodes +|{osp} hosts +|Virtualization API + +|5000 +|Keystone +|{ocp-short} nodes +|{osp} hosts +|Authentication API + +|9696 +|Neutron +|{ocp-short} nodes +|{osp} hosts +|Network API + +|9292 +|Glance +|{ocp-short} nodes +|{osp} hosts +|Image service API +|=== + +[cols="1,1,1,1,2a",options="header"] +.Network ports required for migrating from Open Virtual Appliance (OVA) files +|=== +|Port |Protocol |Source |Destination |Purpose + +|2049 +|TCP +|{ocp-short} nodes +|Server containing the OVA files +|NFS service + +|111 +|TCP or UCP +|{ocp-short} nodes +|Server containing the OVA files +|RPC Portmapper, only needed for NFSv4.0 +|=== + +[cols="1,1,1,1,2a",options="header"] +.Network ports required for migrating from {virt} +|=== +|Port |Protocol |Source |Destination |Purpose + +|6443 +|API +|{ocp-short} nodes +|{virt} host +|Access API to get information from a VM's manifest + +|443 +|TCP +|{ocp-short} nodes +|{virt} host +|Download VM data using the `virtualMachineExport` resource +|=== + + + diff --git a/documentation/modules/network-prerequisites.adoc b/documentation/modules/network-prerequisites.adoc index c4e4e946a3b..a0bfc1b593b 100644 --- a/documentation/modules/network-prerequisites.adoc +++ b/documentation/modules/network-prerequisites.adoc @@ -16,127 +16,3 @@ Prerequisites:: * If you are mapping more than one source and destination network, you must create a network attachment definition for each additional destination network. For more information, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/virtualization/virtual-machines#virt-creating-network-attachment-definition[network attachment definition]. [id="ports_{context}"] -== Ports - -The firewalls must enable traffic over the following ports: - -[cols="1,1,1,1,2a",options="header"] -.Network ports required for migrating from VMware vSphere -|=== -|Port |Protocol |Source |Destination |Purpose - -|443 -|TCP -|{ocp-short} nodes -|{vmw} vCenter -|{vmw} provider inventory - -Disk transfer authentication - -|443 -|TCP -|{ocp-short} nodes -|{vmw} ESXi hosts -|Disk transfer authentication - -|902 -|TCP -|{ocp-short} nodes -|{vmw} ESXi hosts -|Disk transfer data copy -|=== - -[cols="1,1,1,1,2a",options="header"] -.Network ports required for migrating from {rhv-full} -|=== -|Port |Protocol |Source |Destination |Purpose - -|443 -|TCP -|{ocp-short} nodes -|{rhv-short} Engine -|{rhv-short} provider inventory - -Disk transfer authentication - -|54322 -|TCP -|{ocp-short} nodes -|{rhv-short} hosts -|Disk transfer data copy -|=== - -[cols="1,1,1,1,2a",options="header"] -.Network ports required for migrating from {osp} -|=== -|Port |Protocol |Source |Destination |Purpose - -|8776 -|Cinder -|{ocp-short} nodes -|{osp} hosts -|Block storage API - -|8774 -|Nova -|{ocp-short} nodes -|{osp} hosts -|Virtualization API - -|5000 -|Keystone -|{ocp-short} nodes -|{osp} hosts -|Authentication API - -|9696 -|Neutron -|{ocp-short} nodes -|{osp} hosts -|Network API - -|9292 -|Glance -|{ocp-short} nodes -|{osp} hosts -|Image service API -|=== - -[cols="1,1,1,1,2a",options="header"] -.Network ports required for migrating from Open Virtual Appliance (OVA) files -|=== -|Port |Protocol |Source |Destination |Purpose - -|2049 -|TCP -|{ocp-short} nodes -|Server containing the OVA files -|NFS service - -|111 -|TCP or UCP -|{ocp-short} nodes -|Server containing the OVA files -|RPC Portmapper, only needed for NFSv4.0 -|=== - -[cols="1,1,1,1,2a",options="header"] -.Network ports required for migrating from {virt} -|=== -|Port |Protocol |Source |Destination |Purpose - -|6443 -|API -|{ocp-short} nodes -|{virt} host -|Access API to get information from a VM's manifest - -|443 -|TCP -|{ocp-short} nodes -|{virt} host -|Download VM data using the `virtualMachineExport` resource -|=== - - - diff --git a/documentation/modules/proc_storage-copy-offload-general-ssh-set-up-toc-sections.adoc b/documentation/modules/proc_storage-copy-offload-general-ssh-set-up-toc-sections.adoc new file mode 100644 index 00000000000..c09331133ea --- /dev/null +++ b/documentation/modules/proc_storage-copy-offload-general-ssh-set-up-toc-sections.adoc @@ -0,0 +1,16 @@ += Important notes and security considerations + + +- All public keys must include command restrictions for security. +- The command path in the restrictions must match the secure script path: `/vmfs/volumes/{datastore-name}/secure-vmkfstools-wrapper.py`. +- You must install the SSH key in each ESXi host in your migration environment. +- SSH service must be enabled on all target ESXi hosts. +- To support ESXi access control, commands are restricted to `vmkfstools` operations only. + +== Security recommendations + +It is recommended to follow the following security recommendations: + +- Use separate key pairs for different environments. +- Rotate keys periodically. +- Consider using shorter-lived keys for enhanced security. diff --git a/documentation/modules/proc_storage-copy-offload-general-ssh-set-up.adoc b/documentation/modules/proc_storage-copy-offload-general-ssh-set-up.adoc index ca7bd3c4f64..044c2e81049 100644 --- a/documentation/modules/proc_storage-copy-offload-general-ssh-set-up.adoc +++ b/documentation/modules/proc_storage-copy-offload-general-ssh-set-up.adoc @@ -14,18 +14,3 @@ Although SSH keys are automatically generated when you choose to use the SSH met Procedures for both options are given in the sections that follow. [id="storage-copy-offload-general-ssh-security_{context}"] -== Important notes and security considerations - -- All public keys must include command restrictions for security. -- The command path in the restrictions must match the secure script path: `/vmfs/volumes/{datastore-name}/secure-vmkfstools-wrapper.py`. -- You must install the SSH key in each ESXi host in your migration environment. -- SSH service must be enabled on all target ESXi hosts. -- To support ESXi access control, commands are restricted to `vmkfstools` operations only. - -== Security recommendations - -It is recommended to follow the following security recommendations: - -- Use separate key pairs for different environments. -- Rotate keys periodically. -- Consider using shorter-lived keys for enhanced security. diff --git a/documentation/modules/ref_mtv-aio-buffer.adoc b/documentation/modules/ref_mtv-aio-buffer.adoc index fdfa640671a..b9128a0f6a2 100644 --- a/documentation/modules/ref_mtv-aio-buffer.adoc +++ b/documentation/modules/ref_mtv-aio-buffer.adoc @@ -19,24 +19,3 @@ Remove AIO buffer configuration before initializing warm migrations. For more de ==== [id="mtv-aio-buffer-key-findings_{context}"] -== Key findings - -* The best migration performance was achieved by migrating multiple (10) virtual machines (VMs) on a single ESXi host with the following values: -** `VixDiskLib.nfcAio.Session.BufSizeIn64KB=16` -** `vixDiskLib.nfcAio.Session.BufCount=4` - -* The following improvements were noted when using AIO buffer settings (asynchronous buffer counts): -** Migration time was reduced by *31.1%*, from 0:24:32 to 0:16:54. -** Read rate was increased from 347.83 MB/s to 504.93 MB/s. - -* There was no significant improvement observed when using AIO buffer settings with a single VM. - -* There was no significant improvement observed when using AIO buffer settings with multiple VMs from multiple hosts. - -[id="mtv-aio-buffer-key-requirements_{context}"] -== Key requirements for support for AIO sizes and buffer counts - -Support is based upon tests performed using the following versions: - -* vSphere 7.0.3 -* VDDK 7.0.3 diff --git a/documentation/modules/ref_mtv-esxi-performance.adoc b/documentation/modules/ref_mtv-esxi-performance.adoc index c77369d8381..5dc37e51332 100644 --- a/documentation/modules/ref_mtv-esxi-performance.adoc +++ b/documentation/modules/ref_mtv-esxi-performance.adoc @@ -13,6 +13,7 @@ Where possible, ensure that hosts used to perform migrations are set with BIOS p Testing showed that when transferring more than 10 VMs with both BIOS and host power management set accordingly, migrations had an increase of 15 MiB in the average datastore read rate. +<<<<<<< HEAD:documentation/modules/ref_mtv-esxi-performance.adoc *Single ESXi host performance* Test migrations by using a single ESXi host. @@ -120,4 +121,7 @@ In each iteration, the number of ESXi hosts was increased to show that increasin |100 |cold |1:04:57 -|=== \ No newline at end of file +|=== +======= +[id="mtv-single-esxi-host-performance_{context}"] +>>>>>>> a1cb644 (CQA 11th March - TOC fix):documentation/modules/mtv-esxi-performance.adoc diff --git a/documentation/modules/virt-v2v-mtv-toc-sections.adoc b/documentation/modules/virt-v2v-mtv-toc-sections.adoc new file mode 100644 index 00000000000..62450bbba88 --- /dev/null +++ b/documentation/modules/virt-v2v-mtv-toc-sections.adoc @@ -0,0 +1,49 @@ += Main functions of virt-v2v in MTV migrations + + +During migration, {project-short} uses `virt-v2v` to collect metadata about VMs, make necessary changes to VM disks, and copy the disks containing the VMs to {virt}. + +`virt-v2v` makes the following changes to VM disks to prepare them for migration: + +* Additions: + +** Injection of VirtIO drivers, for example, network or disk drivers. +** Preparation of hypervisor-specific tools or agents, for example, a QEMU guest agent installation. +** Modification of boot configuration, for example, updated boot loader or boot entries. + +* Removals: + +** Unnecessary or former hypervisor-specific files, for example, VMware tools or VirtualBox additions. +** Old network driver configurations, for example, removing VMware-specific NIC drivers. +** Configuration settings that are incompatible with the target system, for example, old boot settings. + +If you are migrating from {vmw} or from Open Virtual Appliances (OVA) files, `virt-v2v` also sets their IP addresses either during the migration or during the first reboot of the VMs after migration. +[NOTE] +==== +You can also run predefined Ansible hooks before or after a migration using {project-short}. For more information, see xref:about-hooks-for-migration-plans_mtv[About hooks for MTV migration plans]. + +These hooks do not necessarily use `virt-v2v`. +==== + +[id="customizing-removing-installing-virt-v2v_{context}"] +== Customizing, removing, and installing files + +{project-short} uses `virt-v2v` to perform additional guest customizations during the conversion, such as the following actions: + +* Customization to preserve IP addresses +* Customization to preserve drive letters + +[NOTE] +==== +For {rhel-first}-based guests, `virt-v2v` attempts to install the guest agent from the Red Hat registry. If the migration is run in a detached environment, the installation program fails, and you must use hooks or other automation to install the guest agent. +==== + +For more information, see the man reference pages: + +* link:https://libguestfs.org/virt-v2v.1.html[`virt-v2v` - Convert a guest to use KVM] +* link:https://libguestfs.org/virt-customize.1.html[`virt-customize` - Customize a virtual machine] + +[id="permissions-virt-v2v_{context}"] +== Permissions and virt-v2v + +`virt-v2v` does not require permissions or access credentials for the guest operating system itself because `virt-v2v` is not run against a running VM, but only against the disks of a VM. diff --git a/documentation/modules/virt-v2v-mtv.adoc b/documentation/modules/virt-v2v-mtv.adoc index ac659a5e00a..48ab5100b67 100644 --- a/documentation/modules/virt-v2v-mtv.adoc +++ b/documentation/modules/virt-v2v-mtv.adoc @@ -12,51 +12,3 @@ The {project-first} uses the `virt-v2v` tool to convert the disk image of a virt `virt-v2v` is included in Red Hat Enterprise Linux (RHEL) versions 7 and later. [id="main-functions-virt-v2v-mtv_{context}"] -== Main functions of virt-v2v in MTV migrations - -During migration, {project-short} uses `virt-v2v` to collect metadata about VMs, make necessary changes to VM disks, and copy the disks containing the VMs to {virt}. - -`virt-v2v` makes the following changes to VM disks to prepare them for migration: - -* Additions: - -** Injection of VirtIO drivers, for example, network or disk drivers. -** Preparation of hypervisor-specific tools or agents, for example, a QEMU guest agent installation. -** Modification of boot configuration, for example, updated boot loader or boot entries. - -* Removals: - -** Unnecessary or former hypervisor-specific files, for example, VMware tools or VirtualBox additions. -** Old network driver configurations, for example, removing VMware-specific NIC drivers. -** Configuration settings that are incompatible with the target system, for example, old boot settings. - -If you are migrating from {vmw} or from Open Virtual Appliances (OVA) files, `virt-v2v` also sets their IP addresses either during the migration or during the first reboot of the VMs after migration. -[NOTE] -==== -You can also run predefined Ansible hooks before or after a migration using {project-short}. For more information, see xref:about-hooks-for-migration-plans_mtv[About hooks for MTV migration plans]. - -These hooks do not necessarily use `virt-v2v`. -==== - -[id="customizing-removing-installing-virt-v2v_{context}"] -== Customizing, removing, and installing files - -{project-short} uses `virt-v2v` to perform additional guest customizations during the conversion, such as the following actions: - -* Customization to preserve IP addresses -* Customization to preserve drive letters - -[NOTE] -==== -For {rhel-first}-based guests, `virt-v2v` attempts to install the guest agent from the Red Hat registry. If the migration is run in a detached environment, the installation program fails, and you must use hooks or other automation to install the guest agent. -==== - -For more information, see the man reference pages: - -* link:https://libguestfs.org/virt-v2v.1.html[`virt-v2v` - Convert a guest to use KVM] -* link:https://libguestfs.org/virt-customize.1.html[`virt-customize` - Customize a virtual machine] - -[id="permissions-virt-v2v_{context}"] -== Permissions and virt-v2v - -`virt-v2v` does not require permissions or access credentials for the guest operating system itself because `virt-v2v` is not run against a running VM, but only against the disks of a VM. diff --git a/documentation/modules/vmware-prerequisites-toc-sections.adoc b/documentation/modules/vmware-prerequisites-toc-sections.adoc new file mode 100644 index 00000000000..70815f6ad95 --- /dev/null +++ b/documentation/modules/vmware-prerequisites-toc-sections.adoc @@ -0,0 +1,65 @@ += {vmw} privileges + + +The following minimal set of {vmw} privileges is required to migrate virtual machines to {virt} with the {project-first}. + +[cols="2", options="header"] +.VMware privileges +|=== +|Privilege |Description +2+|`Virtual machine.Interaction` privileges: +|`Virtual machine.Interaction.Power Off` |Allows powering off a powered-on virtual machine. This operation powers down the guest operating system. +|`Virtual machine.Interaction.Power On` |Allows powering on a powered-off virtual machine and resuming a suspended virtual machine. +|`Virtual machine.Guest operating system management by VIX API` |Allows managing a virtual machine by the {vmw} Virtual Infrastructure eXtension (VIX) API. +2+a|`Virtual machine.Provisioning` privileges: +[NOTE] +==== +All `Virtual machine.Provisioning` privileges are required. +==== +|`Virtual machine.Provisioning.Allow disk access` +|Allows opening a disk on a virtual machine for random read and write access. Used mostly for remote disk mounting. +|`Virtual machine.Provisioning.Allow file access` +|Allows operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. +|`Virtual machine.Provisioning.Allow read-only disk access` +|Allows opening a disk on a virtual machine for random read access. Used mostly for remote disk mounting. +|`Virtual machine.Provisioning.Allow virtual machine download` +|Allows read operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. +|`Virtual machine.Provisioning.Allow virtual machine files upload` +|Allows write operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. +|`Virtual machine.Provisioning.Clone template` +|Allows cloning of a template. +|`Virtual machine.Provisioning.Clone virtual machine` +|Allows cloning of an existing virtual machine and allocation of resources. +|`Virtual machine.Provisioning.Create template from virtual machine` +|Allows creation of a new template from a virtual machine. +|`Virtual machine.Provisioning.Customize guest` +|Allows customization of a virtual machine's guest operating system without moving the virtual machine. +|`Virtual machine.Provisioning.Deploy template` +|Allows deployment of a virtual machine from a template. +|`Virtual machine.Provisioning.Mark as template` +|Allows marking an existing powered-off virtual machine as a template. +|`Virtual machine.Provisioning.Mark as virtual machine` +|Allows marking an existing template as a virtual machine. +|`Virtual machine.Provisioning.Modify customization specification` +|Allows creation, modification, or deletion of customization specifications. +|`Virtual machine.Provisioning.Promote disks` +|Allows promote operations on a virtual machine's disks. +|`Virtual machine.Provisioning.Read customization specifications` +|Allows reading a customization specification. +2+|`Virtual machine.Snapshot management` privileges: +|`Virtual machine.Snapshot management.Create snapshot` |Allows creation of a snapshot from the virtual machine's current state. +|`Virtual machine.Snapshot management.Remove Snapshot` |Allows removal of a snapshot from the snapshot history. +2+|`Datastore` privileges: +|`Datastore.Browse datastore` |Allows exploring the contents of a datastore. +|`Datastore.Low level file operations` |Allows performing low-level file operations - read, write, delete, and rename - in a datastore. +2+|`Sessions` privileges: +|`Sessions.Validate session` |Allows verification of the validity of a session. +2+|`Cryptographic` privileges: +|`Cryptographic.Decrypt` |Allows decryption of an encrypted virtual machine. +|`Cryptographic.Direct access` |Allows access to encrypted resources. +|=== + +[TIP] +==== +Create a role in {vmw} with the permissions described in the preceding table and then apply this role to the *Inventory* section, as described in xref:creating-vmware-role-mtv-permissions_mtv[Creating a {vmw} role to apply {project-short} permissions]. +==== diff --git a/documentation/modules/vmware-prerequisites.adoc b/documentation/modules/vmware-prerequisites.adoc index 35ee74da831..bc15c7f5b59 100644 --- a/documentation/modules/vmware-prerequisites.adoc +++ b/documentation/modules/vmware-prerequisites.adoc @@ -45,67 +45,3 @@ In case of a power outage, data might be lost for a VM with disabled hibernation ==== [id="vmware-privileges_{context}"] -== {vmw} privileges - -The following minimal set of {vmw} privileges is required to migrate virtual machines to {virt} with the {project-first}. - -[cols="2", options="header"] -.VMware privileges -|=== -|Privilege |Description -2+|`Virtual machine.Interaction` privileges: -|`Virtual machine.Interaction.Power Off` |Allows powering off a powered-on virtual machine. This operation powers down the guest operating system. -|`Virtual machine.Interaction.Power On` |Allows powering on a powered-off virtual machine and resuming a suspended virtual machine. -|`Virtual machine.Guest operating system management by VIX API` |Allows managing a virtual machine by the {vmw} Virtual Infrastructure eXtension (VIX) API. -2+a|`Virtual machine.Provisioning` privileges: -[NOTE] -==== -All `Virtual machine.Provisioning` privileges are required. -==== -|`Virtual machine.Provisioning.Allow disk access` -|Allows opening a disk on a virtual machine for random read and write access. Used mostly for remote disk mounting. -|`Virtual machine.Provisioning.Allow file access` -|Allows operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. -|`Virtual machine.Provisioning.Allow read-only disk access` -|Allows opening a disk on a virtual machine for random read access. Used mostly for remote disk mounting. -|`Virtual machine.Provisioning.Allow virtual machine download` -|Allows read operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. -|`Virtual machine.Provisioning.Allow virtual machine files upload` -|Allows write operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. -|`Virtual machine.Provisioning.Clone template` -|Allows cloning of a template. -|`Virtual machine.Provisioning.Clone virtual machine` -|Allows cloning of an existing virtual machine and allocation of resources. -|`Virtual machine.Provisioning.Create template from virtual machine` -|Allows creation of a new template from a virtual machine. -|`Virtual machine.Provisioning.Customize guest` -|Allows customization of a virtual machine's guest operating system without moving the virtual machine. -|`Virtual machine.Provisioning.Deploy template` -|Allows deployment of a virtual machine from a template. -|`Virtual machine.Provisioning.Mark as template` -|Allows marking an existing powered-off virtual machine as a template. -|`Virtual machine.Provisioning.Mark as virtual machine` -|Allows marking an existing template as a virtual machine. -|`Virtual machine.Provisioning.Modify customization specification` -|Allows creation, modification, or deletion of customization specifications. -|`Virtual machine.Provisioning.Promote disks` -|Allows promote operations on a virtual machine's disks. -|`Virtual machine.Provisioning.Read customization specifications` -|Allows reading a customization specification. -2+|`Virtual machine.Snapshot management` privileges: -|`Virtual machine.Snapshot management.Create snapshot` |Allows creation of a snapshot from the virtual machine's current state. -|`Virtual machine.Snapshot management.Remove Snapshot` |Allows removal of a snapshot from the snapshot history. -2+|`Datastore` privileges: -|`Datastore.Browse datastore` |Allows exploring the contents of a datastore. -|`Datastore.Low level file operations` |Allows performing low-level file operations - read, write, delete, and rename - in a datastore. -2+|`Sessions` privileges: -|`Sessions.Validate session` |Allows verification of the validity of a session. -2+|`Cryptographic` privileges: -|`Cryptographic.Decrypt` |Allows decryption of an encrypted virtual machine. -|`Cryptographic.Direct access` |Allows access to encrypted resources. -|=== - -[TIP] -==== -Create a role in {vmw} with the permissions described in the preceding table and then apply this role to the *Inventory* section, as described in xref:creating-vmware-role-mtv-permissions_mtv[Creating a {vmw} role to apply {project-short} permissions]. -==== diff --git a/documentation/modules/warm-migration-stages-toc-sections.adoc b/documentation/modules/warm-migration-stages-toc-sections.adoc new file mode 100644 index 00000000000..9f8f77af300 --- /dev/null +++ b/documentation/modules/warm-migration-stages-toc-sections.adoc @@ -0,0 +1,18 @@ += Precopy stage + + +The VMs are not shut down during the precopy stage. + +The VM disks are copied incrementally by using link:https://kb.vmware.com/s/article/1020128[changed block tracking (CBT)] snapshots. The snapshots are created at one-hour intervals by default. You can change the snapshot interval by updating the `forklift-controller` deployment. + +A VM can support up to 28 CBT snapshots. If the source VM has too many CBT snapshots and the `Migration Controller` service is not able to create a new snapshot, warm migration might fail. The `Migration Controller` service deletes each snapshot when the snapshot is no longer required. + +The precopy stage runs until the cutover stage is started manually or is scheduled to start. + +== Cutover stage + +The VMs are shut down during the cutover stage and the remaining data is migrated. Data stored in RAM is not migrated. + +You can start the cutover stage manually by using the {project-short} console or you can schedule a cutover time in the `Migration` custom resource (CR). + +The duration of the cutover stage depends on how much data has changed since the last snapshot was created during the precopy stage. diff --git a/documentation/modules/warm-migration-stages.adoc b/documentation/modules/warm-migration-stages.adoc index 895f62d6b81..9bfd7b3b77d 100644 --- a/documentation/modules/warm-migration-stages.adoc +++ b/documentation/modules/warm-migration-stages.adoc @@ -9,21 +9,3 @@ [role="_abstract"] Warm migration operates in two stages: the precopy stage, where most data is copied while VMs run, and the cutover stage, where VMs are shut down to complete the migration. - -== Precopy stage - -The VMs are not shut down during the precopy stage. - -The VM disks are copied incrementally by using link:https://kb.vmware.com/s/article/1020128[changed block tracking (CBT)] snapshots. The snapshots are created at one-hour intervals by default. You can change the snapshot interval by updating the `forklift-controller` deployment. - -A VM can support up to 28 CBT snapshots. If the source VM has too many CBT snapshots and the `Migration Controller` service is not able to create a new snapshot, warm migration might fail. The `Migration Controller` service deletes each snapshot when the snapshot is no longer required. - -The precopy stage runs until the cutover stage is started manually or is scheduled to start. - -== Cutover stage - -The VMs are shut down during the cutover stage and the remaining data is migrated. Data stored in RAM is not migrated. - -You can start the cutover stage manually by using the {project-short} console or you can schedule a cutover time in the `Migration` custom resource (CR). - -The duration of the cutover stage depends on how much data has changed since the last snapshot was created during the precopy stage. From 89a5da3419f074846b5717fa098a801a65c92a68 Mon Sep 17 00:00:00 2001 From: Andy Arnold Date: Wed, 18 Mar 2026 17:08:27 +0000 Subject: [PATCH 2/2] Update ref_mtv-esxi-performance.adoc --- documentation/modules/ref_mtv-esxi-performance.adoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/documentation/modules/ref_mtv-esxi-performance.adoc b/documentation/modules/ref_mtv-esxi-performance.adoc index 5dc37e51332..660260b3287 100644 --- a/documentation/modules/ref_mtv-esxi-performance.adoc +++ b/documentation/modules/ref_mtv-esxi-performance.adoc @@ -13,7 +13,6 @@ Where possible, ensure that hosts used to perform migrations are set with BIOS p Testing showed that when transferring more than 10 VMs with both BIOS and host power management set accordingly, migrations had an increase of 15 MiB in the average datastore read rate. -<<<<<<< HEAD:documentation/modules/ref_mtv-esxi-performance.adoc *Single ESXi host performance* Test migrations by using a single ESXi host. @@ -122,6 +121,3 @@ In each iteration, the number of ESXi hosts was increased to show that increasin |cold |1:04:57 |=== -======= -[id="mtv-single-esxi-host-performance_{context}"] ->>>>>>> a1cb644 (CQA 11th March - TOC fix):documentation/modules/mtv-esxi-performance.adoc