From 1e3d705226604aa518faa64c75d841e3c523a596 Mon Sep 17 00:00:00 2001 From: Avital Pinnick Date: Sun, 20 Jun 2021 16:15:13 +0300 Subject: [PATCH] [enterprise-4.7] MIG-743: Advanced migration options --- _topic_map.yml | 4 + migrating_from_ocp_3_to_4/about-mtc-3-4.adoc | 4 - .../advanced-migration-options-3-4.adoc | 46 ++++ .../migrating-applications-3-4.adoc | 52 +--- .../premigration-checklists.adoc | 3 +- .../troubleshooting-3-4.adoc | 4 +- .../about-mtc.adoc | 4 - .../advanced-migration-options-mtc.adoc | 43 ++++ .../migrating-applications-with-mtc.adoc | 52 ---- .../troubleshooting-mtc.adoc | 4 +- ...tion-about-migrating-applications-api.adoc | 112 +++++++++ modules/migration-about-migration-hooks.adoc | 16 +- ...migration-about-mtc-custom-resources.adoc} | 8 +- ...ration-changing-migration-plan-limits.adoc | 4 +- .../migration-configuring-proxy-for-dvm.adoc | 2 +- modules/migration-error-messages.adoc | 14 +- modules/migration-excluding-resources.adoc | 4 +- .../migration-migrating-applications-api.adoc | 160 ++++-------- modules/migration-mtc-cr-manifests.adoc | 233 +++++++++--------- modules/migration-mtc-workflow.adoc | 4 +- modules/migration-prerequisites.adoc | 11 +- ...n-updating-deprecated-internal-images.adoc | 4 +- ...on-using-mtc-crs-for-troubleshooting.adoc} | 8 +- ...gration-writing-ansible-playbook-hook.adoc | 4 +- 24 files changed, 411 insertions(+), 389 deletions(-) create mode 100644 migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc create mode 100644 migration-toolkit-for-containers/advanced-migration-options-mtc.adoc create mode 100644 modules/migration-about-migrating-applications-api.adoc rename modules/{migration-mtc-custom-resources.adoc => migration-about-mtc-custom-resources.adoc} (91%) rename modules/{migration-viewing-migration-crs.adoc => migration-using-mtc-crs-for-troubleshooting.adoc} (95%) diff --git a/_topic_map.yml b/_topic_map.yml index ef1f67e9e99e..e9428f7ae42e 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -1945,6 +1945,8 @@ Topics: File: premigration-checklists - Name: Migrating your applications File: migrating-applications-3-4 +- Name: Advanced migration options + File: advanced-migration-options-3-4 - Name: Troubleshooting File: troubleshooting-3-4 --- @@ -1964,6 +1966,8 @@ Topics: File: premigration-checklists - Name: Migrating your applications File: migrating-applications-with-mtc +- Name: Advanced migration options + File: advanced-migration-options-mtc - Name: Troubleshooting File: troubleshooting-mtc --- 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 ead52001519b..486798832f8a 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 @@ -18,11 +18,7 @@ The {mtc-short} console is installed on the target cluster by default. You can c {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. -You can use migration hooks to run Ansible playbooks at certain points during the migration. The hooks are added when you create a migration plan. - The service catalog is deprecated in {product-title} 4. You can migrate workload resources provisioned with the service catalog from {product-title} 3 to 4 but you cannot perform service catalog actions such as `provision`, `deprovision`, or `update` on these workloads after migration. The {mtc-short} console displays a message if the service catalog resources cannot be migrated. include::modules/migration-mtc-workflow.adoc[leveloffset=+1] -include::modules/migration-mtc-custom-resources.adoc[leveloffset=+1] include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1] -include::modules/migration-about-migration-hooks.adoc[leveloffset=+1] 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 new file mode 100644 index 000000000000..f5f638c9c298 --- /dev/null +++ b/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc @@ -0,0 +1,46 @@ +[id="advanced-migration-options-3-4_{context}"] += Advanced migration options +include::modules/common-attributes.adoc[] +:context: advanced-migration-options-3-4 +:advanced-migration-options-3-4: + +toc::[] + +This section describes advanced options for automating your migration and for modifying the migration plan. + +[discrete] +[id="additional-resources_{context}"] +=== Additional resources + +* xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-mtc-workflow_about-mtc-3-4[{mtc-short} workflow] + +[id="mtc-custom-resources_{context}"] +== {mtc-short} custom resources + +This section describes the custom resources (CRs) that are used by the {mtc-full} ({mtc-short}). + +include::modules/migration-about-mtc-custom-resources.adoc[leveloffset=+2] +include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2] + +[id="migrating-your-applications-api_{context}"] +== Migrating your applications with the {mtc-short} API + +This section describes how to migrate your applications with the {mtc-short} API from the command line interface (CLI). + +include::modules/migration-about-migrating-applications-api.adoc[leveloffset=+2] +include::modules/migration-prerequisites.adoc[leveloffset=+2] +include::modules/migration-configuring-proxy-for-dvm.adoc[leveloffset=+3] +include::modules/migration-migrating-applications-api.adoc[leveloffset=+2] + +[id="migration-hooks_{context}"] +== Migration hooks + +You can use migration hooks to run custom code at certain points during a migration. + +include::modules/migration-about-migration-hooks.adoc[leveloffset=+2] +include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2] + +include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+1] +include::modules/migration-excluding-resources.adoc[leveloffset=+1] + +: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 3457cf66d27c..16a5a0115329 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 @@ -17,15 +17,6 @@ include::modules/migration-prerequisites.adoc[leveloffset=+1] * xref:../migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc#migration-updating-deprecated-internal-images_troubleshooting-3-4[Updating deprecated internal images] include::modules/migration-configuring-proxy-for-dvm.adoc[leveloffset=+2] -include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2] - -[discrete] -[id="additional-resources-for-migration-hooks_{context}"] -=== Additional resources for migration hooks - -* xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-about-migration-hooks_about-mtc-3-4[About migration hooks] -* xref:../migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc#mighook_migrating-applications-3-4[MigHook custom resource] -* xref:../migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc#migplan_migrating-applications-3-4[MigPlan custom resource] [id="migrating-applications-mtc-web-console_{context}"] == Migrating your applications by using the {mtc-short} web console @@ -46,45 +37,4 @@ include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+2] include::modules/migration-running-migration-plan-cam.adoc[leveloffset=+2] -[id="migrating-applications-mtc-cli_{context}"] -== Migrating your applications from the command line - -You can migrate your applications on the command line by creating or editing the {mtc-short} custom resource (CR) manifests. - -You can migrate applications from a local cluster to a remote cluster, from a remote cluster to a local cluster, and between remote clusters. - -[discrete] -[id="cluster-terminology_{context}"] -=== Cluster terminology - -The following terms are relevant for configuring clusters: - -* `host` cluster: -** The `migration-controller` pod runs on the `host` cluster. -** A `host` cluster does not require an exposed secure registry route for direct image migration. -* Local cluster: The local cluster is often the same as the `host` cluster but this is not a requirement. -* Remote cluster: -** A remote cluster must have an exposed secure registry route for direct image migration. -** A remote cluster must have a `Secret` CR containing the `migration-controller` service account token. - -The following terms are relevant for performing a migration: - -* Source cluster: Cluster from which the applications are migrated. -* Destination cluster: Cluster to which the applications are migrated. - -include::modules/migration-migrating-applications-api.adoc[leveloffset=+2] -include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2] - -[discrete] -[id="additional-resources-for-custom-resources_{context}"] -=== Additional resources for custom resources - -* xref:../migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc#migration-viewing-migration-crs_troubleshooting-3-4[Viewing migration custom resources] - -[id="configuring-migration-plan_{context}"] -== Configuring a migration plan - -You can increase the number of objects to be migrated or exclude resources from the migration. - -include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2] -include::modules/migration-excluding-resources.adoc[leveloffset=+2] +:migrating-applications-3-4!: diff --git a/migrating_from_ocp_3_to_4/premigration-checklists.adoc b/migrating_from_ocp_3_to_4/premigration-checklists.adoc index 78319ef4925e..03fccc3e9138 100644 --- a/migrating_from_ocp_3_to_4/premigration-checklists.adoc +++ b/migrating_from_ocp_3_to_4/premigration-checklists.adoc @@ -48,7 +48,8 @@ Even if the pods are in a *Running* state, a high restart count might indicate u $ oc adm prune images ---- -* [ ] The internal container image registry uses a link:https://docs.openshift.com/container-platform/3.11/scaling_performance/optimizing_storage.html#registry[supported storage type]. +* [ ] The internal registry uses a link:https://docs.openshift.com/container-platform/3.11/scaling_performance/optimizing_storage.html#registry[supported storage type]. +* [ ] Direct image migration only: The internal registry is link:https://docs.openshift.com/container-platform/3.11/install_config/registry/securing_and_exposing_registry.html#exposing-the-registry[exposed] to external traffic. * [ ] You can read and write images to the registry. * [ ] The link:https://access.redhat.com/articles/3093761[etcd cluster] is healthy. * [ ] The link:https://docs.openshift.com/container-platform/3.11/install_config/master_node_configuration.html#master-node-configuration-node-qps-burst[average API server response time] on the source cluster is less than 50 ms. 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 e35772223839..7da156abac9f 100644 --- a/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc +++ b/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc @@ -18,14 +18,14 @@ include::modules/migration-using-mig-log-reader.adoc[leveloffset=+2] include::modules/migration-using-must-gather.adoc[leveloffset=+2] include::modules/migration-debugging-velero-resources.adoc[leveloffset=+2] include::modules/migration-partial-failure-velero.adoc[leveloffset=+2] -include::modules/migration-viewing-migration-crs.adoc[leveloffset=+2] +include::modules/migration-using-mtc-crs-for-troubleshooting.adoc[leveloffset=+2] [discrete] [id="additional-resources-for-debugging-tools_{context}"] === Additional resources for debugging tools * xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-mtc-workflow_about-mtc-3-4[{mtc-short} workflow] -* xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-mtc-custom-resources_about-mtc-3-4[{mtc-short} custom resources] +* xref:../migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc#mtc-custom-resources_advanced-migration-options-3-4[{mtc-short} custom resources] [id="common-issues-and-concerns_{context}"] == Common issues and concerns diff --git a/migration-toolkit-for-containers/about-mtc.adoc b/migration-toolkit-for-containers/about-mtc.adoc index 32c173af561d..ffa5aea9c7b0 100644 --- a/migration-toolkit-for-containers/about-mtc.adoc +++ b/migration-toolkit-for-containers/about-mtc.adoc @@ -11,9 +11,5 @@ The {mtc-short} console is installed on the target cluster by default. You can c {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. -You can use migration hooks to run Ansible playbooks at certain points during the migration. The hooks are added when you create a migration plan. - include::modules/migration-mtc-workflow.adoc[leveloffset=+1] -include::modules/migration-mtc-custom-resources.adoc[leveloffset=+1] include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1] -include::modules/migration-about-migration-hooks.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 new file mode 100644 index 000000000000..6fa751e0d093 --- /dev/null +++ b/migration-toolkit-for-containers/advanced-migration-options-mtc.adoc @@ -0,0 +1,43 @@ +[id="advanced-migration-options-mtc_{context}"] += Advanced migration options +include::modules/common-attributes.adoc[] +:context: advanced-migration-options-mtc + +toc::[] + +This section describes advanced options for automating your migration and for modifying the migration plan. + +[discrete] +[id="additional-resources_{context}"] +=== Additional resources + +* xref:../migration-toolkit-for-containers/about-mtc.adoc#migration-mtc-workflow_about-mtc[{mtc-short} workflow] + +[id="mtc-custom-resources_{context}"] +== {mtc-short} custom resources + +This section describes the custom resources (CRs) that are used by the {mtc-full} ({mtc-short}). + +include::modules/migration-about-mtc-custom-resources.adoc[leveloffset=+2] +include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2] + +[id="migrating-your-applications-api_{context}"] +== Migrating your applications with the {mtc-short} API + +This section describes how to migrate your applications with the {mtc-short} API from the command line interface (CLI). + +include::modules/migration-about-migrating-applications-api.adoc[leveloffset=+2] +include::modules/migration-prerequisites.adoc[leveloffset=+2] +include::modules/migration-configuring-proxy-for-dvm.adoc[leveloffset=+3] +include::modules/migration-migrating-applications-api.adoc[leveloffset=+2] + +[id="migration-hooks_{context}"] +== Migration hooks + +You can use migration hooks to run custom code at certain points during a migration. + +include::modules/migration-about-migration-hooks.adoc[leveloffset=+2] +include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2] + +include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+1] +include::modules/migration-excluding-resources.adoc[leveloffset=+1] diff --git a/migration-toolkit-for-containers/migrating-applications-with-mtc.adoc b/migration-toolkit-for-containers/migrating-applications-with-mtc.adoc index ce4832c35ea0..91ee90ba3efa 100644 --- a/migration-toolkit-for-containers/migrating-applications-with-mtc.adoc +++ b/migration-toolkit-for-containers/migrating-applications-with-mtc.adoc @@ -9,15 +9,6 @@ You can migrate your applications by using the {mtc-full} ({mtc-short}) web cons include::modules/migration-prerequisites.adoc[leveloffset=+1] include::modules/migration-configuring-proxy-for-dvm.adoc[leveloffset=+2] -include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2] - -[discrete] -[id="additional-resources-for-migration-hooks_{context}"] -=== Additional resources for migration hooks - -* xref:../migration-toolkit-for-containers/about-mtc.adoc#migration-about-migration-hooks_about-mtc[About migration hooks] -* xref:../migration-toolkit-for-containers/migrating-applications-with-mtc.adoc#mighook_migrating-applications-with-mtc[MigHook custom resource] -* xref:../migration-toolkit-for-containers/migrating-applications-with-mtc#migplan_migrating-applications-with-mtc[MigPlan custom resource] [id="migrating-applications-mtc-web-console_{context}"] == Migrating your applications by using the {mtc-short} web console @@ -37,46 +28,3 @@ include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+2] * xref:../migration-toolkit-for-containers/about-mtc.adoc#snapshot-copy-method_about-mtc[{mtc-short} snapshot copy method] include::modules/migration-running-migration-plan-cam.adoc[leveloffset=+2] - -[id="migrating-applications-mtc-cli_{context}"] -== Migrating your applications from the command line - -You can migrate your applications on the command line by creating or editing the {mtc-short} custom resource (CR) manifests. - -You can migrate applications from a local cluster to a remote cluster, from a remote cluster to a local cluster, and between remote clusters. - -[discrete] -[id="cluster-terminology_{context}"] -=== Cluster terminology - -The following terms are relevant for configuring clusters: - -* `host` cluster: -** The `migration-controller` pod runs on the `host` cluster. -** A `host` cluster does not require an exposed secure registry route for direct image migration. -* Local cluster: The local cluster is often the same as the `host` cluster but this is not a requirement. -* Remote cluster: -** A remote cluster must have an exposed secure registry route for direct image migration. -** A remote cluster must have a `Secret` CR containing the `migration-controller` service account token. - -The following terms are relevant for performing a migration: - -* Source cluster: Cluster from which the applications are migrated. -* Destination cluster: Cluster to which the applications are migrated. - -include::modules/migration-migrating-applications-api.adoc[leveloffset=+2] -include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2] - -[discrete] -[id="additional-resources-for-custom-resources_{context}"] -=== Additional resources for custom resources - -* xref:../migration-toolkit-for-containers/troubleshooting-mtc.adoc#migration-viewing-migration-crs_troubleshooting-mtc[Viewing migration custom resources] - -[id="configuring-migration-plan_{context}"] -== Configuring a migration plan - -You can increase the number of objects to be migrated or exclude resources from the migration. - -include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2] -include::modules/migration-excluding-resources.adoc[leveloffset=+2] diff --git a/migration-toolkit-for-containers/troubleshooting-mtc.adoc b/migration-toolkit-for-containers/troubleshooting-mtc.adoc index 210a8ce209ea..9a175e90ad2d 100644 --- a/migration-toolkit-for-containers/troubleshooting-mtc.adoc +++ b/migration-toolkit-for-containers/troubleshooting-mtc.adoc @@ -18,14 +18,14 @@ include::modules/migration-using-mig-log-reader.adoc[leveloffset=+2] include::modules/migration-using-must-gather.adoc[leveloffset=+2] include::modules/migration-debugging-velero-resources.adoc[leveloffset=+2] include::modules/migration-partial-failure-velero.adoc[leveloffset=+2] -include::modules/migration-viewing-migration-crs.adoc[leveloffset=+2] +include::modules/migration-using-mtc-crs-for-troubleshooting.adoc[leveloffset=+2] [discrete] [id="additional-resources-for-debugging-tools_{context}"] === Additional resources for debugging tools * xref:../migration-toolkit-for-containers/about-mtc.adoc#migration-mtc-workflow_about-mtc[{mtc-short} workflow] -* xref:../migration-toolkit-for-containers/about-mtc.adoc#migration-mtc-custom-resources_about-mtc[{mtc-short} custom resources] +* xref:../migration-toolkit-for-containers/advanced-migration-options-mtc.adoc#mtc-custom-resources_advanced-migration-options-mtc[{mtc-short} custom resources] [id="common-issues-and-concerns_{context}"] == Common issues and concerns diff --git a/modules/migration-about-migrating-applications-api.adoc b/modules/migration-about-migrating-applications-api.adoc new file mode 100644 index 000000000000..bf584a61d5e3 --- /dev/null +++ b/modules/migration-about-migrating-applications-api.adoc @@ -0,0 +1,112 @@ +// Module included in the following assemblies: +// +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration-toolkit-for-containers/advanced-migration-options-mtc.adoc + +[id="migration-about-migrating-applications-api_{context}"] += About migrating applications + +You can migrate applications from a local cluster to a remote cluster, from a remote cluster to a local cluster, and between remote clusters. + +[id="terminology_{context}"] +== Terminology + +Source cluster:: +* Cluster from which the applications are migrated. + +Destination cluster:: +* Cluster to which the applications are migrated. + +Replication repository:: +* Object storage. +* Requires network access to all clusters. + +Indirect migration:: +* Images, volumes, and Kubernetes objects are copied from the source cluster to the replication repository and then from the replication repository to the destination cluster. + +Direct volume migration:: +* Volumes are copied directly from the source cluster to the destination cluster. +* Significantly faster than indirect migration. + +Direct image migration:: +* Images are copied directly from the source cluster to the destination cluster. +* Significantly faster than indirect migration. + +Host cluster:: +* Cluster on which the `migration-controller` pod and the web console run. +* Usually the same as the destination cluster and the local cluster but this is not a requirement. +* Does not require an exposed secure registry route for direct image migration. + +Local cluster:: +* Usually the same as the destination cluster and the host cluster but this is not a requirement. + +Remote cluster:: +* Usually the same as the source cluster but this is not a requirement. +* Requires an exposed secure registry route for direct image migration. +* Requires a `Secret` CR containing the `migration-controller` service account token. + +[id="mapping-destination-namespaces-in-the-migplan-custom-resource_{context}"] +== Mapping destination namespaces in the MigPlan custom resource (CR) + +If you map destination namespaces in the `MigPlan` CR, you must ensure that the namespaces are not duplicated on the source or the destination clusters because the UID and GID ranges of the namespaces are copied during migration. + +The following examples will cause validation errors: + +.Two source namespaces mapped to the same destination namespace +[source,yaml] +---- +spec: + namespaces: + - namespace_2 + - namespace_1:namespace_2 +---- + +.Source namespace mapped to duplicate namespace +[source,yaml] +---- +spec: + namespaces: + - namespace_1:namespace_1 +---- + +[id="using-migmigration-crs-for-stage-migration-cancellation-and-rollback_{context}"] +== Stage migration, migration cancellation, and migration rollback + +You can create and associate multiple `MigMigration` custom resources (CRs) with the same `MigPlan` CR for the following use cases: + +* To perform stage migrations, which copy most of the data without stopping the application, before running a migration. Stage migrations improve the performance of the migration. +* To cancel a migration in progress. +* To roll back a completed migration. + +[id="creating-registry-route-for-direct-image-migration_{context}"] +== Creating a registry route for direct image migration + +For direct image migration, you must create a route to the exposed internal registry on all remote clusters. + +.Prerequisites + +* The internal registry must be exposed to external traffic on all remote clusters. ++ +The {product-title} 4 registry is exposed by default. +ifdef::advanced-migration-options-3-4[] ++ +The {product-title} 3 registry must be link:https://docs.openshift.com/container-platform/3.11/install_config/registry/securing_and_exposing_registry.html#exposing-the-registry[exposed manually]. +endif::[] + +.Procedure + +ifdef::advanced-migration-options-3-4[] +* To create a route to an {product-title} 3 registry, run the following command: ++ +[source,terminal] +---- +$ oc create route passthrough --service=docker-registry --port=5000 -n default +---- +endif::[] + +* To create a route to an {product-title} 4 registry, run the following command: ++ +[source,terminal] +---- +$ oc create route passthrough --service=image-registry --port=5000 -n openshift-image-registry +---- diff --git a/modules/migration-about-migration-hooks.adoc b/modules/migration-about-migration-hooks.adoc index 3c3863615587..b36e31e1e0b7 100644 --- a/modules/migration-about-migration-hooks.adoc +++ b/modules/migration-about-migration-hooks.adoc @@ -1,14 +1,12 @@ // Module included in the following assemblies: // -// * migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc -// * migration-toolkit-for-containers/migrating-applications-with-mtc.adoc +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration-toolkit-for-containers/advanced-migration-options-mtc.adoc [id="migration-about-migration-hooks_{context}"] = About migration hooks -You can use migration hooks to run custom code at certain points during a migration with the {mtc-full} ({mtc-short}). You can add up to four migration hooks to a single migration plan, with each hook running at a different phase of the migration. - -Migration hooks perform tasks such as customizing application quiescence, manually migrating unsupported data types, and updating applications after migration. +You can add up to four migration hooks to a single migration plan, with each hook running at a different phase of the migration. Migration hooks perform tasks such as customizing application quiescence, manually migrating unsupported data types, and updating applications after migration. A migration hook runs on a source or a target cluster at one of the following migration steps: @@ -17,16 +15,14 @@ A migration hook runs on a source or a target cluster at one of the following mi * `PreRestore`: Before resources are restored on the target cluster * `PostRestore`: After resources are restored on the target cluster -You can create a hook by using an Ansible playbook or a custom hook container. +You can create a hook by creating an Ansible playbook that runs with the default Ansible image or with a custom hook container. .Ansible playbook -The Ansible playbook is mounted on a hook container as a config map. The hook container runs as a job, using the cluster, service account, and namespace specified in the `MigPlan` custom resource (CR). The job continues to run until it reaches the the default limit of 6 retries or a successful completion. This continues even if the initial pod is evicted or killed. +The Ansible playbook is mounted on a hook container as a config map. The hook container runs as a job, using the cluster, service account, and namespace specified in the `MigPlan` custom resource. The job continues to run until it reaches the default limit of 6 retries or a successful completion. This continues even if the initial pod is evicted or killed. The default Ansible runtime image is `registry.redhat.io/rhmtc/openshift-migration-hook-runner-rhel7:{mtc-version}`. This image is based on the Ansible Runner image and includes `python-openshift` for Ansible Kubernetes resources and an updated `oc` binary. -Optional: You can use a custom Ansible runtime image containing additional Ansible modules or tools instead of the default image. - .Custom hook container -You can create a custom hook container that includes Ansible playbooks or custom code. +You can use a custom hook container instead of the default Ansible image. diff --git a/modules/migration-mtc-custom-resources.adoc b/modules/migration-about-mtc-custom-resources.adoc similarity index 91% rename from modules/migration-mtc-custom-resources.adoc rename to modules/migration-about-mtc-custom-resources.adoc index 32a7c1c857ee..9ffad4b214a8 100644 --- a/modules/migration-mtc-custom-resources.adoc +++ b/modules/migration-about-mtc-custom-resources.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: // -// * migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc -// * migration-toolkit-for-containers/migrating-applications-with-mtc.adoc +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration-toolkit-for-containers/advanced-migration-options-mtc.adoc -[id="migration-mtc-custom-resources_{context}"] -= {mtc-full} custom resources +[id="migration-about-mtc-custom-resources_{context}"] += About {mtc-short} custom resources The {mtc-full} ({mtc-short}) creates the following custom resources (CRs): diff --git a/modules/migration-changing-migration-plan-limits.adoc b/modules/migration-changing-migration-plan-limits.adoc index 5cb53e131b7b..3dc2382e9201 100644 --- a/modules/migration-changing-migration-plan-limits.adoc +++ b/modules/migration-changing-migration-plan-limits.adoc @@ -1,7 +1,7 @@ // Module included in the following assemblies: // -// * migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc -// * migration-toolkit-for-containers/migrating-applications-with-mtc +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration-toolkit-for-containers/advanced-migration-options-mtc.adoc [id="migration-changing-migration-plan-limits_{context}"] = Increasing limits for large migrations diff --git a/modules/migration-configuring-proxy-for-dvm.adoc b/modules/migration-configuring-proxy-for-dvm.adoc index 0dc1851cf358..521794f0ff18 100644 --- a/modules/migration-configuring-proxy-for-dvm.adoc +++ b/modules/migration-configuring-proxy-for-dvm.adoc @@ -4,7 +4,7 @@ // * migration-toolkit-for-containers/migrating-applications-with-mtc [id="migration-configuring-proxy-for-dvm_{context}"] -= Configuring a proxy for direct volume migration += Configuring an Stunnel proxy for direct volume migration If you are performing direct volume migration from a source cluster behind a proxy, you must configure an Stunnel proxy in the `MigrationController` custom resource (CR). Stunnel creates a transparent tunnel between the source and target clusters for the TCP connection without changing the certificates. diff --git a/modules/migration-error-messages.adoc b/modules/migration-error-messages.adoc index 4cd08a57660a..eae0e2ac8076 100644 --- a/modules/migration-error-messages.adoc +++ b/modules/migration-error-messages.adoc @@ -8,7 +8,7 @@ This section describes common error messages you might encounter with the {mtc-full} ({mtc-short}) and how to resolve their underlying causes. -[discrete] +[id="ca-certificate-error-displayed-when-accessing-console-for-first-time_{context}"] == CA certificate error displayed when accessing the {mtc-short} console for the first time If the {mtc-short} console displays a `CA certificate error` message the first time you try to access it, the likely cause is that a cluster uses self-signed CA certificates. @@ -17,7 +17,7 @@ Navigate to the `oauth-authorization-server` URL in the error message and accept If the browser displays an `Unauthorized` message after you have accepted the CA certificate, navigate to the {mtc-short} console and then refresh the web page. -[discrete] +[id="oauth-timeout-error-in-console_{context}"] == OAuth timeout error in the {mtc-short} console If the {mtc-short} console displays a `connection has timed out` message after you have accepted a self-signed certificate, the cause is likely to be one of the following: @@ -31,7 +31,7 @@ To determine the cause: * Inspect the {mtc-short} console web page with a browser web inspector. * Check the `Migration UI` pod log for errors. -[discrete] +[id="certificate-signed-by-unknown-authority-error_{context}"] == Certificate signed by unknown authority error If you use a self-signed certificate to secure a cluster or a replication repository for the {mtc-full} ({mtc-short}), certificate verification might fail with the following error message: `Certificate signed by unknown authority`. @@ -50,7 +50,7 @@ $ echo -n | openssl s_client -connect : \ <1> <1> Specify the host FQDN and port of the endpoint, for example, `api.my-cluster.example.com:6443`. <2> Specify the name of the CA bundle file. -[discrete] +[id="backup-storage-location-errors-in-velero-pod-log_{context}"] == Backup storage location errors in the Velero pod log If a `Velero` `Backup` custom resource contains a reference to a backup storage location (BSL) that does not exist, the `Velero` pod log might display the following error messages: @@ -64,7 +64,7 @@ Error getting backup storage location: backupstoragelocation.velero.io \"my-bsl\ You can ignore these error messages. A missing BSL cannot cause a migration to fail. -[discrete] +[id="pod-volume-backup-timeout-error-in-velero-pod-log_{context}"] == Pod volume backup timeout error in the Velero pod log If a migration fails because `Restic` times out, the `Velero` pod log displays the following error: @@ -95,7 +95,7 @@ spec: . Click *Save*. -[discrete] +[id="restic-verification-errors-in-migmigration-custom-resource_{context}"] == Restic verification errors in the MigMigration custom resource If data verification fails when migrating a persistent volume with the file system data copy method, the `MigMigration` CR displays the following error: @@ -176,7 +176,7 @@ The output identifies the `Restic` pod that logged the errors. $ oc logs -f ---- -[discrete] +[id="restic-permission-error-when-migrating-from-nfs-storage-with-root-squash-enabled_{context}"] == Restic permission error when migrating from NFS storage with root_squash enabled If you are migrating data from NFS storage and `root_squash` is enabled, `Restic` maps to `nfsnobody` and does not have permission to perform the migration. The `Restic` pod log displays the following error: diff --git a/modules/migration-excluding-resources.adoc b/modules/migration-excluding-resources.adoc index 4b6d920c59e8..4105d38ac0e7 100644 --- a/modules/migration-excluding-resources.adoc +++ b/modules/migration-excluding-resources.adoc @@ -1,7 +1,7 @@ // Module included in the following assemblies: // -// * migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc -// * migration-toolkit-for-containers/migrating-applications-with-mtc +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration-toolkit-for-containers/advanced-migration-options-mtc.adoc [id="migration-excluding-resources_{context}"] = Excluding resources from a migration plan diff --git a/modules/migration-migrating-applications-api.adoc b/modules/migration-migrating-applications-api.adoc index 33854fc9b68b..3f87b0188388 100644 --- a/modules/migration-migrating-applications-api.adoc +++ b/modules/migration-migrating-applications-api.adoc @@ -1,56 +1,20 @@ // Module included in the following assemblies: // -// * migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc -// * migration-toolkit-for-containers/migrating-applications-with-mtc +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration-toolkit-for-containers/advanced-migration-options-mtc.adoc [id="migration-migrating-applications-api_{context}"] -= Migrating your applications with the {mtc-full} API += Migrating your applications from the command line -You can migrate your applications on the command line with the {mtc-full} ({mtc-short}) API. - -You can migrate applications from a local cluster to a remote cluster, from a remote cluster to a local cluster, and between remote clusters. - -This procedure describes how to perform indirect migration and direct migration: - -* Indirect migration: Images, volumes, and Kubernetes objects are copied from the source cluster to the replication repository and then from the replication repository to the destination cluster. -* Direct migration: Images or volumes are copied directly from the source cluster to the destination cluster. Direct image migration and direct volume migration have significant performance benefits. - -You create the following custom resources (CRs) to perform a migration: - -* `MigCluster` CR: Defines a `host`, local, or remote cluster -+ -The `migration-controller` pod runs on the `host` cluster. - -* `Secret` CR: Contains credentials for a remote cluster or storage -* `MigStorage` CR: Defines a replication repository -+ -Different storage providers require different parameters in the `MigStorage` CR manifest. - -* `MigPlan` CR: Defines a migration plan -* `MigMigration` CR: Performs a migration defined in an associated `MigPlan` -+ -You can create multiple `MigMigration` CRs for a single `MigPlan` CR for the following purposes: -+ -* To perform stage migrations, which copy most of the data without stopping the application, before running a migration. Stage migrations improve the performance of the migration. -* To cancel a migration in progress -* To roll back a completed migration - -.Prerequisites - -* You must have `cluster-admin` privileges for all clusters. -* You must install the {product-title} CLI (`oc`). -* You must install the {mtc-full} Operator on all clusters. -* The _version_ of the installed {mtc-full} Operator must be the same on all clusters. -* You must configure an object storage as a replication repository. -* If you are using direct image migration, you must expose a secure registry route on all remote clusters. -* If you are using direct volume migration, the source cluster must not have an HTTP proxy configured. +You can migrate your applications from the command line with the {mtc-full} ({mtc-short}) API. .Procedure -. Create a `MigCluster` CR manifest for the `host` cluster called `host-cluster.yaml`: +. Create a `MigCluster` CR manifest for the host cluster: + [source,yaml] ---- +$ cat << EOF | oc apply -f - apiVersion: migration.openshift.io/v1alpha1 kind: MigCluster metadata: @@ -58,19 +22,14 @@ metadata: namespace: openshift-migration spec: isHostCluster: true +EOF ---- -. Create a `MigCluster` CR for the `host` cluster: -+ -[source,terminal] ----- -$ oc create -f host-cluster.yaml -n openshift-migration ----- - -. Create a `Secret` CR manifest for each remote cluster called `cluster-secret.yaml`: +. Create a `Secret` CR manifest for each remote cluster: + [source,yaml] ---- +$ cat << EOF | oc apply -f - apiVersion: v1 kind: Secret metadata: @@ -79,52 +38,40 @@ metadata: type: Opaque data: saToken: <1> +EOF ---- -<1> Specify the base64-encoded `migration-controller` service account (SA) token of the remote cluster. -+ -You can obtain the SA token by running the following command: +<1> Specify the base64-encoded `migration-controller` service account (SA) token of the remote cluster. You can obtain the token by running the following command: + [source,terminal] ---- $ oc sa get-token migration-controller -n openshift-migration | base64 -w 0 ---- -. Create a `Secret` CR for each remote cluster: -+ -[source,terminal] ----- -$ oc create -f cluster-secret.yaml ----- - -. Create a `MigCluster` CR manifest for each remote cluster called `remote-cluster.yaml`: +. Create a `MigCluster` CR manifest for each remote cluster: + [source,yaml] ---- +$ cat << EOF | oc apply -f - apiVersion: migration.openshift.io/v1alpha1 kind: MigCluster metadata: - name: + name: <.> namespace: openshift-migration spec: - exposedRegistryPath: <1> - insecure: false <2> + exposedRegistryPath: <.> + insecure: false <.> isHostCluster: false serviceAccountSecretRef: - name: <3> + name: <.> namespace: openshift-config - url: <4> ----- -<1> Optional: Specify the exposed registry route, for example, `docker-registry-default.apps.example.com` if you are using direct image migration. -<2> SSL verification is enabled if `false`. CA certificates are not required or checked if `true`. -<3> Specify the `Secret` CR of the remote cluster. -<4> Specify the URL of the remote cluster. - -. Create a `MigCluster` CR for each remote cluster: -+ -[source,terminal] ----- -$ oc create -f remote-cluster.yaml -n openshift-migration ----- + url: <.> +EOF +---- +<.> Specify the `Cluster` CR of the remote cluster. +<.> Optional: For direct image migration, specify the exposed registry route. +<.> SSL verification is enabled if `false`. CA certificates are not required or checked if `true`. +<.> Specify the `Secret` CR of the remote cluster. +<.> Specify the URL of the remote cluster. . Verify that all clusters are in a `Ready` state: + @@ -133,10 +80,11 @@ $ oc create -f remote-cluster.yaml -n openshift-migration $ oc describe cluster ---- -. Create a `Secret` CR manifest for the replication repository called `storage-secret.yaml`: +. Create a `Secret` CR manifest for the replication repository: + [source,yaml] ---- +$ cat << EOF | oc apply -f - apiVersion: v1 kind: Secret metadata: @@ -146,11 +94,12 @@ type: Opaque data: aws-access-key-id: <1> aws-secret-access-key: <2> +EOF ---- <1> Specify the key ID in base64 format. <2> Specify the secret key in base64 format. + -AWS credentials are base64-encoded by default. If you are using another storage provider, you must encode your credentials by running the following command with each key: +AWS credentials are base64-encoded by default. For other storage providers, you must encode your credentials by running the following command with each key: + [source,terminal] ---- @@ -158,17 +107,11 @@ $ echo -n "" | base64 -w 0 <1> ---- <1> Specify the key ID or the secret key. Both keys must be base64-encoded. -. Create the `Secret` CR for the replication repository: -+ -[source,terminal] ----- -$ oc create -f storage-secret.yaml ----- - -. Create a `MigStorage` CR manifest for the replication repository called `migstorage.yaml`: +. Create a `MigStorage` CR manifest for the replication repository: + [source,yaml] ---- +$ cat << EOF | oc apply -f - apiVersion: migration.openshift.io/v1alpha1 kind: MigStorage metadata: @@ -186,6 +129,7 @@ spec: name: <4> namespace: openshift-config volumeSnapshotProvider: <5> +EOF ---- <1> Specify the bucket name. <2> Specify the `Secrets` CR of the object storage. You must ensure that the credentials stored in the `Secrets` CR of the object storage are correct. @@ -193,24 +137,18 @@ spec: <4> Optional: If you are copying data by using snapshots, specify the `Secrets` CR of the object storage. You must ensure that the credentials stored in the `Secrets` CR of the object storage are correct. <5> Optional: If you are copying data by using snapshots, specify the storage provider. -. Create the `MigStorage` CR: -+ -[source,terminal] ----- -$ oc create -f migstorage.yaml -n openshift-migration ----- - . Verify that the `MigStorage` CR is in a `Ready` state: + [source,terminal] ---- -$ oc describe migstorage +$ oc describe migstorage ---- -. Create a `MigPlan` CR manifest called `migplan.yaml`: +. Create a `MigPlan` CR manifest: + [source,yaml] ---- +$ cat << EOF | oc apply -f - apiVersion: migration.openshift.io/v1alpha1 kind: MigPlan metadata: @@ -230,31 +168,27 @@ spec: srcMigClusterRef: name: <5> namespace: openshift-migration +EOF ---- <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. - -. Create the `MigPlan` CR: -+ -[source,terminal] ----- -$ oc create -f migplan.yaml -n openshift-migration ----- +<4> Specify one or more source namespaces. By default, the destination namespace has the same name. +<5> Specify a destination namespace if it is different from the source namespace. +<6> Specify the name of the source cluster `MigCluster` instance. -. View the `MigPlan` instance to verify that it is in a `Ready` state: +. Verify that the `MigPlan` instance is in a `Ready` state: + [source,terminal] ---- $ oc describe migplan -n openshift-migration ---- -. Create a `MigMigration` CR manifest called `migmigration.yaml`: +. Create a `MigMigration` CR manifest to start the migration defined in the `MigPlan` instance: + [source,yaml] ---- +$ cat << EOF | oc apply -f - apiVersion: migration.openshift.io/v1alpha1 kind: MigMigration metadata: @@ -267,20 +201,14 @@ spec: quiescePods: true <2> stage: false <3> rollback: false <4> +EOF ---- <1> Specify the `MigPlan` CR name. <2> The pods on the source cluster are stopped before migration if `true`. <3> A stage migration, which copies most of the data without stopping the application, is performed if `true`. <4> A completed migration is rolled back if `true`. -. Create the `MigMigration` CR to start the migration defined in the `MigPlan` CR: -+ -[source,terminal] ----- -$ oc create -f migmigration.yaml -n openshift-migration ----- - -. Verify the progress of the migration by watching the `MigMigration` CR: +. Verify the migration by watching the `MigMigration` CR progress: + [source,terminal] ---- diff --git a/modules/migration-mtc-cr-manifests.adoc b/modules/migration-mtc-cr-manifests.adoc index e4944944a4f7..2dd00db37c90 100644 --- a/modules/migration-mtc-cr-manifests.adoc +++ b/modules/migration-mtc-cr-manifests.adoc @@ -6,7 +6,7 @@ [id="migration-mtc-cr-manifests_{context}"] = {mtc-short} custom resource manifests -{mtc-full} ({mtc-short}) uses the following custom resource (CR) manifests to create CRs for migrating applications. +{mtc-full} ({mtc-short}) uses the following custom resource (CR) manifests for migrating applications. [id="directimagemigration_{context}"] == DirectImageMigration @@ -23,17 +23,17 @@ metadata: name: spec: srcMigClusterRef: - name: <1> + name: namespace: openshift-migration destMigClusterRef: - name: <2> + name: namespace: openshift-migration namespaces: - - <3> + - + - : <2> ---- -<1> Specify the `MigCluster` CR name of the source cluster. -<2> Specify the `MigCluster` CR name of the destination cluster. -<3> Specify one or more namespaces containing images to be migrated. +<1> One or more namespaces containing images to be migrated. By default, the destination namespace has the same name as the source namespace. +<2> Source namespace mapped to a destination namespace with a different name. [id="directimagestreammigration_{context}"] == DirectImageStreamMigration @@ -50,21 +50,16 @@ metadata: name: directimagestreammigration_name spec: srcMigClusterRef: - name: <1> + name: namespace: openshift-migration destMigClusterRef: - name: <2> + name: namespace: openshift-migration imageStreamRef: - name: <3> - namespace: <4> - destNamespace: <5> + name: + namespace: + destNamespace: ---- -<1> Specify the `MigCluster` CR name of the source cluster. -<2> Specify the `MigCluster` CR name of the destination cluster. -<3> Specify the image stream name. -<4> Specify the image stream namespace on the source cluster. -<5> Specify the image stream namespace on the destination cluster. [id="directvolumemigration_{context}"] == DirectVolumeMigration @@ -86,17 +81,15 @@ spec: namespace: openshift-migration persistentVolumeClaims: - name: <4> - namespace: <5> + namespace: srcMigClusterRef: - name: <6> + name: namespace: openshift-migration ---- -<1> Namespaces are created for the PVs on the destination cluster if `true`. -<2> The `DirectVolumeMigrationProgress` CRs are deleted after migration if `true`. The default value is `false` so that `DirectVolumeMigrationProgress` CRs are retained for troubleshooting. +<1> Set to `true` to create namespaces for the PVs on the destination cluster. +<2> Set to `true` to delete `DirectVolumeMigrationProgress` CRs after migration. The default is `false` so that `DirectVolumeMigrationProgress` CRs are retained for troubleshooting. <3> Update the cluster name if the destination cluster is not the host cluster. -<4> Specify one or more PVCs to be migrated with direct volume migration. -<5> Specify the namespace of each PVC. -<6> Specify the `MigCluster` CR name of the source cluster. +<4> Specify one or more PVCs to be migrated. [id="directvolumemigrationprogress_{context}"] == DirectVolumeMigrationProgress @@ -110,20 +103,22 @@ kind: DirectVolumeMigrationProgress metadata: labels: controller-tools.k8s.io: "1.0" - name: directvolumemigrationprogress_name + name: spec: clusterRef: - name: source_cluster + name: namespace: openshift-migration podRef: - name: rsync_pod + name: namespace: openshift-migration ---- [id="miganalytic_{context}"] == MigAnalytic -The `MigAnalytic` CR collects the number of images, Kubernetes resources, and the PV capacity from an associated `MigPlan` CR. +The `MigAnalytic` CR collects the number of images, Kubernetes resources, and the persistent volume (PV) capacity from an associated `MigPlan` CR. + +You can configure the data that it collects. [source,yaml] ---- @@ -131,29 +126,26 @@ apiVersion: migration.openshift.io/v1alpha1 kind: MigAnalytic metadata: annotations: - migplan: <1> + migplan: name: miganalytic_name namespace: openshift-migration labels: - migplan: <2> + migplan: spec: - analyzeImageCount: true <3> - analyzeK8SResources: true <4> - analyzePVCapacity: true <5> - listImages: false <6> - listImagesLimit: 50 <7> + analyzeImageCount: true <.> + analyzeK8SResources: true <.> + analyzePVCapacity: true <.> + listImages: false <.> + listImagesLimit: 50 <.> migPlanRef: - name: migplan_name <8> + name: namespace: openshift-migration ---- -<1> Specify the `MigPlan` CR name associated with the `MigAnalytic` CR. -<2> Specify the `MigPlan` CR name associated with the `MigAnalytic` CR. -<3> Optional: The number of images is returned if `true`. -<4> Optional: Returns the number, kind, and API version of the Kubernetes resources if `true`. -<5> Optional: Returns the PV capacity if `true`. -<6> Returns a list of image names if `true`. Default is `false` so that the output is not excessively long. -<7> Optional: Specify the maximum number of image names to return if `listImages` is `true`. -<8> Specify the `MigPlan` CR name associated with the `MigAnalytic` CR. +<.> Optional: Returns the number of images. +<.> Optional: Returns the number, kind, and API version of the Kubernetes resources. +<.> Optional: Returns the PV capacity. +<.> Returns a list of image names. The default is `false` so that the output is not excessively long. +<.> Optional: Specify the maximum number of image names to return if `listImages` is `true`. [id="migcluster_{context}"] == MigCluster @@ -176,30 +168,33 @@ spec: insecure: false <5> refresh: false <6> # The 'restartRestic' parameter is relevant for a source cluster. -# restartRestic: true <7> + restartRestic: true <7> # The following parameters are relevant for a remote cluster. -# isHostCluster: false -# exposedRegistryPath: <8> -# url: <9> -# serviceAccountSecretRef: -# name: <10> -# namespace: openshift-config + exposedRegistryPath: <8> + url: <9> + serviceAccountSecretRef: + name: <10> + namespace: openshift-config ---- -<1> Optional: Update the cluster name if the `migration-controller` pod is not running on this cluster. +<1> Update the cluster name if the `migration-controller` pod is not running on this cluster. <2> The `migration-controller` pod runs on this cluster if `true`. -<3> Optional: If the storage provider is Microsoft Azure, specify the resource group. -<4> Optional: If you created a certificate bundle for self-signed CA certificates and if the `insecure` parameter value is `false`, specify the base64-encoded certificate bundle. -<5> SSL verification is enabled if `false`. -<6> The cluster is validated if `true`. -<7> The `restic` pods are restarted on the source cluster after the `stage` pods are created if `true`. -<8> Optional: If you are using direct image migration, specify the exposed registry path of a remote cluster. -<9> Specify the URL of the remote cluster. -<10> Specify the name of the `Secret` CR for the remote cluster. +<3> Microsoft Azure only: Specify the resource group. +<4> Optional: If you created a certificate bundle for self-signed CA certificates and if the `insecure` parameter value is `false`, specify the base64-encoded certificate bundle. +<5> Set to `true` to disable SSL verification. +<6> Set to `true` to validate the cluster. +<7> Set to `true` to restart the `Restic` pods on the source cluster after the `Stage` pods are created. +<8> Remote cluster and direct image migration only: Specify the exposed secure registry path. +<9> Remote cluster only: Specify the URL. +<10> Remote cluster only: Specify the name of the `Secret` CR. [id="mighook_{context}"] == MigHook -The `MigHook` CR defines an Ansible playbook or a custom image that runs tasks at a specified stage of the migration. +The `MigHook` CR defines a migration hook that runs custom code at a specified stage of the migration. You can create up to four migration hooks. Each hook runs during a different phase of the migration. + +You can configure the hook name, runtime duration, a custom image, and the cluster where the hook will run. + +The migration phases and namespaces of the hooks are configured in the `MigPlan` CR. [source,yaml] ---- @@ -210,7 +205,7 @@ metadata: name: <2> namespace: openshift-migration spec: - activeDeadlineSeconds: <3> + activeDeadlineSeconds: 1800 <3> custom: false <4> image: <5> playbook: <6> @@ -218,22 +213,18 @@ spec: ---- <1> Optional: A unique hash is appended to the value for this parameter so that each migration hook has a unique name. You do not need to specify the value of the `name` parameter. <2> Specify the migration hook name, unless you specify the value of the `generateName` parameter. -<3> Optional: Specify the maximum number of seconds that a hook can run. The default value is `1800`. +<3> Optional: Specify the maximum number of seconds that a hook can run. The default is `1800`. <4> The hook is a custom image if `true`. The custom image can include Ansible or it can be written in a different programming language. <5> Specify the custom image, for example, `quay.io/konveyor/hook-runner:latest`. Required if `custom` is `true`. -<6> Specify the entire base64-encoded Ansible playbook. Required if `custom` is `false`. -<7> Specify `source` or `destination` as the cluster on which the hook will run. +<6> Base64-encoded Ansible playbook. Required if `custom` is `false`. +<7> Specify the cluster on which the hook will run. Valid values are `source` or `destination`. [id="migmigration_{context}"] == MigMigration -The `MigMigration` CR runs an associated `MigPlan` CR. - -You can create multiple `MigMigration` CRs associated with the same `MigPlan` CR for the following scenarios: +The `MigMigration` CR runs a `MigPlan` CR. -* You can run multiple _stage_ or incremental migrations to copy data without stopping the pods on the source cluster. Running stage migrations improves the performance of the actual migration. -* You can cancel a migration in progress. -* You can roll back a migration. +You can configure a `Migmigration` CR to run a stage or incremental migration, to cancel a migration in progress, or to roll back a completed migration. [source,yaml] ---- @@ -252,22 +243,28 @@ spec: keepAnnotations: true <5> verify: false <6> migPlanRef: - name: <7> + name: namespace: openshift-migration ---- -<1> A migration in progress is canceled if `true`. -<2> A completed migration is rolled back if `true`. -<3> Data is copied incrementally and the pods on the source cluster are not stopped if `true`. -<4> The pods on the source cluster are scaled to `0` after the `Backup` stage of a migration if `true`. -<5> The labels and annotations applied during the migration are retained if `true`. -<6> The status of the migrated pods on the destination cluster are checked and the names of pods that are not in a `Running` state are returned if `true`. -<7> `migPlanRef.name`: Specify the name of the associated `MigPlan` CR. +<1> Set to `true` to cancel a migration in progress. +<2> Set to `true` to roll back a completed migration. +<3> Set to `true` to run a stage migration. Data is copied incrementally and the pods on the source cluster are not stopped. +<4> Set to `true` to stop the application during migration. The pods on the source cluster are scaled to `0` after the `Backup` stage. +<5> Set to `true` to retain the labels and annotations applied during the migration. +<6> Set to `true` to check the status of the migrated pods on the destination cluster are checked and to return the names of pods that are not in a `Running` state. [id="migplan_{context}"] == MigPlan 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. +You can configure destination namespaces, hook phases, and direct or indirect migration. + +[NOTE] +==== +By default, a destination namespace has the same name as the source namespace. If you configure a different destination namespace, you must ensure that the namespaces are not duplicated on the source or the destination clusters because the UID and GID ranges are copied during migration. +==== + [source,yaml] ---- apiVersion: migration.openshift.io/v1alpha1 @@ -280,48 +277,50 @@ metadata: spec: closed: false <1> srcMigClusterRef: - name: <2> + name: namespace: openshift-migration destMigClusterRef: - name: <3> + name: namespace: openshift-migration - hooks: <4> - - executionNamespace: <5> - phase: <6> + hooks: <2> + - executionNamespace: <3> + phase: <4> reference: - name: <7> - namespace: <8> - serviceAccount: <9> - indirectImageMigration: true <10> - indirectVolumeMigration: false <11> + name: <5> + namespace: <6> + serviceAccount: <7> + indirectImageMigration: true <8> + indirectVolumeMigration: false <9> migStorageRef: - name: <12> + name: namespace: openshift-migration namespaces: - - <13> - refresh: false <14> + - <10> + - + - : <11> + refresh: false <12> ---- <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. -<3> Specify the name of the destination cluster `MigCluster` CR. -<4> Optional: You can specify up to four migration hooks. -<5> Optional: Specify the namespace in which the hook will run. -<6> Optional: Specify the migration phase during which a hook runs. One hook can be assigned to one phase. The expected values are `PreBackup`, `PostBackup`, `PreRestore`, and `PostRestore`. -<7> Optional: Specify the name of the `MigHook` CR. -<8> Optional: Specify the namespace of `MigHook` CR. -<9> Optional: Specify a service account with `cluster-admin` privileges. -<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`. +<2> Optional: You can specify up to four migration hooks. Each hook must run during a different migration phase. +<3> Optional: Specify the namespace in which the hook will run. +<4> Optional: Specify the migration phase during which a hook runs. One hook can be assigned to one phase. Valid values are `PreBackup`, `PostBackup`, `PreRestore`, and `PostRestore`. +<5> Optional: Specify the name of the `MigHook` CR. +<6> Optional: Specify the namespace of `MigHook` CR. +<7> Optional: Specify a service account with `cluster-admin` privileges. +<8> 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. +<9> 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. +<10> Specify one or more source namespaces. If you specify only the source namespace, the destination namespace is the same. +<11> Specify the destination namespace if it is different from the source namespace. +<12> The `MigPlan` CR is validated if `true`. [id="migstorage_{context}"] == MigStorage -The `MigStorage` CR describes the object storage for the replication repository. You can configure Amazon Web Services, Microsoft Azure, Google Cloud Storage, and generic S3-compatible cloud storage, for example, Minio or NooBaa. +The `MigStorage` CR describes the object storage for the replication repository. + +Amazon Web Services (AWS), Microsoft Azure, Google Cloud Storage, Multi-Cloud Object Gateway, and generic S3-compatible cloud storage are supported. -Different providers require different parameters. +AWS and the snapshot copy method have additional parameters. [source,yaml] ---- @@ -352,13 +351,13 @@ spec: refresh: false <11> ---- <1> Specify the storage provider. -<2> Optional: If you are using the snapshot copy method, specify the storage provider. -<3> If you are using AWS, specify the bucket name. -<4> If you are using AWS, specify the bucket region, for example, `us-east-1`. -<5> Specify the name of the `Secret` CR that you created for the `MigStorage` CR. -<6> Optional: If you are using the AWS Key Management Service, specify the unique identifier of the key. -<7> Optional: If you granted public access to the AWS bucket, specify the bucket URL. -<8> Optional: Specify the AWS signature version for authenticating requests to the bucket, for example, `4`. -<9> Optional: If you are using the snapshot copy method, specify the geographical region of the clusters. -<10> Optional: If you are using the snapshot copy method, specify the name of the `Secret` CR that you created for the `MigStorage` CR. -<11> The cluster is validated if `true`. +<2> Snapshot copy method only: Specify the storage provider. +<3> AWS only: Specify the bucket name. +<4> AWS only: Specify the bucket region, for example, `us-east-1`. +<5> Specify the name of the `Secret` CR that you created for the storage. +<6> AWS only: If you are using the AWS Key Management Service, specify the unique identifier of the key. +<7> AWS only: If you granted public access to the AWS bucket, specify the bucket URL. +<8> AWS only: Specify the AWS signature version for authenticating requests to the bucket, for example, `4`. +<9> Snapshot copy method only: Specify the geographical region of the clusters. +<10> Snapshot copy method only: Specify the name of the `Secret` CR that you created for the storage. +<11> Set to `true` to validate the cluster. diff --git a/modules/migration-mtc-workflow.adoc b/modules/migration-mtc-workflow.adoc index 7b89ba25abd7..cb69cce93fde 100644 --- a/modules/migration-mtc-workflow.adoc +++ b/modules/migration-mtc-workflow.adoc @@ -1,7 +1,7 @@ // Module included in the following assemblies: // -// * migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc -// * migration-toolkit-for-containers/migrating-applications-with-mtc.adoc +// * migrating_from_ocp_3_to_4/about-mtc-3-4.adoc +// * migration-toolkit-for-containers/about-mtc.adoc [id="migration-mtc-workflow_{context}"] = {mtc-full} workflow diff --git a/modules/migration-prerequisites.adoc b/modules/migration-prerequisites.adoc index 6d3f522abd0d..3d1735f52e8c 100644 --- a/modules/migration-prerequisites.adoc +++ b/modules/migration-prerequisites.adoc @@ -1,22 +1,25 @@ // Module included in the following assemblies: // // * migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc // * migration-toolkit-for-containers/migrating-applications-with-mtc +// * migration-toolkit-for-containers/advanced-migration-options-mtc.adoc [id="migration-prerequisites_{context}"] -= Prerequisites += Migration prerequisites * You must be logged in as a user with `cluster-admin` privileges on all clusters. .Direct image migration -* You must ensure that the secure registry of the source cluster is exposed. +* You must ensure that the secure internal registry of the source cluster is exposed. +* You must create a route to the exposed registry. .Direct volume migration * If your clusters use proxies, you must configure an Stunnel TCP proxy. -ifdef::migrating-applications-3-4[] +ifdef::migrating-applications-3-4,advanced-migration-options-3-4[] .Internal images * If your application uses internal images from the `openshift` namespace, you must ensure that the required versions of the images are present on the target cluster. @@ -33,7 +36,7 @@ endif::[] * The clusters have unrestricted network access to each other and to the replication repository. * If you copy the persistent volumes with `move`, the clusters must have unrestricted network access to the remote volumes. -ifdef::migrating-applications-3-4[] +ifdef::migrating-applications-3-4,advanced-migration-options-3-4[] * You must enable the following ports on an {product-title} 3 cluster: ** `8443` (API server) ** `443` (routes) diff --git a/modules/migration-updating-deprecated-internal-images.adoc b/modules/migration-updating-deprecated-internal-images.adoc index 0968bf04b0eb..515c0a513b90 100644 --- a/modules/migration-updating-deprecated-internal-images.adoc +++ b/modules/migration-updating-deprecated-internal-images.adoc @@ -1,7 +1,7 @@ // Module included in the following assemblies: // -// * migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc -// * migration-toolkit-for-containers/migrating-applications-with-mtc +// * migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc +// * migration-toolkit-for-containers/troubleshooting-mtc.adoc [id="migration-updating-deprecated-internal-images_{context}"] = Updating deprecated internal images diff --git a/modules/migration-viewing-migration-crs.adoc b/modules/migration-using-mtc-crs-for-troubleshooting.adoc similarity index 95% rename from modules/migration-viewing-migration-crs.adoc rename to modules/migration-using-mtc-crs-for-troubleshooting.adoc index 0b7714444bd0..d863fd6654f5 100644 --- a/modules/migration-viewing-migration-crs.adoc +++ b/modules/migration-using-mtc-crs-for-troubleshooting.adoc @@ -1,12 +1,12 @@ // Module included in the following assemblies: // // * migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc -// * migration-toolkit-for-containers/troubleshooting-mtc +// * migration-toolkit-for-containers/troubleshooting-mtc.adoc -[id="migration-viewing-migration-crs_{context}"] -= Viewing {mtc-short} custom resources +[id="migration-using-mtc-crs-for-troubleshooting_{context}"] += Using {mtc-short} custom resources for troubleshooting -You can view the following {mtc-full} ({mtc-short}) custom resources (CRs) to troubleshoot a failed migration: +You can check the following {mtc-full} ({mtc-short}) custom resources (CRs) to troubleshoot a failed migration: * `MigCluster` * `MigStorage` diff --git a/modules/migration-writing-ansible-playbook-hook.adoc b/modules/migration-writing-ansible-playbook-hook.adoc index 3acb9629059c..5ba3f195c534 100644 --- a/modules/migration-writing-ansible-playbook-hook.adoc +++ b/modules/migration-writing-ansible-playbook-hook.adoc @@ -1,7 +1,7 @@ // Module included in the following assemblies: // -// * migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc -// * migration-toolkit-for-containers/migrating-applications-with-mtc +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration-toolkit-for-containers/advanced-migration-options-mtc.adoc [id="migration-writing-ansible-playbook-hook_{context}"] = Writing an Ansible playbook for a migration hook