MIG-684: Map namespaces

Author: apinnick

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

@@ -24,15 +24,18 @@ You can create a migration plan in the {mtc-full} ({mtc-short}) web console.
 +
 The migration plan name must not exceed 253 lower-case alphanumeric characters (`a-z, 0-9`) and must not contain spaces or underscores (`_`).
 
-. Select a *Source cluster*, a *Target cluster*, and a *Repository*, and click *Next*.
-. On the *Namespaces* page, select the projects to be migrated and click *Next*.
-. On the *Persistent volumes* page, click a *Migration type* for each PV:
+. Select a *Source cluster*, a *Target cluster*, and a *Repository*.
+. Click *Next*.
+. Select the projects for migration.
+. Optional: Click the edit icon beside a project to change the target namespace.
+. Click *Next*.
+. Select a *Migration type* for each PV:
 
 * The *Copy* option copies the data from the PV of a source cluster to the replication repository and then restores the data on a newly created PV, with similar characteristics, in the target cluster.
 * The *Move* option unmounts a remote volume, for example, NFS, from the source cluster, creates a PV resource on the target cluster pointing to the remote volume, and then mounts the remote volume on the target cluster. Applications running on the target cluster use the same remote volume that the source cluster was using.
 
 . Click *Next*.
-. On the *Copy options* page, select a *Copy method* for each PV:
+. Select a *Copy method* for each PV:
 
 * *Snapshot copy* backs up and restores data using the cloud provider's snapshot functionality. It is significantly faster than *Filesystem copy*.
 * *Filesystem copy* backs up the files on the source cluster and restores them on the target cluster.
@@ -51,7 +54,7 @@ If you selected *Filesystem copy*, you can change the target storage class.
 The direct migration options copy images and files directly from the source cluster to the target cluster. This option is much faster than copying images and files from the source cluster to the replication repository and then from the replication repository to the target cluster.
 
 . Click *Next*.
-. Optional: On the *Hooks* page, click *Add Hook* to add a hook to the migration plan.
+. Optional: Click *Add Hook* to add a hook to the migration plan.
 +
 A hook runs custom code. You can add up to four hooks to a single migration plan. Each hook runs during a different migration step.
 

modules/migration-migrating-applications-api.adoc

@@ -242,16 +242,37 @@ spec:
     name: <migstorage_ref> <3>
     namespace: openshift-migration
   namespaces:
-    - <application_namespace> <4>
+    - <source_namespace_1> <4>
+    - <source_namespace_2>
+    - <source_namespace_3>:<destination_namespace> <5>
   srcMigClusterRef:
-    name: <remote_cluster_ref> <5>
+    name: <remote_cluster_ref> <6>
     namespace: openshift-migration
 ----
 <1> Direct image migration is enabled if `false`.
 <2> Direct volume migration is enabled if `false`.
 <3> Specify the name of the `MigStorage` CR instance.
-<4> Specify one or more namespaces to be migrated.
-<5> Specify the name of the source cluster `MigCluster` instance.
+<4> Specify one or more source namespaces. If you specify only the source namespace, the destination namespace is the same.
+<5> Specify a destination namespace if it is different from the source namespace.
+<6> Specify the name of the source cluster `MigCluster` instance.
++
+[IMPORTANT]
+====
+You must ensure that namespaces are not duplicated on the source or the destination clusters because the UID and GID ranges are copied during migration. The following examples will cause a validation error:
+
+----
+spec:
+  namespaces:
+    - namespace_2
+    - namespace_1:namespace_2
+----
+
+----
+spec:
+  namespaces:
+    - namespace_1:namespace_1
+----
+====
 
 . Create the `MigPlan` CR:
 +

modules/migration-mtc-cr-manifests.adoc

@@ -268,6 +268,24 @@ spec:
 
 The `MigPlan` CR defines the parameters of a migration plan. It contains a group of virtual machines that are being migrated with the same parameters.
 
+[IMPORTANT]
+====
+You must ensure that namespaces are not duplicated on the source or the destination clusters because the UID and GID ranges are copied during migration. The following examples will cause a validation error:
+
+----
+spec:
+  namespaces:
+    - namespace_2
+    - namespace_1:namespace_2
+----
+
+----
+spec:
+  namespaces:
+    - namespace_1:namespace_1
+----
+====
+
 [source,yaml]
 ----
 apiVersion: migration.openshift.io/v1alpha1
@@ -298,8 +316,10 @@ spec:
     name: <migstorage_name> <12>
     namespace: openshift-migration
   namespaces:
-  - <namespace>  <13>
-  refresh: false  <14>
+    - <source_namespace_1> <13>
+    - <source_namespace_2>
+    - <source_namespace_3>:<destination_namespace_4> <14>
+  refresh: false  <15>
 ----
 <1> The migration has completed if `true`. You cannot create another `MigMigration` CR for this `MigPlan` CR.
 <2> Specify the name of the source cluster `MigCluster` CR.
@@ -313,8 +333,9 @@ spec:
 <10> Direct image migration is disabled if `true`. Images are copied from the source cluster to the replication repository and from the replication repository to the destination cluster.
 <11> Direct volume migration is disabled if `true`. PVs are copied from the source cluster to the replication repository and from the replication repository to the destination cluster.
 <12> Specify the name of `MigStorage` CR.
-<13> Specify one or more namespaces.
-<14> The `MigPlan` CR is validated if `true`.
+<13> Specify one or more source namespaces. If you specify only the source namespace, the destination namespace is the same.
+<14> Specify the destination namespace if it is different from the source namespace.
+<15> The `MigPlan` CR is validated if `true`.
 
 [id="migstorage_{context}"]
 == MigStorage