From e8b5e271834388fd756d207ce3e9a4ee8807fa8d Mon Sep 17 00:00:00 2001 From: Avital Pinnick Date: Wed, 23 Jun 2021 11:35:13 +0300 Subject: [PATCH] MIG-744: MTC 1.5.0 release notes --- _topic_map.yml | 6 ++-- .../about-migrating-from-3-to-4.adoc | 2 ++ migrating_from_ocp_3_to_4/about-mtc-3-4.adoc | 6 ++-- .../advanced-migration-options-3-4.adoc | 2 +- .../migrating-applications-3-4.adoc | 10 ++++++ ....adoc => premigration-checklists-3-4.adoc} | 4 +-- .../troubleshooting-3-4.adoc | 2 ++ .../about-mtc.adoc | 10 +++++- .../advanced-migration-options-mtc.adoc | 2 +- .../migrating-applications-with-mtc.adoc | 10 ++++++ .../mtc-release-notes.adoc | 14 +++++++++ ....adoc => premigration-checklists-mtc.adoc} | 4 +-- .../troubleshooting-mtc.adoc | 3 +- modules/common-attributes.adoc | 4 +-- modules/migration-known-issues.adoc | 3 -- modules/migration-mtc-release-notes-1-5.adoc | 31 +++++++++++++++++++ ...ation-understanding-data-copy-methods.adoc | 11 +++---- 17 files changed, 99 insertions(+), 25 deletions(-) rename migrating_from_ocp_3_to_4/{premigration-checklists.adoc => premigration-checklists-3-4.adoc} (98%) create mode 100644 migration-toolkit-for-containers/mtc-release-notes.adoc rename migration-toolkit-for-containers/{premigration-checklists.adoc => premigration-checklists-mtc.adoc} (98%) create mode 100644 modules/migration-mtc-release-notes-1-5.adoc diff --git a/_topic_map.yml b/_topic_map.yml index fb5ab9f803..d7ebd2346e 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2011,7 +2011,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 @@ -2025,6 +2025,8 @@ 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 @@ -2032,7 +2034,7 @@ Topics: - 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 index 50ba6fb93c..49f9b7ba78 100644 --- 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 index 486798832f..5843fcb0bb 100644 --- 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 index cadf9d3c16..ffa28792f4 100644 --- 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 index b34e104a61..fc8115bff1 100644 --- 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.adoc b/migrating_from_ocp_3_to_4/premigration-checklists-3-4.adoc similarity index 98% rename from migrating_from_ocp_3_to_4/premigration-checklists.adoc rename to migrating_from_ocp_3_to_4/premigration-checklists-3-4.adoc index 03fccc3e91..fa09413702 100644 --- a/migrating_from_ocp_3_to_4/premigration-checklists.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 index 7da156abac..c947f3fa91 100644 --- 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 index ffa5aea9c7..c4c12d688e 100644 --- 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 index b61b29a27a..7b1a165a49 100644 --- 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 index 91ee90ba3e..a790ac419e 100644 --- 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 new file mode 100644 index 0000000000..4b7d6bd13c --- /dev/null +++ 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.adoc b/migration-toolkit-for-containers/premigration-checklists-mtc.adoc similarity index 98% rename from migration-toolkit-for-containers/premigration-checklists.adoc rename to migration-toolkit-for-containers/premigration-checklists-mtc.adoc index c88d503241..a7ed7362bf 100644 --- a/migration-toolkit-for-containers/premigration-checklists.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 index 9a175e90ad..ac1b9db633 100644 --- 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 index 2465081a9a..1250604e9b 100644 --- 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 index 743fbc5b9d..329dd529fb 100644 --- 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 new file mode 100644 index 0000000000..1c8ffe1e71 --- /dev/null +++ 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 index 1a0807e112..937e5c82b4 100644 --- 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.