MIG-744: MTC 1.5.0 release notes

apinnick · apinnick · commit ab10be42ca7f · 2021-06-29T10:02:40.000+03:00
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -2023,7 +2023,7 @@ Topics:
 - Name: Upgrading MTC
   File: upgrading-3-4
 - Name: Premigration checklists
-  File: premigration-checklists
+  File: premigration-checklists-3-4
 - Name: Migrating your applications
   File: migrating-applications-3-4
 - Name: Advanced migration options
@@ -2037,14 +2037,16 @@ Distros: openshift-enterprise,openshift-origin
 Topics:
 - Name: About MTC
   File: about-mtc
+- Name: MTC release notes
+  File: mtc-release-notes
 - Name: Installing MTC
   File: installing-mtc
 - Name: Installing MTC in a restricted network environment
   File: installing-mtc-restricted
 - Name: Upgrading MTC
   File: upgrading-mtc
 - Name: Premigration checklists
-  File: premigration-checklists
+  File: premigration-checklists-mtc
 - Name: Migrating your applications
   File: migrating-applications-with-mtc
 - Name: Advanced migration options
diff --git a/migrating_from_ocp_3_to_4/about-migrating-from-3-to-4.adoc b/migrating_from_ocp_3_to_4/about-migrating-from-3-to-4.adoc
@@ -14,3 +14,5 @@ Learn about the differences between {product-title} versions 3 and 4. Prior to t
 
 xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#about-mtc-3-4[About the {mtc-full}]::
 Learn about the {mtc-full} ({mtc-short}) to migrate your application workloads.
+
+For new features, enhancements, and known issues, see the xref:../migration-toolkit-for-containers/mtc-release-notes.adoc#mtc-release-notes[{mtc-short} release notes].
diff --git a/migrating_from_ocp_3_to_4/about-mtc-3-4.adoc b/migrating_from_ocp_3_to_4/about-mtc-3-4.adoc
@@ -5,15 +5,15 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-The {mtc-full} ({mtc-short}) web console and API, based on Kubernetes custom resources, enable you to migrate stateful application workloads at the granularity of a namespace.
-
-You can migrate from {product-title} 3.7, 3.9, 3.10, or 3.11 to {product-version}. {mtc-short} enables you to control the migration and to minimize application downtime.
+The {mtc-full} ({mtc-short}) enables you to migrate stateful application workloads from {product-title} 3.7, 3.9, 3.10, or 3.11 to {product-version} at the granularity of a namespace.
 
 [IMPORTANT]
 ====
 Before you begin your migration, be sure to review the xref:../migrating_from_ocp_3_to_4/planning-migration-3-4.adoc#planning-migration-3-4[differences between {product-title} 3 and 4].
 ====
 
+{mtc-short} provides a web console and an API, based on Kubernetes custom resources, to help you control the migration and minimize application downtime.
+
 The {mtc-short} console is installed on the target cluster by default. You can configure the {mtc-full} Operator to install the console on an link:https://access.redhat.com/articles/5064151[{product-title} 3 source cluster or on a remote cluster].
 
 {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.
diff --git a/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc b/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc
@@ -1,4 +1,4 @@
-[id="advanced-migration-options-3-4_{context}"]
+[id="advanced-migration-options-3-4"]
 = Advanced migration options
 include::modules/common-attributes.adoc[]
 :context: advanced-migration-options-3-4
diff --git a/migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc b/migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc
@@ -8,6 +8,16 @@ toc::[]
 
 You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or from the command line.
 
+Most cluster-scoped resources are not yet handled by {mtc-short}. If your applications require cluster-scoped resources, you might have to create them manually on the target cluster.
+
+During migration, {mtc-short} preserves the following namespace annotations:
+
+* `openshift.io/sa.scc.mcs`
+* `openshift.io/sa.scc.supplemental-groups`
+* `openshift.io/sa.scc.uid-range`
+
+These annotations preserve the UID range, ensuring that the containers retain their file system permissions on the target cluster. There is a risk that the migrated UIDs could duplicate UIDs within an existing or future namespace on the target cluster.
+
 include::modules/migration-prerequisites.adoc[leveloffset=+1]
 
 [discrete]
diff --git a/migrating_from_ocp_3_to_4/premigration-checklists-3-4.adoc b/migrating_from_ocp_3_to_4/premigration-checklists-3-4.adoc
@@ -1,7 +1,7 @@
-[id="premigration-checks"]
+[id="premigration-checklists-3-4"]
 = Premigration checklists
 include::modules/common-attributes.adoc[]
-:context: premigration-checks
+:context: premigration-checklists-3-4
 
 toc::[]
 
diff --git a/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc b/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc
@@ -7,6 +7,8 @@ toc::[]
 
 This section describes resources for troubleshooting the {mtc-full} ({mtc-short}).
 
+For known issues, see the xref:../migration-toolkit-for-containers/mtc-release-notes.adoc#mtc-release-notes[{mtc-short} release notes].
+
 [id="logs-and-debugging-tools_{context}"]
 == Logs and debugging tools
 
diff --git a/migration-toolkit-for-containers/about-mtc.adoc b/migration-toolkit-for-containers/about-mtc.adoc
@@ -5,11 +5,19 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-The {mtc-full} ({mtc-short}) web console and API, based on Kubernetes custom resources, enable you to migrate stateful application workloads at the granularity of a namespace.
+The {mtc-full} ({mtc-short}) enables you to migrate stateful application workloads between {product-title} clusters at the granularity of a namespace
+
+{mtc-short} provides a web console and an API, based on Kubernetes custom resources, to help you control the migration and minimize application downtime.
 
 The {mtc-short} console is installed on the target cluster by default. You can configure the {mtc-full} Operator to install the console on a link:https://access.redhat.com/articles/5064151[remote cluster].
 
 {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.
 
+[id="additional-resources_{context}"]
+[discrete]
+== Additional resources
+
+* xref:../migration-toolkit-for-containers/advanced-migration-options-mtc.adoc#advanced-migration-options-mtc[Advanced migration options] for automating migration
+
 include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
 include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1]
diff --git a/migration-toolkit-for-containers/advanced-migration-options-mtc.adoc b/migration-toolkit-for-containers/advanced-migration-options-mtc.adoc
@@ -1,4 +1,4 @@
-[id="advanced-migration-options-mtc_{context}"]
+[id="advanced-migration-options-mtc"]
 = Advanced migration options
 include::modules/common-attributes.adoc[]
 :context: advanced-migration-options-mtc
diff --git a/migration-toolkit-for-containers/migrating-applications-with-mtc.adoc b/migration-toolkit-for-containers/migrating-applications-with-mtc.adoc
@@ -7,6 +7,16 @@ toc::[]
 
 You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or from the command line.
 
+Most cluster-scoped resources are not yet handled by {mtc-short}. If your applications require cluster-scoped resources, you might have to create them manually on the target cluster.
+
+During migration, the {mtc-full} ({mtc-short}) preserves the following namespace annotations:
+
+* `openshift.io/sa.scc.mcs`
+* `openshift.io/sa.scc.supplemental-groups`
+* `openshift.io/sa.scc.uid-range`
++
+These annotations preserve the UID range, ensuring that the containers retain their file system permissions on the target cluster. There is a risk that the migrated UIDs could duplicate UIDs within an existing or future namespace on the target cluster.
+
 include::modules/migration-prerequisites.adoc[leveloffset=+1]
 include::modules/migration-configuring-proxy-for-dvm.adoc[leveloffset=+2]
 
diff --git a/migration-toolkit-for-containers/mtc-release-notes.adoc b/migration-toolkit-for-containers/mtc-release-notes.adoc
@@ -0,0 +1,14 @@
+[id="mtc-release-notes"]
+= Migration Toolkit for Containers release notes
+include::modules/common-attributes.adoc[]
+:context: mtc-release-notes
+
+toc::[]
+
+The {mtc-full} ({mtc-short}) enables you to migrate stateful application workloads between {product-title} clusters at the granularity of a namespace.
+
+You can migrate from xref:../migrating_from_ocp_3_to_4/about-migrating-from-3-to-4.adoc[{product-title} 3.7, 3.9, 3.10, or 3.11 to {product-version}] and between {product-title} 4 clusters.
+
+{mtc-short} provides a web console and an API, based on Kubernetes custom resources, to help you control the migration and minimize application downtime.
+
+include::modules/migration-mtc-release-notes-1-5.adoc[leveloffset=+1]
diff --git a/migration-toolkit-for-containers/premigration-checklists-mtc.adoc b/migration-toolkit-for-containers/premigration-checklists-mtc.adoc
@@ -1,7 +1,7 @@
-[id="premigration-checks"]
+[id="premigration-checklists-mtc"]
 = Premigration checklists
 include::modules/common-attributes.adoc[]
-:context: premigration-checks
+:context: premigration-checklists-mtc
 
 toc::[]
 
diff --git a/migration-toolkit-for-containers/troubleshooting-mtc.adoc b/migration-toolkit-for-containers/troubleshooting-mtc.adoc
@@ -7,6 +7,8 @@ toc::[]
 
 This section describes resources for troubleshooting the {mtc-full} ({mtc-short}).
 
+For known issues, see the xref:../migration-toolkit-for-containers/mtc-release-notes.adoc#mtc-release-notes[{mtc-short} release notes].
+
 [id="logs-and-debugging-tools_{context}"]
 == Logs and debugging tools
 
@@ -35,7 +37,6 @@ This section describes common issues and concerns that can cause issues during m
 include::modules/migration-updating-deprecated-gvks.adoc[leveloffset=+2]
 include::modules/migration-dvm-error-node-selectors.adoc[leveloffset=+2]
 include::modules/migration-error-messages.adoc[leveloffset=+2]
-include::modules/migration-known-issues.adoc[leveloffset=+2]
 
 [id="rolling-back-migration_{context}"]
 == Rolling back a migration
diff --git a/modules/common-attributes.adoc b/modules/common-attributes.adoc
@@ -37,5 +37,5 @@ endif::[]
 :launch: image:app-launcher.png[title="Application Launcher"]
 :mtc-short: MTC
 :mtc-full: Migration Toolkit for Containers
-:mtc-version: 1.4
-:mtc-version-z: 1.4.4
+:mtc-version: 1.5
+:mtc-version-z: 1.5.0
diff --git a/modules/migration-known-issues.adoc b/modules/migration-known-issues.adoc
@@ -18,11 +18,8 @@ These annotations preserve the UID range, ensuring that the containers retain th
 
 * Most cluster-scoped resources are not yet handled by {mtc-short}. If your applications require cluster-scoped resources, you might have to create them manually on the target cluster.
 * If a migration fails, the migration plan does not retain custom PV settings for quiesced pods. You must manually roll back the migration, delete the migration plan, and create a new migration plan with your PV settings. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1784899[*BZ#1784899*])
-
 * If a large migration fails because Restic times out, you can increase the `restic_timeout` parameter value (default: `1h`) in the `MigrationController` custom resource (CR) manifest.
-
 * If you select the data verification option for PVs that are migrated with the file system copy method, performance is significantly slower.
-
 * If you are migrating data from NFS storage and `root_squash` is enabled, `Restic` maps to `nfsnobody`. The migration fails and a permission error is displayed in the `Restic` pod log. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1873641[*BZ#1873641*])
 +
 You can resolve this issue by adding supplemental groups for `Restic` to the `MigrationController` CR manifest:
diff --git a/modules/migration-mtc-release-notes-1-5.adoc b/modules/migration-mtc-release-notes-1-5.adoc
@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * migration-toolkit-for-containers/mtc-release-notes.adoc
+
+[id="migration-mtc-release-notes-1-5_{context}"]
+= {mtc-full} 1.5 release notes
+
+The release notes for {mtc-full} ({mtc-short}) version {mtc-version} describe new features, enhancements, and known issues.
+
+[id="new-features-and-enhancements-1-5_{context}"]
+== New features and enhancements
+
+This release has the following new features and enhancements:
+
+* The *Migration resource* tree on the *Migration details* page of the web console has been enhanced with additional resources, Kubernetes events, and live status information for monitoring and debugging migrations.
+* The web console can support hundreds of migration plans.
+* A source namespace can be mapped to a different target namespace in a migration plan. Previously, the source namespace was mapped to a target namespace with the same name.
+* Hook phases with status information are displayed in the web console during a migration.
+* The number of Rsync retry attempts is displayed in the web console during direct volume migration.
+* Persistent volume (PV) resizing can be enabled during direct volume migration to ensure that the target cluster does not run out of disk space.
+* The threshold that triggers PV resizing is configurable. Previously, PV resizing occurred when the disk usage exceeded 97%.
+* Velero has been updated to version 1.6, which provides numerous fixes and enhancements.
+* A cached Kubernetes client can be enabled to provide improved performance.
+
+[id="known-issues-1-5_{context}"]
+== Known issues
+
+This release has the following known issues:
+
+* PV resizing does not work as expected for AWS gp2 storage unless the `pv_resizing_threshold` is 42% or greater. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1973148[*BZ#1973148*])
+* If a migration fails, the migration plan does not retain custom PV settings for quiesced pods. You must manually roll back the migration, delete the migration plan, and create a new migration plan with your PV settings. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1784899[*BZ#1784899*])
diff --git a/modules/migration-understanding-data-copy-methods.adoc b/modules/migration-understanding-data-copy-methods.adoc
@@ -48,13 +48,10 @@ a|* Cloud provider must support snapshots.
 [id="direct-migration_{context}"]
 == Direct volume migration and direct image migration
 
-You can use _direct image migration_ and _direct volume migration_ to migrate images and data directly from the source cluster to the target cluster.
+You can use direct image migration (DIM) and direct volume migration (DVM) to migrate images and data directly from the source cluster to the target cluster.
 
-Direct migration has significant performance benefits because it skips the intermediate steps of backing up files from the source cluster to the replication repository and restoring files from the replication repository to the target cluster.
+If you run DVM with nodes that are in different availability zones, the migration might fail because the migrated pods cannot access the persistent volume claim.
 
-Direct migration uses link:https://rsync.samba.org/[Rsync] to transfer the files.
+DIM and DVM have significant performance benefits because the intermediate steps of backing up files from the source cluster to the replication repository and restoring files from the replication repository to the target cluster are skipped. The data is transferred with link:https://rsync.samba.org/[Rsync].
 
-[NOTE]
-====
-Direct image migration and direct volume migration have additional prerequisites.
-====
+DIM and DVM have additional prerequisites.

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-[id="advanced-migration-options-3-4_{context}"]`
	`1`	`+[id="advanced-migration-options-3-4"]`
`2`	`2`	`= Advanced migration options`
`3`	`3`	`include::modules/common-attributes.adoc[]`
`4`	`4`	`:context: advanced-migration-options-3-4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-[id="advanced-migration-options-mtc_{context}"]`
	`1`	`+[id="advanced-migration-options-mtc"]`
`2`	`2`	`= Advanced migration options`
`3`	`3`	`include::modules/common-attributes.adoc[]`
`4`	`4`	`:context: advanced-migration-options-mtc`