[enterprise-4.7] BZ1920404: Create migration controller in MTC upgrade

migration/migrating_3_4/deploying-cam-3-4.adoc

@@ -15,13 +15,18 @@ Optional: You can configure the {mtc-full} Operator to install the {mtc-short} l
 
 In a restricted environment, you can install the {mtc-full} Operator from a local mirror registry.
 
-After you have installed the {mtc-full} Operator on your clusters, you can launch the {mtc-short} web console.
+After you have installed the {mtc-full} Operator on your clusters, you can launch the {mtc-short} console.
 
 [id='installing-cam-operator_{context}']
 == Installing the {mtc-full} Operator
 
 You can install the {mtc-full} Operator with the Operator Lifecycle Manager (OLM) on an {product-title} {product-version} target cluster and manually on an {product-title} 3 source cluster.
 
+[IMPORTANT]
+====
+You must ensure that the same Operator version is installed on the source and target clusters.
+====
+
 include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2]
 include::modules/migration-installing-cam-operator-ocp-3.adoc[leveloffset=+2]
 :!migrating-3-4:

migration/migrating_3_4/upgrading-migration-tool-3-4.adoc

@@ -8,6 +8,13 @@ toc::[]
 
 You can upgrade the {mtc-full} ({mtc-short}) by installing the latest {mtc-full} Operator.
 
+[IMPORTANT]
+====
+You must ensure that the same Operator version is installed on the source and target clusters.
+
+Do not enable automatic updates on the {product-title} {product-version} cluster.
+====
+
 include::modules/migration-upgrading-migration-tool-4.adoc[leveloffset=+1]
 include::modules/migration-upgrading-migration-tool-3.adoc[leveloffset=+1]
 :migrating-3-4!:

modules/common-attributes.adoc

@@ -33,5 +33,5 @@ endif::[]
 :launch: image:app-launcher.png[title="Application Launcher"]
 :mtc-short: MTC
 :mtc-full: Migration Toolkit for Containers
-:mtc-version: 1.3
-:mtc-version-z: 1.3.2
+:mtc-version: 1.4
+:mtc-version-z: 1.4.0

modules/migration-installing-cam-operator-ocp-3.adoc

@@ -1,28 +1,30 @@
 // Module included in the following assemblies:
 //
 // * migration/migrating_3_4/deploying-cam-3-4.adoc
+
 [id="migration-installing-cam-operator-ocp-3_{context}"]
 ifdef::migrating-3-4[]
-= Installing the {mtc-full} Operator on an {product-title} 3 source cluster
+= Installing the {mtc-full} on an {product-title} 3 source cluster
 
-You can install the {mtc-full} ({mtc-short}) Operator manually on an {product-title} 3 source cluster.
+You can install the {mtc-full} ({mtc-short}) manually on an {product-title} 3 source cluster.
 endif::[]
 ifdef::disconnected-3-4[]
-= Installing the {mtc-full} Operator on an {product-title} 3 source cluster in a restricted environment
+= Installing the {mtc-full} on an {product-title} 3 source cluster in a restricted environment
 
 You can create a manifest file based on the {mtc-full} ({mtc-short}) Operator image and edit the manifest to point to your local image registry. Then, you can use the local image to create the {mtc-full} Operator on an {product-title} 3 source cluster.
 endif::[]
 
 [IMPORTANT]
 ====
-You must install the same {mtc-short} version on the {product-title} 3 and 4 clusters. The {mtc-full} Operator on the {product-title} 4 cluster is updated automatically by the Operator Lifecycle Manager.
+You must install the same {mtc-short} version on the {product-title} 3 and 4 clusters. The {mtc-full} Operator on the {product-title} 4 cluster is updated automatically by Operator Lifecycle Manager.
 
 To ensure that you have the latest version on the {product-title} 3 cluster, download the `operator.yml` and `controller-3.yml` files when you are ready to create and run the migration plan.
 ====
 
 .Prerequisites
 
 * Access to `registry.redhat.io`
+* Podman installed
 ifdef::migrating-3-4[]
 * {product-title} 3 cluster configured to pull images from `registry.redhat.io`
 +
@@ -134,7 +136,7 @@ rolebindings.rbac.authorization.k8s.io "system:image-pullers" already exists
 ----
 <1> You can ignore `Error from server (AlreadyExists)` messages. They are caused by the {mtc-full} Operator creating resources for earlier versions of {product-title} 3 that are provided in later releases.
 
-. Create the `MigrationController` CR object:
+. Create the `MigrationController` object:
 +
 [source,terminal]
 ----

modules/migration-installing-cam-operator-ocp-4.adoc

@@ -6,32 +6,32 @@
 
 [id="migration-installing-cam-operator-ocp-4_{context}"]
 ifdef::source-4-1-4[]
-= Installing the {mtc-full} Operator on an {product-title} 4.1 source cluster
+= Installing the {mtc-full} on an {product-title} 4.1 source cluster
 endif::[]
 ifdef::source-4-2-4[]
-= Installing the {mtc-full} Operator on an {product-title} 4.2 source cluster
+= Installing the {mtc-full} on an {product-title} 4.2 source cluster
 endif::[]
 ifdef::disconnected-source-4-1-4[]
-= Installing the {mtc-full} Operator on an {product-title} 4.1 source cluster in a restricted environment
+= Installing the {mtc-full} on an {product-title} 4.1 source cluster in a restricted environment
 endif::[]
 ifdef::disconnected-source-4-2-4[]
-= Installing the {mtc-full} Operator on an {product-title} 4.2 source cluster in a restricted environment
+= Installing the {mtc-full} on an {product-title} 4.2 source cluster in a restricted environment
 endif::[]
 ifdef::migrating-3-4,target-4-1-4,target-4-2-4[]
-= Installing the {mtc-full} Operator on an {product-title} {product-version} target cluster
+= Installing the {mtc-full} on an {product-title} {product-version} target cluster
 endif::[]
 ifdef::disconnected-3-4,disconnected-target-4-1-4,disconnected-target-4-2-4[]
-= Installing the {mtc-full} Operator on an {product-title} {product-version} target cluster in a restricted environment
+= Installing the {mtc-full} on an {product-title} {product-version} target cluster in a restricted environment
 endif::[]
 
 ifdef::source-4-1-4,source-4-2-4,disconnected-source-4-1-4,disconnected-source-4-2-4[]
-You can install the {mtc-full} ({mtc-short}) Operator on an {product-title} 4 source cluster with the Operator Lifecycle Manager (OLM).
+You can install the {mtc-full} ({mtc-short}) on an {product-title} 4 source cluster by using Operator Lifecycle Manager (OLM) to install the {mtc-full} Operator.
 endif::[]
 
 ifdef::migrating-3-4,target-4-1-4,target-4-2-4,disconnected-3-4,disconnected-target-4-1-4,disconnected-target-4-2-4[]
-You can install the {mtc-full} ({mtc-short}) Operator on an {product-title} {product-version} target cluster with the Operator Lifecycle Manager (OLM).
+You can install the {mtc-full} ({mtc-short}) on an {product-title} {product-version} target cluster by using Operator Lifecycle Manager (OLM) to install the {mtc-full} Operator.
 
-The {mtc-full} Operator installs the {mtc-short} on the target cluster by default.
+{mtc-short} is installed on the target cluster by default.
 endif::[]
 
 ifdef::disconnected-3-4,disconnected-target-4-1-4,disconnected-target-4-2-4,disconnected-source-4-1-4,disconnected-source-4-2-4[]
@@ -51,43 +51,48 @@ ifdef::source-4-1-4[]
 endif::[]
 . Use the *Filter by keyword* field to find the *{mtc-full} Operator*.
 . Select the *{mtc-full} Operator* and click *Install*.
-. On the *Install Operator* page, click *Install*.
+ifdef::migrating-3-4[]
++
+[NOTE]
+====
+Do not change the subscription approval option to *Automatic*. The {mtc-full} Operator version must be the same on the source and the target clusters.
+====
+endif::[]
+
+ifdef::target-4-2-4,source-4-2-4,target-4-1-4[]
+. In the *Subscription* tab, change the *Approval* option to *Automatic*.
+endif::[]
+. Click *Install*.
 +
 On the *Installed Operators* page, the *{mtc-full} Operator* appears in the *openshift-migration* project with the status *Succeeded*.
 
 . Click *{mtc-full} Operator*.
 . Under *Provided APIs*, locate the *Migration Controller* tile, and click *Create Instance*.
 
 ifdef::source-4-1-4[]
-. Set the `migration_controller` and `migration_ui` parameters to `false` and add the `deprecated_cors_configuration: true` parameter to the `spec` stanza:
+. Update the `migration_controller` and `migration_ui` parameters and add the `deprecated_cors_configuration` parameter to the manifest:
 +
 [source,yaml]
 ----
 spec:
-  ...
+...
   migration_controller: false
   migration_ui: false
-  ...
+...
   deprecated_cors_configuration: true
 ----
 endif::[]
 ifdef::source-4-2-4[]
-. Set the `migration_controller` and `migration_ui` parameters to `false` in the `spec` stanza:
+. Update the `migration_controller` and `migration_ui` parameters in the manifest:
 +
 [source,yaml]
 ----
 spec:
-  ...
+...
   migration_controller: false
   migration_ui: false
-  ...
 ----
 endif::[]
 
 . Click *Create*.
-ifdef::source-4-1-4,source-4-2-4[]
-. Click *Workloads* -> *Pods* to verify that the `Restic` and `Velero` pods are running.
-endif::[]
-ifdef::disconnected-3-4,disconnected-target-4-1-4,disconnected-target-4-2-4,migrating-3-4,target-4-2-4,target-4-1-4[]
-. Click *Workloads* -> *Pods* to verify that the `ControllerManager`, `MigrationUI`, `Restic`, and `Velero` pods are running.
-endif::[]
+. Click *Workloads* -> *Pods* to verify that the {mtc-short} pods are running.

modules/migration-running-migration-plan-cam.adoc

@@ -29,7 +29,7 @@ $ oc adm prune images
 ----
 
 . Log in to the {mtc-short} web console and click *Migration plans*.
-. Click the *Options* menu {kebab} beside a migration plan and select *Stage* to copy data from the source cluster to the target cluster without stopping the application.
+. Click the *Options* menu {kebab} next to a migration plan and select *Stage* to copy data from the source cluster to the target cluster without stopping the application.
 +
 You can run *Stage* multiple times to reduce the actual migration time.
 

modules/migration-upgrading-migration-tool-3.adoc

@@ -3,14 +3,14 @@
 // * migration/migrating_3_4/upgrading-migration-tool-3-4.adoc
 
 [id='migration-upgrading-migration-tool-3_{context}']
-= Upgrading the {mtc-full} Operator on an {product-title} 3 cluster
+= Upgrading the {mtc-full} on an {product-title} 3 cluster
 
 You can upgrade {mtc-full} ({mtc-short}) on an {product-title} 3 cluster by downloading the latest `operator.yml` file and replacing the existing {mtc-full} Operator.
 
-[NOTE]
-====
-If you remove and recreate the namespace, you must update the cluster service account token in the {mtc-short} web console.
-====
+.Prerequisites
+
+* Access to `registry.redhat.io`
+* Podman installed
 
 .Procedure
 
@@ -35,16 +35,7 @@ $ sudo podman cp $(sudo podman create registry.redhat.io/rhmtc/openshift-migrati
 $ oc replace --force -f operator.yml
 ----
 
-. If you are upgrading from version 1.1.2 or earlier, delete the `Restic` pod to apply the changes:
-
-.. Get the `Restic` pod names:
-+
-[source,terminal]
-----
-$ oc get pod -n openshift-migration | grep restic
-----
-
-.. Delete each `Restic` Pod:
+. If you are upgrading from version 1.1.2 or earlier, delete the `Restic` pods to apply the changes:
 +
 [source,terminal]
 ----
@@ -65,9 +56,43 @@ $ oc scale -n openshift-migration --replicas=0 deployment/migration-operator
 $ oc scale -n openshift-migration --replicas=1 deployment/migration-operator
 ----
 
-. Verify that the operator was upgraded to the latest version:
+. Verify that the `migration-operator` was upgraded to {mtc-version-z}:
 +
 [source,terminal]
 ----
 $ oc -o yaml -n openshift-migration get deployment/migration-operator | grep image: | awk -F ":" '{ print $NF }'
 ----
+
+. Download the latest `controller-3.yml` file:
++
+[source,terminal,subs="attributes+"]
+----
+$ sudo podman cp $(sudo podman create registry.redhat.io/rhmtc/openshift-migration-rhel7-operator:v{mtc-version-z}):/controller-3.yml ./
+----
+
+. Create the `MigrationController` object:
++
+[source,terminal]
+----
+$ oc create -f controller-3.yml
+----
+
+. Verify that the {mtc-short} pods are running:
++
+[source,terminal]
+----
+$ oc get pods -n openshift-migration
+----
+
+. If you have already added your {product-title} 3 source cluster to the {mtc-short} console, you must update the service account token because the upgrade deletes and restores the `openshift-migration` namespace:
+
+.. Obtain the service account token:
++
+[source,terminal]
+----
+$ oc sa get-token migration-controller -n openshift-migration
+----
+
+.. In the {mtc-short} console, click *Clusters*, click the Options menu {kebab} next to the source cluster, and select *Edit*.
+
+.. Enter the new service account token in the *Service account token* field, click *Update cluster*, and then click *Close*.

modules/migration-upgrading-migration-tool-4.adoc

@@ -4,44 +4,62 @@
 // * migration/migrating_4_2_4/upgrading-migration-tool-4-2-4.adoc
 
 [id='migration-upgrading-migration-tool-4_{context}']
-= Upgrading the {mtc-full} Operator on an {product-title} 4 cluster
+= Upgrading the {mtc-full} on an {product-title} 4 cluster
 
-ifeval::["{mtc-version}" > "1.3"]
-You can upgrade the {mtc-full} ({mtc-short}) Operator on an {product-title} 4 cluster with the Operator Lifecycle Manager.
+You can upgrade the {mtc-full} ({mtc-short}) on an {product-title} 4 cluster using the {product-title} console.
 
+ifdef::migrating-4-1-4,migrating-4-2-4[]
 If you selected the *Automatic* approval option when you installed the {mtc-full} Operator, the Operator is updated automatically.
 
 The following procedure enables you to change the *Manual* approval option to *Automatic* or to change the release channel.
+endif::[]
 
 .Procedure
 
-. In the {product-title} console, navigate to *Operators* > *Installed Operators*.
+. In the {product-title} console, navigate to *Operators* -> *Installed Operators*.
 . Click *{mtc-full} Operator*.
+ifdef::migrating-4-1-4,migrating-4-2-4[]
 . In the *Subscription* tab, change the *Approval* option to *Automatic*.
 . Optional: Edit the *Channel*.
 +
 Updating the subscription deploys the updated {mtc-full} Operator and updates the {mtc-short} components.
 endif::[]
-ifeval::["{mtc-version}" <= "1.3"]
-You can upgrade to {mtc-full} ({mtc-short}) {mtc-version} on an {product-title} 4 cluster by deleting the `MigrationController` custom resource (CR), uninstalling the CAM Operator, and then installing the {mtc-full} Operator.
-
-.Procedure
 
-. Delete the `MigrationController` CR:
+. Under *Provided APIs*, locate the *Migration Controller* tile, and click *Create Instance*.
+ifdef::migrating-4-1-4[]
+. If you are upgrading {mtc-short} on a 4.1 _source_ cluster, update the `migration_controller` and `migration_ui` parameters and add the `deprecated_cors_configuration` parameter to the `migration_controller` manifest:
 +
-[source,terminal]
+[source,yaml]
 ----
-$ oc delete migrationcontroller -n openshift-migration migration-controller
+spec:
+...
+  migration_controller: false
+  migration_ui: false
+  deprecated_cors_configuration: true
 ----
++
+[NOTE]
+====
+You do not need to update the manifest of the target cluster.
+====
+endif::[]
 
-. In the {product-title} console, navigate to *Operators* > *Installed Operators*.
-. Click *CAM Operator*.
-. On the right side of the *Operator Details* page, select *Uninstall Operator* from the *Actions* list.
-. Select *Uninstall*. This Operator stops running and no longer receives updates.
-. Navigate to *Operators* -> *OperatorHub*.
-. Use the *Filter by keyword* field to find the *{mtc-full} Operator*.
-. Select the *{mtc-full} Operator* and click *Install*.
-. On the *Install Operator* page, click *Install*.
+ifdef::migrating-4-2-4[]
+. If you are upgrading {mtc-short} on a 4.2 _source_ cluster, update the `migration_controller` and `migration_ui` parameters in the `migration_controller` manifest:
 +
-On the *Installed Operators* page, verify that the *{mtc-full} Operator* appears in the *openshift-migration* project with the status *Succeeded*.
+[source,yaml]
+----
+spec:
+...
+  migration_controller: false
+  migration_ui: false
+----
++
+[NOTE]
+====
+You do not need to update the manifest of the target cluster.
+====
 endif::[]
+
+. Click *Create*.
+. Click *Workloads* -> *Pods* to verify that the {mtc-short} pods are running.