From 98cc14c94f35cfe6d39f3ed94982551ff3409d19 Mon Sep 17 00:00:00 2001 From: Andy Arnold Date: Thu, 28 Sep 2023 20:04:25 +0100 Subject: [PATCH] MIG-1453: updating upgrade documentation --- .../upgrading-mtc.adoc | 2 + modules/migration-upgrading-from-mtc-1-3.adoc | 7 ++ modules/migration-upgrading-mtc-on-ocp-4.adoc | 16 ++++ modules/upgrading-mtc-1-8-0.adoc | 64 ++++++++++++++ modules/upgrading-oadp10-to12-in-mtc.adoc | 84 +++++++++++++++++++ 5 files changed, 173 insertions(+) create mode 100644 modules/upgrading-mtc-1-8-0.adoc create mode 100644 modules/upgrading-oadp10-to12-in-mtc.adoc diff --git a/migration_toolkit_for_containers/upgrading-mtc.adoc b/migration_toolkit_for_containers/upgrading-mtc.adoc index 3d95d8f4981b..3595dbc09915 100644 --- a/migration_toolkit_for_containers/upgrading-mtc.adoc +++ b/migration_toolkit_for_containers/upgrading-mtc.adoc @@ -17,6 +17,8 @@ If you are upgrading from {mtc-short} version 1.3, you must perform an additiona ==== include::modules/migration-upgrading-mtc-on-ocp-4.adoc[leveloffset=+1] +include::modules/upgrading-mtc-1-8-0.adoc[leveloffset=+1] +include::modules/upgrading-oadp10-to12-in-mtc.adoc[leveloffset=+2] include::modules/migration-upgrading-mtc-with-legacy-operator.adoc[leveloffset=+1] include::modules/migration-upgrading-from-mtc-1-3.adoc[leveloffset=+1] :upgrading-mtc!: diff --git a/modules/migration-upgrading-from-mtc-1-3.adoc b/modules/migration-upgrading-from-mtc-1-3.adoc index 876dd906a959..0f6291958228 100644 --- a/modules/migration-upgrading-from-mtc-1-3.adoc +++ b/modules/migration-upgrading-from-mtc-1-3.adoc @@ -11,6 +11,13 @@ If you are upgrading {mtc-full} ({mtc-short}) version 1.3.x to {mtc-version}, yo Because the `indirectImageMigration` and `indirectVolumeMigration` parameters do not exist in {mtc-short} 1.3, their default value in version 1.4 is `false`, which means that direct image migration and direct volume migration are enabled. Because the direct migration requirements are not fulfilled, the migration plan cannot reach a `Ready` state unless these parameter values are changed to `true`. +[IMPORTANT] + +==== +* Migrating from {product-title} 3 to {product-title} 4 requires a legacy {mtc-short} Operator and {mtc-short} 1.7.x. +* Upgrading MTC 1.7.x to 1.8.x requires manually updating the OADP channel from `stable-1.0` to `stable-1.2` in order to successfully complete the upgrade from 1.7.x to 1.8.x. +==== + .Prerequisites * You must be logged in as a user with `cluster-admin` privileges. diff --git a/modules/migration-upgrading-mtc-on-ocp-4.adoc b/modules/migration-upgrading-mtc-on-ocp-4.adoc index f6b3395cc2a4..e031724387c6 100644 --- a/modules/migration-upgrading-mtc-on-ocp-4.adoc +++ b/modules/migration-upgrading-mtc-on-ocp-4.adoc @@ -9,6 +9,22 @@ You can upgrade the {mtc-full} ({mtc-short}) on {product-title} {product-version} by using the Operator Lifecycle Manager. +[IMPORTANT] +==== +When upgrading the {mtc-short} by using the Operator Lifecycle Manager, you must use a supported migration path. +==== + +.Migration paths +* Migrating from {product-title} 3 to {product-title} 4 requires a legacy {mtc-short} Operator and {mtc-short} 1.7.x. +* Migrating from {mtc-short} 1.7.x to {mtc-short} 1.8.x is not supported. +* You must use {mtc-short} 1.7.x to migrate anything with a source of {product-title} 4.9 or earlier. +** {mtc-short} 1.7.x must be used on both source and destination. +* MTC 1.8.x only supports migrations from {product-title} 4.10 or later to {product-title} 4.10 or later. For migrations only involving cluster versions 4.10 and later, either 1.7.x or 1.8.x may be used. However, it must be the same MTC version on both source & destination. +** Migration from source {mtc-short} 1.7.x to destination {mtc-short} 1.8.x is unsupported. +** Migration from source {mtc-short} 1.8.x to destination {mtc-short} 1.7.x is unsupported. +** Migration from source {mtc-short} 1.7.x to destination {mtc-short} 1.7.x is supported. +** Migration from source {mtc-short} 1.8.x to destination {mtc-short} 1.8.x is supported + .Prerequisites * You must be logged in as a user with `cluster-admin` privileges. diff --git a/modules/upgrading-mtc-1-8-0.adoc b/modules/upgrading-mtc-1-8-0.adoc new file mode 100644 index 000000000000..9dbab0f3803b --- /dev/null +++ b/modules/upgrading-mtc-1-8-0.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * migration_toolkit_for_containers/upgrading-mtc.adoc + +:_content-type: PROCEDURE +[id="migration-upgrading-mtc-18_{context}"] += Upgrading the {mtc-full} to 1.8.0 + +To upgrade the {mtc-full} to 1.8.0, complete the following steps. + +.Procedure + +. Determine subscription names and current channels to work with for upgrading by using one of the following methods: + +** Determine the subscription names and channels by running the following command: ++ +[source,terminal] +---- +$ oc -n openshift-migration get sub +---- ++ +.Example output +[source,terminal] +---- +NAME PACKAGE SOURCE CHANNEL +mtc-operator mtc-operator mtc-operator-catalog release-v1.7 +redhat-oadp-operator-stable-1.0-mtc-operator-catalog-openshift-marketplace redhat-oadp-operator mtc-operator-catalog stable-1.0 +---- + +** Or return the subscription names and channels in JSON by running the following command: ++ +[source,terminal] +---- +$ oc -n openshift-migration get sub -o json | jq -r '.items[] | { name: .metadata.name, package: .spec.name, channel: .spec.channel }' +---- ++ +.Example output +[source,terminal] +---- +{ + "name": "mtc-operator", + "package": "mtc-operator", + "channel": "release-v1.7" +} +{ + "name": "redhat-oadp-operator-stable-1.0-mtc-operator-catalog-openshift-marketplace", + "package": "redhat-oadp-operator", + "channel": "stable-1.0" +} +---- + +. For each subscription, patch to move from the {mtc-short} 1.7 channel to the {mtc-short} 1.8 channel by running the following command: ++ +[source,terminal] +---- +$ oc -n openshift-migration patch subscription mtc-operator --type merge --patch '{"spec": {"channel": "release-v1.8"}}' +---- ++ +.Example output +[source,terminal] +---- +subscription.operators.coreos.com/mtc-operator patched +---- + diff --git a/modules/upgrading-oadp10-to12-in-mtc.adoc b/modules/upgrading-oadp10-to12-in-mtc.adoc new file mode 100644 index 000000000000..b654505cc312 --- /dev/null +++ b/modules/upgrading-oadp10-to12-in-mtc.adoc @@ -0,0 +1,84 @@ +// Module included in the following assemblies: +// +// * migrating_from_ocp_3_to_4/upgrading-3-4.adoc +// * migration_toolkit_for_containers/upgrading-mtc.adoc + +:_content-type: PROCEDURE +[id="migration-upgrading-oadp-for-mtc-18_{context}"] += Upgrading OADP 1.0 to 1.2 for {mtc-full} 1.8.0 + +To upgrade OADP 1.0 to 1.2 for {mtc-full} 1.8.0, complete the following steps. + +.Procedure + + +* For each subscription, patch the OADP operator from OADP 1.0 to OADP 1.2 by running the following command: ++ +[source,terminal] +---- +$ oc -n openshift-migration patch subscription redhat-oadp-operator-stable-1.0-mtc-operator-catalog-openshift-marketplace --type merge --patch '{"spec": {"channel":"stable-1.2"}}' +---- ++ +[NOTE] +==== +Sections indicating the user-specific returned `NAME` values that are used for the installation of MTC & OADP, respectively. +==== ++ +.Example output +[source,terminal] +---- +subscription.operators.coreos.com/redhat-oadp-operator-stable-1.0-mtc-operator-catalog-openshift-marketplace patched +---- ++ +[NOTE] +==== +The returned value will be similar to `redhat-oadp-operator-stable-1.0-mtc-operator-catalog-openshift-marketplace`, which is used in this example. +==== ++ +-- +* If the `installPlanApproval` parameter is set to `Automatic`, the Operator Lifecycle Manager (OLM) begins the upgrade process. +* If the `installPlanApproval` parameter is set to `Manual`, you must approve each `installPlan` before the OLM begins the upgrades. +-- + +.Verification +. Verify that the OLM has completed the upgrades of OADP and {mtc-short} by running the following command: ++ +[source,terminal] +---- +$ oc -n openshift-migration get subscriptions.operators.coreos.com mtc-operator -o json | jq '.status | (."state"=="AtLatestKnown")' +---- + +. When a value of `true` is returned, verify the channel used for each subscription by running the following command: ++ +[source,terminal] +---- +$ oc -n openshift-migration get sub -o json | jq -r '.items[] | {name: .metadata.name, channel: .spec.channel }' +---- ++ +.Example output +[source,terminal] +---- +{ + "name": "mtc-operator", + "channel": "release-v1.8" +} +{ + "name": "redhat-oadp-operator-stable-1.0-mtc-operator-catalog-openshift-marketplace", + "channel": "stable-1.2" +} +---- + + Confirm that the `mtc-operator.v1.8.0` and `oadp-operator.v1.2.x` packages are installed by running the following command: ++ +[source,terminal] +---- +$ oc -n openshift-migration get csv +---- ++ +.Example output +[source,terminal] +---- +NAME DISPLAY VERSION REPLACES PHASE +mtc-operator.v1.8.0 Migration Toolkit for Containers Operator 1.8.0 mtc-operator.v1.7.13 Succeeded +oadp-operator.v1.2.2 OADP Operator 1.2.2 oadp-operator.v1.0.13 Succeeded +----