rebase

apinnick · apinnick · commit b816ad916c0f · 2021-02-09T12:43:31.000+02:00
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -1802,7 +1802,7 @@ Topics:
     File: about-migration
   - Name: Planning your migration from OpenShift Container Platform 3 to 4
     File: planning-migration-3-to-4
-  - Name: Migration tools and prerequisites
+  - Name: About the Migration Toolkit for Containers
     File: migrating-application-workloads-3-4
   - Name: Deploying the Migration Toolkit for Containers
     File: deploying-cam-3-4
@@ -1820,7 +1820,7 @@ Topics:
   Dir: migrating_4_1_4
   Distros: openshift-enterprise
   Topics:
-  - Name: Migration tools and prerequisites
+  - Name: About the Migration Toolkit for Containers
     File: migrating-application-workloads-4-1-4
   - Name: Deploying the Migration Toolkit for Containers
     File: deploying-cam-4-1-4
@@ -1836,7 +1836,7 @@ Topics:
   Dir: migrating_4_2_4
   Distros: openshift-enterprise
   Topics:
-  - Name: Migration tools and prerequisites
+  - Name: About the Migration Toolkit for Containers
     File: migrating-application-workloads-4-2-4
   - Name: Deploying the Migration Toolkit for Containers
     File: deploying-cam-4-2-4
diff --git a/migration/migrating_3_4/deploying-cam-3-4.adoc b/migration/migrating_3_4/deploying-cam-3-4.adoc
@@ -6,11 +6,13 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-You can deploy the {mtc-full} ({mtc-short}) on an {product-title} {product-version} target cluster and an {product-title} 3 source cluster by installing the {mtc-full} Operator. The {mtc-full} Operator deploys {mtc-short} on the target cluster by default.
+You can deploy the {mtc-full} ({mtc-short}) on an {product-title} {product-version} target cluster and an {product-title} 3 source cluster by installing the {mtc-full} Operator.
 
 [NOTE]
 ====
-Optional: You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on an {product-title} 3 cluster or on a remote cluster].
+{mtc-short} is installed on the target cluster by default.
+
+You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on an {product-title} 3 cluster or on a remote cluster].
 ====
 
 In a restricted environment, you can install the {mtc-full} Operator from a local mirror registry.
diff --git a/migration/migrating_3_4/migrating-application-workloads-3-4.adoc b/migration/migrating_3_4/migrating-application-workloads-3-4.adoc
@@ -1,5 +1,5 @@
 [id="migrating-application-workloads-3-4"]
-= Migration tools and prerequisites
+= About the {mtc-full}
 include::modules/common-attributes.adoc[]
 :context: migrating-3-4
 :migrating-3-4:
@@ -8,6 +8,13 @@ toc::[]
 
 You can migrate application workloads from {product-title} 3.7, 3.9, 3.10, and 3.11 to {product-title} {product-version} with the {mtc-full} ({mtc-short}). {mtc-short} enables you to control the migration and to minimize application downtime.
 
+[NOTE]
+====
+{mtc-short} is installed on the target cluster by default.
+
+You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on an {product-title} 3 cluster or on a remote cluster].
+====
+
 The {mtc-short} web console and API, based on Kubernetes custom resources, enable you to migrate stateful application workloads at the granularity of a namespace.
 
 {mtc-short} supports the file system and snapshot data copy methods for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider.
@@ -29,7 +36,8 @@ Before you begin your migration, be sure to review the information on xref:../..
 ====
 
 include::modules/migration-prerequisites.adoc[leveloffset=+1]
-include::modules/migration-understanding-cam.adoc[leveloffset=+1]
+include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
+include::modules/migration-mtc-custom-resources.adoc[leveloffset=+1]
 include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1]
 include::modules/migration-understanding-migration-hooks.adoc[leveloffset=+1]
 include::modules/migration-understanding-cpma.adoc[leveloffset=+1]
diff --git a/migration/migrating_3_4/troubleshooting-3-4.adoc b/migration/migrating_3_4/troubleshooting-3-4.adoc
@@ -31,4 +31,11 @@ include::modules/migration-rolling-back-migration-cli.adoc[leveloffset=+2]
 
 include::modules/migration-using-must-gather.adoc[leveloffset=+1]
 include::modules/migration-known-issues.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#migration-mtc-workflow_migrating-3-4[{mtc-short} workflow]
+* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#migration-mtc-custom-resources_migrating-3-4[{mtc-short} custom resources]
+
 :!migrating-3-4:
diff --git a/migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc b/migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc
@@ -1,5 +1,5 @@
 [id="migrating-application-workloads-4-1-4"]
-= Migration tools and prerequisites
+= About the {mtc-full}
 include::modules/common-attributes.adoc[]
 :context: migrating-4-1-4
 :migrating-4-1-4:
@@ -11,6 +11,8 @@ You can migrate application workloads from {product-title} 4.1 to {product-versi
 [NOTE]
 ====
 You can migrate between {product-title} clusters of the same version, for example, from 4.1 to 4.1, as long as the source and target clusters are configured correctly.
+
+{mtc-short} is installed on the target cluster by default. You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on a remote cluster].
 ====
 
 The {mtc-short} web console and API, based on Kubernetes custom resources, enable you to migrate stateful and stateless application workloads at the granularity of a namespace.
@@ -20,8 +22,8 @@ The {mtc-short} web console and API, based on Kubernetes custom resources, enabl
 You can use migration hooks to run Ansible playbooks at certain points during the migration. The hooks are added when you create a migration plan.
 
 include::modules/migration-prerequisites.adoc[leveloffset=+1]
-include::modules/migration-understanding-cam.adoc[leveloffset=+1]
+include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
+include::modules/migration-mtc-custom-resources.adoc[leveloffset=+1]
 include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1]
 include::modules/migration-understanding-migration-hooks.adoc[leveloffset=+1]
-
 :!migrating-4-1-4:
diff --git a/migration/migrating_4_1_4/troubleshooting-4-1-4.adoc b/migration/migrating_4_1_4/troubleshooting-4-1-4.adoc
@@ -30,4 +30,11 @@ include::modules/migration-rolling-back-migration-cli.adoc[leveloffset=+2]
 
 include::modules/migration-using-must-gather.adoc[leveloffset=+1]
 include::modules/migration-known-issues.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../../migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc#migration-mtc-workflow_migrating-4-1-4[{mtc-short} workflow]
+* xref:../../migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc#migration-mtc-custom-resources_migrating-4-1-4[{mtc-short} custom resources]
+
 :!migrating-4-1-4:
diff --git a/migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc b/migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc
@@ -1,5 +1,5 @@
 [id="migrating-application-workloads-4-2-4"]
-= Migration tools and prerequisites
+= About the {mtc-full}
 include::modules/common-attributes.adoc[]
 :context: migrating-4-2-4
 :migrating-4-2-4:
@@ -11,6 +11,8 @@ You can migrate application workloads from {product-title} 4.2 to {product-versi
 [NOTE]
 ====
 You can migrate between {product-title} clusters of the same version, for example, from 4.2 to 4.2 or from 4.3 to 4.3, as long as the source and target clusters are configured correctly.
+
+{mtc-short} is installed on the target cluster by default. You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on a remote cluster].
 ====
 
 The {mtc-short} web console and API, based on Kubernetes custom resources, enable you to migrate stateful and stateless application workloads at the granularity of a namespace.
@@ -20,8 +22,8 @@ The {mtc-short} web console and API, based on Kubernetes custom resources, enabl
 You can use migration hooks to run Ansible playbooks at certain points during the migration. The hooks are added when you create a migration plan.
 
 include::modules/migration-prerequisites.adoc[leveloffset=+1]
-include::modules/migration-understanding-cam.adoc[leveloffset=+1]
+include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
+include::modules/migration-mtc-custom-resources.adoc[leveloffset=+1]
 include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1]
 include::modules/migration-understanding-migration-hooks.adoc[leveloffset=+1]
-
 :!migrating-4-2-4:
diff --git a/migration/migrating_4_2_4/troubleshooting-4-2-4.adoc b/migration/migrating_4_2_4/troubleshooting-4-2-4.adoc
@@ -30,4 +30,11 @@ include::modules/migration-rolling-back-migration-cli.adoc[leveloffset=+2]
 
 include::modules/migration-using-must-gather.adoc[leveloffset=+1]
 include::modules/migration-known-issues.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../../migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc#migration-mtc-workflow_migrating-4-2-4[{mtc-short} workflow]
+* xref:../../migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc#migration-mtc-custom-resources_migrating-4-2-4[{mtc-short} custom resources]
+
 :!migrating-4-2-4:
diff --git a/modules/migration-mtc-custom-resources.adoc b/modules/migration-mtc-custom-resources.adoc
@@ -0,0 +1,40 @@
+//
+// * migration/migrating_3_4/migrating-application-workloads-3-4.adoc
+// * migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc
+// * migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc
+
+[id='migration-mtc-custom-resources_{context}']
+= {mtc-full} custom resources
+
+The {mtc-full} ({mtc-short}) creates the following custom resources (CRs):
+
+image::migration-architecture.png[migration architecture diagram]
+
+image:darkcircle-1.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migcluster_types.go[MigCluster] (configuration, {mtc-short} cluster): Cluster definition
+
+image:darkcircle-2.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migstorage_types.go[MigStorage] (configuration, {mtc-short} cluster): Storage definition
+
+image:darkcircle-3.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migplan_types.go[MigPlan] (configuration, {mtc-short} cluster): Migration plan
+
+The `MigPlan` CR describes the source and target clusters, replication repository, and namespaces being migrated. It is associated with 0, 1, or many `MigMigration` CRs.
+
+[NOTE]
+====
+Deleting a `MigPlan` CR deletes the associated `MigMigration` CRs.
+====
+
+image:darkcircle-4.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/backupstoragelocation_types.go[BackupStorageLocation] (configuration, {mtc-short} cluster): Location of `Velero` backup objects
+
+image:darkcircle-5.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/volume_snapshot_location.go[VolumeSnapshotLocation] (configuration, {mtc-short} cluster): Location of `Velero` volume snapshots
+
+image:darkcircle-6.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migmigration_types.go[MigMigration] (action, {mtc-short} cluster): Migration, created every time you stage or migrate data. Each `MigMigration` CR is associated with a `MigPlan` CR.
+
+image:darkcircle-7.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/backup.go[Backup] (action, source cluster): When you run a migration plan, the `MigMigration` CR creates two `Velero` backup CRs on each source cluster:
+
+* Backup CR #1 for Kubernetes objects
+* Backup CR #2 for PV data
+
+image:darkcircle-8.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/restore.go[Restore] (action, target cluster): When you run a migration plan, the `MigMigration` CR creates two `Velero` restore CRs on the target cluster:
+
+* Restore CR #1 (using Backup CR #2) for PV data
+* Restore CR #2 (using Backup CR #1) for Kubernetes objects
diff --git a/modules/migration-mtc-workflow.adoc b/modules/migration-mtc-workflow.adoc
@@ -4,12 +4,10 @@
 // * migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc
 // * migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc
 
-[id='migration-understanding-cam_{context}']
-= About the {mtc-full}
+[id='migration-mtc-workflow_{context}']
+= {mtc-full} workflow
 
-The {mtc-full} ({mtc-short}) enables you to migrate Kubernetes resources, persistent volume data, and internal container images from an {product-title} source cluster to an {product-title} {product-version} target cluster, using the {mtc-short} web console or the Kubernetes API.
-
-Migrating an application with the {mtc-short} web console involves the following steps:
+Migrating an application with the {mtc-short} web console involves the following workflow:
 
 . Install the {mtc-full} Operator on all clusters.
 +
@@ -25,6 +23,11 @@ The source and target clusters must have network access to the replication repos
 
 * *Copy*: {mtc-short} copies the data from the source cluster to the replication repository, and from the replication repository to the target cluster.
 +
+[NOTE]
+====
+If you are using direct image migration or direct volume migration, the images or volumes are copied directly from the source cluster to the target cluster.
+====
++
 image::migration-PV-copy.png[]
 
 * *Move*: {mtc-short} unmounts a remote volume, for example, NFS, from the source cluster, creates a PV resource on the target cluster pointing to the remote volume, and then mounts the remote volume on the target cluster. Applications running on the target cluster use the same remote volume that the source cluster was using. The remote volume must be accessible to the source and target clusters.
diff --git a/modules/migration-prerequisites.adoc b/modules/migration-prerequisites.adoc
@@ -5,7 +5,7 @@
 // * migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc
 
 [id='migration-prerequisites_{context}']
-= Migration prerequisites
+= {mtc-full} prerequisites
 
 The {mtc-full} ({mtc-short}) has the following prerequisites:
 
diff --git a/modules/migration-running-migration-plan-cam.adoc b/modules/migration-running-migration-plan-cam.adoc
@@ -9,6 +9,22 @@
 
 You can stage or migrate applications and data with the migration plan you created in the {mtc-full} ({mtc-short}) web console.
 
+[NOTE]
+====
+{mtc-short} sets the reclaim policy of migrated persistent volumes (PVs) to `Retain` on the target cluster.
+
+The `Backup` custom resource contains a `PVOriginalReclaimPolicy` annotation that indicates the original reclaim policy. You can manually restore the reclaim policy of the migrated PVs.
+====
+
+.Prerequisites
+
+The {mtc-short} web console must contain the following:
+
+* Source cluster in a `Ready` state
+* Target cluster in a `Ready` state
+* Replication repository
+* Valid migration plan
+
 .Procedure
 
 . Log in to the source cluster.
@@ -34,4 +50,4 @@ You can run *Stage* multiple times to reduce the actual migration time.
 .. Click the migrated project to view its status.
 .. In the *Routes* section, click *Location* to verify that the application is functioning, if applicable.
 .. Click *Workloads* -> *Pods* to verify that the pods are running in the migrated namespace.
-.. Click *Storage* -> *Persistent volumes* to verify that the migrated persistent volume is correctly provisioned.
+.. Click *Storage* -> *Persistent volumes* to verify that the migrated persistent volumes are correctly provisioned.
diff --git a/modules/migration-viewing-migration-crs.adoc b/modules/migration-viewing-migration-crs.adoc
@@ -4,40 +4,39 @@
 // * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc
 // * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc
 [id='migration-viewing-migration-crs_{context}']
-= Viewing migration custom resources
+= Viewing {mtc-short} custom resources
 
-The {mtc-full} ({mtc-short}) creates the following custom resources (CRs):
+You can view the following {mtc-full} ({mtc-short}) custom resources (CRs) to troubleshoot a failed migration:
 
-image::migration-architecture.png[migration architecture diagram]
-
-image:darkcircle-1.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migcluster_types.go[MigCluster] (configuration, {mtc-short} cluster): Cluster definition
-
-image:darkcircle-2.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migstorage_types.go[MigStorage] (configuration, {mtc-short} cluster): Storage definition
-
-image:darkcircle-3.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migplan_types.go[MigPlan] (configuration, {mtc-short} cluster): Migration plan
-
-The `MigPlan` CR describes the source and target clusters, replication repository, and namespaces being migrated. It is associated with 0, 1, or many `MigMigration` CRs.
-
-[NOTE]
-====
-Deleting a `MigPlan` CR deletes the associated `MigMigration` CRs.
-====
-
-image:darkcircle-4.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/backupstoragelocation_types.go[BackupStorageLocation] (configuration, {mtc-short} cluster): Location of `Velero` backup objects
-
-image:darkcircle-5.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/volume_snapshot_location.go[VolumeSnapshotLocation] (configuration, {mtc-short} cluster): Location of `Velero` volume snapshots
-
-image:darkcircle-6.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migmigration_types.go[MigMigration] (action, {mtc-short} cluster): Migration, created every time you stage or migrate data. Each `MigMigration` CR is associated with a `MigPlan` CR.
-
-image:darkcircle-7.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/backup.go[Backup] (action, source cluster): When you run a migration plan, the `MigMigration` CR creates two `Velero` backup CRs on each source cluster:
+* `MigCluster`
+* `MigStorage`
+* `MigPlan`
+* `BackupStorageLocation`
++
+The `BackupStorageLocation` CR contains a `migrationcontroller` label to identify the {mtc-short} instance that created the CR:
++
+[source,yaml]
+----
+    labels:
+      migrationcontroller: ebe13bee-c803-47d0-a9e9-83f380328b93
+----
 
-* Backup CR #1 for Kubernetes objects
-* Backup CR #2 for PV data
+* `VolumeSnapshotLocation`
++
+The `VolumeSnapshotLocation` CR contains a `migrationcontroller` label to identify the {mtc-short} instance that created the CR:
++
+[source,yaml]
+----
+    labels:
+      migrationcontroller: ebe13bee-c803-47d0-a9e9-83f380328b93
+----
 
-image:darkcircle-8.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/restore.go[Restore] (action, target cluster): When you run a migration plan, the `MigMigration` CR creates two `Velero` restore CRs on the target cluster:
+* `MigMigration`
+* `Backup`
++
+{mtc-short} changes the reclaim policy of migrated persistent volumes (PVs) to `Retain` on the target cluster. The `Backup` CR contains an `openshift.io/orig-reclaim-policy` annotation that indicates the original reclaim policy. You can manually restore the reclaim policy of the migrated PVs.
 
-* Restore CR #1 (using Backup CR #2) for PV data
-* Restore CR #2 (using Backup CR #1) for Kubernetes objects
+* `Restore`
 
 .Procedure
 
@@ -110,6 +109,7 @@ metadata:
     openshift.io/migrate-quiesce-pods: "true"
     openshift.io/migration-registry: 172.30.105.179:5000
     openshift.io/migration-registry-dir: /socks-shop-mig-plan-registry-44dd3bd5-c9f8-11e9-95ad-0205fe66cbb6
+    openshift.io/orig-reclaim-policy: delete
   creationTimestamp: "2019-08-29T01:03:15Z"
   generateName: 88435fe0-c9f8-11e9-85e6-5d593ce65e10-
   generation: 1
