MIG-1078: Update MTC 1.7 Compatibility guidelines #42576

stoobie · 2022-03-01T16:50:54Z

This PR addresses https://issues.redhat.com/browse/MIG-1078.

This applies to:
enterprise-4.10 and later

Preview:
https://deploy-preview-42576--osdocs.netlify.app/openshift-enterprise/latest/migrating_from_ocp_3_to_4/installing-3-4.html#migration-compatibility-guidelines_installing-3-4

Updated:

_attributes/common-attributes.adoc
modules/migration-compatibility-guidelines.adoc

netlify · 2022-03-01T16:53:36Z

✅ Deploy Preview for osdocs ready!

Name	Link
🔨 Latest commit	`031f3af`
🔍 Latest deploy log	https://app.netlify.com/sites/osdocs/deploys/623b2a0d54f2f60008473434
😎 Deploy Preview	https://deploy-preview-42576--osdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

stoobie · 2022-03-07T17:44:52Z

@eriknelson Please review.

eriknelson

I'm having a really hard time understanding this.

This section of the compatibility guidelines I think should be lifted practically verbatim. I'm open to reframing what we designate the channgel "stable" vs. "latest", but the language and details of this PR are not very accurate.

eriknelson · 2022-03-04T18:03:31Z

modules/migration-compatibility-guidelines.adoc

@@ -8,18 +8,45 @@
 [id="migration-compatibility-guidelines_{context}"]
 = Compatibility guidelines

+// Do we have a "What's New" section in the Release Notes? I'm wondering what, given the complicated support model we discuss here, is the motivation to upgrade from MTC 1.5/1.6 to MTC 1.7? Or is the usage model only: Install once, migrate, and that's it, you don't need MTC after that, so no need to upgrade...?


What is the motivation to upgrade?

https://issues.redhat.com/issues/?jql=labels%20%3D%20cee-training%20and%20project%20%3D%20MIG%20and%20fixVersion%20%3D%20%22MTC%201.7.0%22

MTC 1.7 adds several new features that may be of interest, including in-place storageclass conversion that is not possible with 1.6.

eriknelson · 2022-03-04T18:07:06Z

modules/migration-compatibility-guidelines.adoc

+* Legacy platforms are no longer supported.
+* You cannot install {mtc-short} 1.6 or {mtc-version} on legacy platforms, because the custom resource definition API versions are incompatible.
+//* You cannot install {mtc-short} 1.6 on {product-title} 4.5 or earlier versions, because the custom resource definition API versions are incompatible.
+* {mtc-short} 1.6 and later versions, including {mtc-version}, do not support the `MigrationController` custom resource and the {mtc-short} web console on legacy source clusters, which must run {mtc-short} {mtc-legacy-version-z}. So you must install {mtc-short} 1.6 or later, including {mtc-version}, on the destination cluster.


I'm having a very hard time understanding what this is trying to say, but MTC 1.6 is only available via OLM on modern platforms which support v1 CRDs. This includes all MTC CRD's (there are many), of which MigrationController is one.

eriknelson · 2022-03-04T18:10:08Z

modules/migration-compatibility-guidelines.adoc

+
+[NOTE]
+====
+With {mtc-short} {mtc-version} or later, when migrating from a source cluster on a legacy platform to a destination cluster on a modern platform, use the `crane tunnel-api` command. See xxx.


This is not true. The only time to use the crane tunnel-api is when:

You want to use 1.7 to migrate from a legacy cluster to a modern cluster
2) The modern cluster does not have network connectivity by default to the legacy cluster.

See https://github.com/konveyor/mig-operator/blob/master/docs/usage/CompatibilityGuidelines.md#supported-channels-and-platform-compatibility

If you are using the 1.5+1.6 stream, you may install 1.5 as a control cluster on the source legacy cluster, assuming that it's able to communicate with the target modern platform that is running 1.6.

This really should be treated as a small edge case.

eriknelson · 2022-03-15T17:25:06Z

modules/migration-compatibility-guidelines.adoc

+
+{product-title} 4.5 and earlier are referred to as _legacy platforms_. {product-title} 4.6 and later are referred to as _modern platforms_.
+
+* Legacy platforms are no longer supported.


I don't understand this statement. Is this in reference to supported by openshift? Or supported by MTC?

It's not accurate to say that MTC does not support legacy platforms.

eriknelson · 2022-03-15T17:27:27Z

modules/migration-compatibility-guidelines.adoc

+* Legacy platforms are no longer supported.
+* You cannot install {mtc-short} 1.6 or {mtc-version} on legacy platforms, because the custom resource definition API versions are incompatible.
+//* You cannot install {mtc-short} 1.6 on {product-title} 4.5 or earlier versions, because the custom resource definition API versions are incompatible.
+* {mtc-short} 1.6 and later versions, including {mtc-version}, do not support the `MigrationController` custom resource and the {mtc-short} web console on legacy source clusters, which must run {mtc-short} {mtc-legacy-version-z}. So you must install {mtc-short} 1.6 or later, including {mtc-version}, on the destination cluster.


{mtc-short} 1.6 and later versions, including {mtc-version}, do not support the MigrationController custom resource and the {mtc-short} web console on legacy source clusters,

This is not an accurate statement. For several reasons, including CRD incompatibility (which MTC uses to comprise its API) 1.6 is not supported on legacy platforms.

eriknelson · 2022-03-15T17:42:51Z

modules/migration-compatibility-guidelines.adoc

+* Legacy platforms are no longer supported.
+* You cannot install {mtc-short} 1.6 or {mtc-version} on legacy platforms, because the custom resource definition API versions are incompatible.
+//* You cannot install {mtc-short} 1.6 on {product-title} 4.5 or earlier versions, because the custom resource definition API versions are incompatible.
+* {mtc-short} 1.6 and later versions, including {mtc-version}, do not support the `MigrationController` custom resource and the {mtc-short} web console on legacy source clusters, which must run {mtc-short} {mtc-legacy-version-z}. So you must install {mtc-short} 1.6 or later, including {mtc-version}, on the destination cluster.


So you must install {mtc-short} 1.6 or later, including {mtc-version}, on the destination cluster.

I would eliminate "destination cluster". Source or destination cluster is not really relevant when it comes to compatibility decisions.

eriknelson · 2022-03-15T17:45:43Z

modules/migration-compatibility-guidelines.adoc

+====
+With {mtc-short} {mtc-version} or later, when migrating from a source cluster on a legacy platform to a destination cluster on a modern platform, use the `crane tunnel-api` command. See xxx.
+====
+// You can migrate workloads from a source cluster with {mtc-short} {mtc-legacy-version-z} to a target cluster with {mtc-short} {mtc-version} as long as the `MigrationController` custom resource and the {mtc-short} web console are running on the destination cluster.


The MigrationController resource is simply a CR reconciled by the operator to install MTC components. It will always be present regardless of whether the cluster is a source or a target. This also isn't really an accurate statement. The controller does not necessarily have to be a destination cluster.

https://github.com/konveyor/mig-operator/blob/master/docs/usage/AlternativeCAMTopologies.md

eriknelson

Getting closer, I noticed some things missing / incomplete.

eriknelson · 2022-03-22T17:46:07Z

modules/migration-compatibility-guidelines.adoc


-You can migrate workloads from a source cluster with {mtc-short} {mtc-legacy-version-z} to a target cluster with {mtc-short} {mtc-version} as long as the `MigrationController` custom resource and the {mtc-short} web console are running on the target cluster.
+legacy platform:: {product-title} 4.5 and earlier


Is there a reason these are all lowercased? Some kind of guideline?

@eriknelson
Just convention. For example, see the glossary of terms here: https://redhat-documentation.github.io/supplementary-style-guide/#_a

These words are not proper nouns, so lower case seems more appropriate.

eriknelson · 2022-03-22T17:46:38Z

modules/migration-compatibility-guidelines.adoc

-You can migrate workloads from a source cluster with {mtc-short} {mtc-legacy-version-z} to a target cluster with {mtc-short} {mtc-version} as long as the `MigrationController` custom resource and the {mtc-short} web console are running on the target cluster.
+legacy platform:: {product-title} 4.5 and earlier
+modern platform:: {product-title} 4.6 and later
+legacy operator:: The {mtc-short} Operator installed on a legacy platform


Suggestion: designed for legacy platforms.

eriknelson · 2022-03-22T17:46:55Z

modules/migration-compatibility-guidelines.adoc

+legacy platform:: {product-title} 4.5 and earlier
+modern platform:: {product-title} 4.6 and later
+legacy operator:: The {mtc-short} Operator installed on a legacy platform
+modern operator:: The {mtc-short} Operator installed


This isn't complete, I'd also suggest: designed for modern platforms.

eriknelson · 2022-03-22T17:47:53Z

modules/migration-compatibility-guidelines.adoc

+====
+Edge cases exist in which network restrictions prevent modern clusters from connecting to other clusters involved in the migration. For example, when migrating from an {product-title} 3.11 cluster on premises to a modern {product-title} cluster in the cloud, where the modern cluster cannot connect to the {product-title} 3.11 cluster.
+
+With {mtc-short} {mtc-version}, if one of the remote clusters is unable to communicate with the control cluster because of network restrictions, use the `crane tunnel-api` command.


We are missing the second piece that you and I talked about here regarding stable:

With the stable MTC release, although you should always designate the most modern cluster as the control cluster, in this specific case it is possible to designate the legacy cluster as the control cluster and push workloads to the remote cluster.

@eriknelson Fixed. Please approve.

eriknelson

LGTM, thanks for working with me on this @stoobie

mjpytlak · 2022-03-23T13:19:55Z

modules/migration-compatibility-guidelines.adoc

-You can migrate workloads from a source cluster with {mtc-short} {mtc-legacy-version-z} to a target cluster with {mtc-short} {mtc-version} as long as the `MigrationController` custom resource and the {mtc-short} web console are running on the target cluster.
+legacy platform:: {product-title} 4.5 and earlier
+modern platform:: {product-title} 4.6 and later
+legacy operator:: The {mtc-short} Operator designed for legacy platforms


Suggested change

legacy operator:: The {mtc-short} Operator designed for legacy platforms

legacy operator:: The {mtc-short} Operator designed for legacy platforms.

mjpytlak · 2022-03-23T13:20:06Z

modules/migration-compatibility-guidelines.adoc

+legacy platform:: {product-title} 4.5 and earlier
+modern platform:: {product-title} 4.6 and later
+legacy operator:: The {mtc-short} Operator designed for legacy platforms
+modern operator:: The {mtc-short} Operator designed for modern platforms


Suggested change

modern operator:: The {mtc-short} Operator designed for modern platforms

modern operator:: The {mtc-short} Operator designed for modern platforms.

mjpytlak · 2022-03-23T13:20:16Z

modules/migration-compatibility-guidelines.adoc

+modern platform:: {product-title} 4.6 and later
+legacy operator:: The {mtc-short} Operator designed for legacy platforms
+modern operator:: The {mtc-short} Operator designed for modern platforms
+control cluster:: The cluster that runs the {mtc-short} controller and GUI


Suggested change

control cluster:: The cluster that runs the {mtc-short} controller and GUI

control cluster:: The cluster that runs the {mtc-short} controller and GUI.

mjpytlak · 2022-03-23T13:20:28Z

modules/migration-compatibility-guidelines.adoc


-You can migrate workloads from a source cluster with {mtc-short} {mtc-legacy-version-z} to a target cluster with {mtc-short} {mtc-version} as long as the `MigrationController` custom resource and the {mtc-short} web console are running on the target cluster.
+legacy platform:: {product-title} 4.5 and earlier
+modern platform:: {product-title} 4.6 and later


Suggested change

modern platform:: {product-title} 4.6 and later

modern platform:: {product-title} 4.6 and later.

mjpytlak · 2022-03-23T13:22:39Z

modules/migration-compatibility-guidelines.adoc

@@ -10,16 +10,45 @@



While you are here, please add a content type attribute in the metadata: :_content-type: <TYPE>

mjpytlak · 2022-03-23T13:24:36Z

modules/migration-compatibility-guidelines.adoc


-You can migrate workloads from a source cluster with {mtc-short} {mtc-legacy-version-z} to a target cluster with {mtc-short} {mtc-version} as long as the `MigrationController` custom resource and the {mtc-short} web console are running on the target cluster.
+legacy platform:: {product-title} 4.5 and earlier


Suggested change

legacy platform:: {product-title} 4.5 and earlier

legacy platform:: {product-title} 4.5 and earlier.

mjpytlak · 2022-03-23T13:31:19Z

@stoobie Just a couple of minor suggestions. Also - does QE need to ack this?

stoobie · 2022-03-23T13:35:32Z

@mjpytlak Thanks for the suggestions, and I'll ask QE to take a look. I know that this is an OCP requirement.

mjpytlak · 2022-03-23T17:29:52Z

Thanks @stoobie peer review LGTM.

stillalearner

/lgtm

openshift-ci · 2022-03-24T09:11:08Z

@stillalearner: changing LGTM is restricted to collaborators

In response to this:

/lgtm

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

stoobie · 2022-03-24T16:04:33Z

@mjpytlak Please merge. MTC 1.7 is now live.

jeana-redhat · 2022-03-24T19:40:40Z

Labeling and merging per @mjpytlak via Slack 👍

...and of course I saw the 2 commits the split-second I took my finger off the mouse button 😩

mjpytlak · 2022-03-24T20:52:25Z

@stoobie tldr. Nothing for you to do.

Here is what happened.

Following the merge of this PR, I noticed that you had not squashed your commits. I reverted the merge in a separate PR (#43802), and we then went ahead and created, merged, and CP your changes to 4.10 and 4.11 in #43803.

openshift-ci bot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Mar 1, 2022

stoobie force-pushed the MIG-1078 branch 2 times, most recently from c7ad518 to 40dde7d Compare March 3, 2022 08:54

openshift-ci bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Mar 3, 2022

eriknelson suggested changes Mar 15, 2022

View reviewed changes

MIG-1078 Updating MTC 1.7 Compatibility Guidelines.

899ea35

stoobie force-pushed the MIG-1078 branch 3 times, most recently from 88aeda0 to b7c2179 Compare March 22, 2022 16:41

eriknelson suggested changes Mar 22, 2022

View reviewed changes

stoobie force-pushed the MIG-1078 branch 2 times, most recently from 8c91f03 to e5813a3 Compare March 23, 2022 09:08

eriknelson approved these changes Mar 23, 2022

View reviewed changes

mjpytlak reviewed Mar 23, 2022

View reviewed changes

MIG-1078 Initial commit

031f3af

stoobie force-pushed the MIG-1078 branch from e5813a3 to 031f3af Compare March 23, 2022 14:09

stillalearner approved these changes Mar 24, 2022

View reviewed changes

jeana-redhat added peer-review-done Signifies that the peer review team has reviewed this PR branch/enterprise-4.10 branch/enterprise-4.11 labels Mar 24, 2022

jeana-redhat added this to the Next Release milestone Mar 24, 2022

jeana-redhat merged commit 090a9fe into openshift:main Mar 24, 2022

mjpytlak mentioned this pull request Mar 24, 2022

Revert "MIG-1078: Update MTC 1.7 Compatibility guidelines" #43802

Merged

bergerhoffer mentioned this pull request Mar 24, 2022

MIG-1078 Updating MTC 1.7 Compatibility Guidelines. #43803

Merged

stoobie deleted the MIG-1078 branch March 31, 2022 09:25


		{product-title} 4.5 and earlier are referred to as _legacy platforms_. {product-title} 4.6 and later are referred to as _modern platforms_.

		* Legacy platforms are no longer supported.


		You can migrate workloads from a source cluster with {mtc-short} {mtc-legacy-version-z} to a target cluster with {mtc-short} {mtc-version} as long as the `MigrationController` custom resource and the {mtc-short} web console are running on the target cluster.
		legacy platform:: {product-title} 4.5 and earlier

	legacy operator:: The {mtc-short} Operator designed for legacy platforms
	legacy operator:: The {mtc-short} Operator designed for legacy platforms.

	modern operator:: The {mtc-short} Operator designed for modern platforms
	modern operator:: The {mtc-short} Operator designed for modern platforms.

	control cluster:: The cluster that runs the {mtc-short} controller and GUI
	control cluster:: The cluster that runs the {mtc-short} controller and GUI.

	modern platform:: {product-title} 4.6 and later
	modern platform:: {product-title} 4.6 and later.

MIG-1078: Update MTC 1.7 Compatibility guidelines #42576

MIG-1078: Update MTC 1.7 Compatibility guidelines #42576

Conversation

stoobie commented Mar 1, 2022 • edited

netlify bot commented Mar 1, 2022 • edited

✅ Deploy Preview for osdocs ready!

stoobie commented Mar 7, 2022

eriknelson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eriknelson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eriknelson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mjpytlak commented Mar 23, 2022 • edited

stoobie commented Mar 23, 2022

mjpytlak commented Mar 23, 2022

stillalearner left a comment

Choose a reason for hiding this comment

openshift-ci bot commented Mar 24, 2022

stoobie commented Mar 24, 2022

jeana-redhat commented Mar 24, 2022 • edited

mjpytlak commented Mar 24, 2022 • edited

stoobie commented Mar 1, 2022 •

edited

netlify bot commented Mar 1, 2022 •

edited

mjpytlak commented Mar 23, 2022 •

edited

jeana-redhat commented Mar 24, 2022 •

edited

mjpytlak commented Mar 24, 2022 •

edited