Merge pull request #740 from RichardHoch/MTV-2945_user_guide

MTV-2945 user guide

Author: anarnold97

documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc

@@ -6,118 +6,18 @@
 [id="about-cold-warm-migration_{context}"]
 = About cold and warm migration
 
-{project-short} supports cold migration from:
+[role="_abstract"]
+{project-first} supports cold and warm migration as follows:
 
-* VMware vSphere
+{project-short} supports cold migration from these source providers:
+
+* {vmw} vSphere
 * {rhv-full} ({rhv-short})
 * {osp}
+* Open Virtual Appliances (OVAs) that were created by {vmw} vSphere
 * Remote {virt} clusters
 
-{project-short} supports warm migration from VMware vSphere and from {rhv-short}.
-
-[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.
-
-[NOTE]
-====
-include::snip_qemu-guest-agent.adoc[]
-====
-
-[id="warm-migration_{context}"]
-== Warm migration
-
-Most of the data is copied during the _precopy_ stage while the source virtual machines (VMs) are running.
-
-Then the VMs are shut down and the remaining data is copied during the _cutover_ stage.
-
-.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.
-
-[IMPORTANT]
-====
-You must enable CBT for each source VM and each VM disk.
-
-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` manifest.
-
-
-[id="warm-migration-versus-cold-migration"_{context}]
-== Advantages and disadvantages of cold and warm migrations
-
-The table that follows offers a more detailed description of the advantages and disadvantages of cold migration and warm migration. It assumes that you have installed Red Hat Enterprise Linux (RHEL) 9 on the {ocp} platform on which you installed {project-short}:
-
-[cols="1,1,1",options="header"]
-.Detailed description of advantages and disadvantages
-
-[cols="1,1,1",options="header"]
-.Advantages and disadvantages of cold and warm migrations
-|===
-|
-|*Cold migration*
-|*Warm migration*
-
-|*Duration*
-|Correlates to the amount of data on the disks. Each block is copied once.
-|Correlates to the amount of data on the disks and VM utilization. Blocks may be copied multiple times.
-
-|*Fail fast*
-|Convert and then transfer. Each VM is converted to be compatible with {ocp-short} and, if the conversion is successful, the VM is transferred. If a VM cannot be converted, the migration fails immediately.
-|Transfer and then convert. For each VM, {project-short} creates a snapshot and transfers it to {ocp}. When you start the cutover, {project-short} creates the last snapshot, transfers it, and then converts the VM.
-
-|*Tools*
-a|`virt-v2v` (Red Hat Enterprise Linux 9), used to convert virtual machines from a foreign hypervisor to run on Kernel-based Virtual Machines (KVMs).
-a|Containerized Data Importer (CDI), a persistent storage management add-on, and `virt-v2v` (Red Hat Enterprise Linux 9)
-
-|*Data transferred*
-|Approximate sum of all disks
-|Approximate sum of all disks and VM utilization
-
-|*VM downtime*
-|High: The VMs are shut down, and the disks are transferred.
-|Low: Disks are transferred in the background. The VMs are shut down during the cutover stage, and the remaining data is migrated. Data stored in RAM is not migrated.
-
-|*Parallelism*
-|Disks are transferred sequentially for each VM. For remote migration, disks are transferred in parallel.
-footnoteref:[footnote1,Remote migration: Target environment that does not have MTV installed. Migration to a remote environment using CDI.]
-|Disks are transferred in parallel by different pods.
-
-|*Connection use*
-|Keeps the connection to the Source only during the disk transfer.
-|Keeps the connection to the Source during the disk transfer, but the connection is released between snapshots.
-
-|*Tools*
-|{project-short} only.
-|{project-short} and CDI from {virt}.
-|===
-
-
-[NOTE]
-====
-The preceding table describes the situation for VMs that are running because the main benefit of warm migration is the reduced downtime, and there is no reason to initiate warm migration for VMs that are down. However, performing warm migration for VMs that are down is not the same as cold migration, even when {project-short} uses `virt-v2v` and RHEL 9. For VMs that are down, {project-short} transfers the disks using CDI, unlike in cold migration.
-====
-
-[NOTE]
-====
-When importing from VMware, there are additional factors which impact the migration speed such as limits related to ESXi, vSphere. or VDDK.
-====
-
-=== Conclusions
-
-Based on the preceding information, we can draw the following conclusions about cold migration vs. warm migration:
+{project-short} supports warm migration from these source providers:
+* {vmw} vSphere
+* {rhv-full}
 
-* The shortest downtime of VMs can be achieved by using warm migration.
-* The shortest duration for VMs with a large amount of data on a single disk can be achieved by using cold migration.
-* The shortest duration for VMs with a large amount of data that is spread evenly across multiple disks can be achieved by using warm migration.

documentation/modules/about-cold-warm-migration.adoc

@@ -6,6 +6,9 @@
 [id="about-hooks-for-migration-plans_{context}"]
 = About hooks for {project-short} migration plans
 
+[role="_abstract"]
+You can add hooks to an {project-first} migration plan to perform automated operations on a VM, either before or after you migrate it.
+
 You can add hooks to {project-first} migration plans using either the {project-short} CLI or the {project-short} user interface, which is located in the {ocp} web console.
 
 * _Pre-migration_ hooks are hooks that perform operations on a VM that is located on a provider. This prepares the VM for migration.
@@ -17,7 +20,7 @@ The default hook image for an {project-short} hook is `quay.io/kubev2v/hook-runn
 
 [id="hook-execution_{context}"]
 == Hook execution
-An Ansible playbook that is provided as part of a migration hook is mounted into the hook container as a `ConfigMap`. The hook container is run as a job on the desired cluster in the `openshift-mtv` namespace using the `ServiceAccount` you choose.
+An Ansible Playbook that is provided as part of a migration hook is mounted into the hook container as a `ConfigMap`. The hook container is run as a job on the desired cluster in the `openshift-mtv` namespace using the `ServiceAccount` you choose.
 
 When you add a hook, you must specify the namespace where the `Hook` CR is located, the name of the hook, and whether the hook is a pre-migration hook or a post-migration hook.
 
@@ -50,7 +53,7 @@ This Secret is not the same as the `Secret` CR that contains the credentials of
 . The {project-short} controller creates the `ConfigMap`, which contains:
 
 ** `workload.yml`, which contains information about the VMs.
-** `playbook.yml`, the raw string playbook you want to execute.
+** `playbook.yml`, the raw string playbook you want to run.
 ** `plan.yml`, which is the `Plan` CR.
 +
 The `ConfigMap` contains the name of the VM and instructs the playbook what to do.

documentation/modules/about-hooks-for-migration-plans.adoc

@@ -0,0 +1,13 @@
+
+:_content-type: CONCEPT
+[id="about-mtv_{context}"]
+= About the {project-full}
+
+[role="_abstract"]
+You can use the {project-first} to migrate virtual machines (VMs) from the following source providers to {virt} destination providers:
+
+* {vmw} vSphere
+* {rhv-full} ({rhv-short})
+* {osp}
+* Open Virtual Appliances (OVAs) that were created by {vmw} vSphere
+* Remote {virt} clusters

documentation/modules/about-mtv.adoc

@@ -4,9 +4,10 @@
 
 :_content-type: CONCEPT
 [id="about-network-maps_{context}"]
-= About network maps
+= About network maps in migration plans
 
-You can create network maps in {project-first} to map source networks to {virt} networks.
+[role="_abstract"]
+You can create network maps in {project-first} migration plans to map source networks to {virt} networks.
 
 There are two types of network maps: maps created for a specific migration plan and maps created for use by any migration plan.
 

documentation/modules/about-network-maps.adoc

@@ -6,6 +6,7 @@
 [id="about-rego-files_{context}"]
 = About Rego files
 
+[role="_abstract"]
 Validation rules are written in link:https://www.openpolicyagent.org/docs/latest/policy-language/[Rego], the Open Policy Agent (OPA) native query language. The rules are stored as `.rego` files in the `/usr/share/opa/policies/io/konveyor/forklift/<provider>` directory of the `Validation` pod.
 
 Each validation rule is defined in a separate `.rego` file and tests for a specific condition. If the condition evaluates as `true`, the rule adds a `{“category”, “label”, “assessment”}` hash to the `concerns`. The `concerns` content is added to the `concerns` key in the inventory record of the VM. The web console displays the content of the `concerns` key for each VM in the provider inventory.

documentation/modules/about-rego-files.adoc

@@ -4,9 +4,10 @@
 
 :_content-type: CONCEPT
 [id="about-storage-maps_{context}"]
-= About storage maps
+= About storage maps in migration plans
 
-You can create storage maps in {project-first} to map source disk storages to {virt} storage classes.
+[role="_abstract"]
+You can create storage maps in {project-first} migration plans to map source disk storages to {virt} storage classes.
 
 There are two types of storage maps: maps created for a specific migration plan and maps created for use by any migration plan.
 

documentation/modules/about-storage-maps.adoc

@@ -6,6 +6,7 @@
 [id="accessing-default-validation-rules_{context}"]
 = Checking the default validation rules
 
+[role="_abstract"]
 Before you create a custom rule, you must check the default rules of the `Validation` service to ensure that you do not create a rule that redefines an existing default value.
 
 Example: If a default rule contains the line `default valid_input = false` and you create a custom rule that contains the line `default valid_input = true`, the `Validation` service will not start.

documentation/modules/accessing-default-validation-rules.adoc

@@ -6,6 +6,7 @@
 [id="accessing-logs-cli_{context}"]
 = Accessing logs and custom resource information from the command line
 
+[role="_abstract"]
 You can access logs and information about custom resources (CRs) from the command line by using the `must-gather` tool. You must attach a `must-gather` data file to all customer cases.
 
 You can gather data for a specific namespace, a completed, failed, or canceled migration plan, or a migrated virtual machine (VM) by using the filtering options.

documentation/modules/accessing-logs-cli.adoc

@@ -6,6 +6,7 @@
 [id="accessing-logs-ui_{context}"]
 = Downloading logs and custom resource information from the web console
 
+[role="_abstract"]
 You can download logs and information about custom resources (CRs) for a completed, failed, or canceled migration plan or for migrated virtual machines (VMs) from the {ocp} web console.
 
 .Procedure