From 2db45de37e341a9b457845dc002aee086c2739e7 Mon Sep 17 00:00:00 2001 From: Avital Pinnick Date: Wed, 10 Feb 2021 12:00:08 +0200 Subject: [PATCH] fix conflict --- .../migrating-applications-with-cam-3-4.adoc | 48 ++- ...migrating-applications-with-cam-4-1-4.adoc | 48 ++- ...migrating-applications-with-cam-4-2-4.adoc | 48 ++- .../migration-migrating-applications-api.adoc | 367 ++++++++++++++++++ modules/migration-mtc-cr-manifests.adoc | 362 +++++++++++++++++ 5 files changed, 852 insertions(+), 21 deletions(-) create mode 100644 modules/migration-migrating-applications-api.adoc create mode 100644 modules/migration-mtc-cr-manifests.adoc diff --git a/migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc b/migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc index 64fb12b6ae..607dc1c3fe 100644 --- a/migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc +++ b/migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc @@ -6,20 +6,54 @@ include::modules/common-attributes.adoc[] toc::[] -You must add your clusters and a replication repository to the {mtc-short} web console. Then, you can create and run a migration plan. +You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or on the command line. -If your cluster or replication repository are secured with self-signed certificates, you can create a CA certificate bundle file or disable SSL verification. +If you are using self-signed CA certificates to secure the clusters or the replication repository, you can create a CA certificate bundle file or disable SSL verification. include::modules/migration-creating-ca-bundle.adoc[leveloffset=+1] -include::modules/migration-adding-cluster-to-cam.adoc[leveloffset=+1] -include::modules/migration-adding-replication-repository-to-cam.adoc[leveloffset=+1] -include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+1] -include::modules/migration-running-migration-plan-cam.adoc[leveloffset=+1] + +[id="migrating-applications-mtc-web-console_{context}"] +== Migrating your applications by using the {mtc-short} web console + +You can configure clusters and a replication repository by using the {mtc-short} web console. Then, you can create and run a migration plan. + +include::modules/migration-adding-cluster-to-cam.adoc[leveloffset=+2] +include::modules/migration-adding-replication-repository-to-cam.adoc[leveloffset=+2] +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 on the command line + +You can migrate your applications on the command line by using the {mtc-short} custom resources (CRs). + +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] +=== {mtc-short} 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] [id='configuring-migration-plan_{context}'] == Configuring a migration plan -You can configure a migration plan to suit your needs by increasing the number of objects migrated or excluding resources from migration. +You can configure a migration plan by increasing the number of objects migrated or excluding resources from migration. include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2] include::modules/migration-excluding-resources.adoc[leveloffset=+2] diff --git a/migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc b/migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc index d6bfb4640b..83cdaa2eb7 100644 --- a/migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc +++ b/migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc @@ -6,20 +6,54 @@ include::modules/common-attributes.adoc[] toc::[] -You must add your clusters and a replication repository to the {mtc-short} web console. Then, you can create and run a migration plan. +You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or on the command line. -If your cluster or replication repository are secured with self-signed certificates, you can create a CA certificate bundle file or disable SSL verification. +If you are using self-signed CA certificates to secure the clusters or the replication repository, you can create a CA certificate bundle file or disable SSL verification. include::modules/migration-creating-ca-bundle.adoc[leveloffset=+1] -include::modules/migration-adding-cluster-to-cam.adoc[leveloffset=+1] -include::modules/migration-adding-replication-repository-to-cam.adoc[leveloffset=+1] -include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+1] -include::modules/migration-running-migration-plan-cam.adoc[leveloffset=+1] + +[id="migrating-applications-mtc-web-console_{context}"] +== Migrating your applications using the {mtc-short} web console + +You can configure clusters and a replication repository by using the {mtc-short} web console. Then, you can create and run a migration plan. + +include::modules/migration-adding-cluster-to-cam.adoc[leveloffset=+2] +include::modules/migration-adding-replication-repository-to-cam.adoc[leveloffset=+2] +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 on the command line + +You can migrate your applications on the command line by using the {mtc-short} custom resources (CRs). + +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] +=== {mtc-short} 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] [id='configuring-migration-plan_{context}'] == Configuring a migration plan -You can configure a migration plan to suit your needs by increasing the number of objects migrated or excluding resources from migration. +You can configure a migration plan by increasing the number of objects migrated or excluding resources from migration. include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2] include::modules/migration-excluding-resources.adoc[leveloffset=+2] diff --git a/migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc b/migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc index c8cbf28a20..cf1bce0183 100644 --- a/migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc +++ b/migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc @@ -6,20 +6,54 @@ include::modules/common-attributes.adoc[] toc::[] -You must add your clusters and a replication repository to the {mtc-short} web console. Then, you can create and run a migration plan. +You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or on the command line. -If your cluster or replication repository are secured with self-signed certificates, you can create a CA certificate bundle file or disable SSL verification. +If you are using self-signed CA certificates to secure the clusters or the replication repository, you can create a CA certificate bundle file or disable SSL verification. include::modules/migration-creating-ca-bundle.adoc[leveloffset=+1] -include::modules/migration-adding-cluster-to-cam.adoc[leveloffset=+1] -include::modules/migration-adding-replication-repository-to-cam.adoc[leveloffset=+1] -include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+1] -include::modules/migration-running-migration-plan-cam.adoc[leveloffset=+1] + +[id="migrating-applications-mtc-web-console_{context}"] +== Migrating your applications by using the {mtc-short} web console + +You can configure clusters and a replication repository by using the {mtc-short} web console. Then, you can create and run a migration plan. + +include::modules/migration-adding-cluster-to-cam.adoc[leveloffset=+2] +include::modules/migration-adding-replication-repository-to-cam.adoc[leveloffset=+2] +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 on the command line + +You can migrate your applications on the command line by using the {mtc-short} custom resources (CRs). + +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] +=== {mtc-short} 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] [id='configuring-migration-plan_{context}'] == Configuring a migration plan -You can configure a migration plan to suit your needs by increasing the number of objects migrated or excluding resources from migration. +You can configure a migration plan by increasing the number of objects migrated or excluding resources from migration. include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2] include::modules/migration-excluding-resources.adoc[leveloffset=+2] diff --git a/modules/migration-migrating-applications-api.adoc b/modules/migration-migrating-applications-api.adoc new file mode 100644 index 0000000000..08fb7b0736 --- /dev/null +++ b/modules/migration-migrating-applications-api.adoc @@ -0,0 +1,367 @@ +// Module included in the following assemblies: +// +// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc +// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc +// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc + +[id='migration-migrating-applications-api_{context}'] += Migrating your applications with the {mtc-full} API + +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. + +.Procedure + +. Create a `MigCluster` CR manifest for the `host` cluster called `host-cluster.yaml`: ++ +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigCluster +metadata: + name: host + namespace: openshift-migration +spec: + isHostCluster: true +---- + +. 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`: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: + namespace: openshift-config +type: Opaque +data: + saToken: <1> +---- +<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: ++ +[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`: ++ +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigCluster +metadata: + name: + namespace: openshift-migration +spec: + exposedRegistryPath: <1> + insecure: false <2> + isHostCluster: false + serviceAccountSecretRef: + name: <3> + 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 +---- + +. Verify that all clusters are in a `Ready` state: ++ +[source,terminal] +---- +$ oc describe cluster +---- + +. Create a `Secret` CR manifest for the replication repository called `storage-secret.yaml`: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + namespace: openshift-config + name: +type: Opaque +data: + aws-access-key-id: <1> + aws-secret-access-key: <2> +---- +<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: ++ +[source,terminal] +---- +$ 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`: ++ +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigStorage +metadata: + name: + namespace: openshift-migration +spec: + backupStorageConfig: + awsBucketName: <1> + credsSecretRef: + name: <2> + namespace: openshift-config + backupStorageProvider: <3> + volumeSnapshotConfig: + credsSecretRef: + name: <4> + namespace: openshift-config + volumeSnapshotProvider: <5> +---- +<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. +<3> Specify the storage provider. +<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 +---- + +. Create a `MigPlan` CR manifest called `migplan.yaml`: ++ +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigPlan +metadata: + name: + namespace: openshift-migration +spec: + destMigClusterRef: + name: host + namespace: openshift-migration + indirectImageMigration: true <1> + indirectVolumeMigration: true <2> + migStorageRef: + name: <3> + namespace: openshift-migration + namespaces: + - <4> + srcMigClusterRef: + name: <5> + 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. + +. Create the `MigPlan` CR: ++ +[source,terminal] +---- +$ oc create -f migplan.yaml -n openshift-migration +---- + +. View the `MigPlan` instance to verify that it is in a `Ready` state: ++ +[source,terminal] +---- +$ oc describe migplan -n openshift-migration +---- + +. Create a `MigMigration` CR manifest called `migmigration.yaml`: ++ +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigMigration +metadata: + name: + namespace: openshift-migration +spec: + migPlanRef: + name: <1> + namespace: openshift-migration + quiescePods: true <2> + stage: false <3> + rollback: false <4> +---- +<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: ++ +[source,terminal] +---- +$ oc watch migmigration -n openshift-migration +---- ++ +The output resembles the following: ++ +.Example output ++ +[source,yaml] +---- +Name: c8b034c0-6567-11eb-9a4f-0bc004db0fbc +Namespace: openshift-migration +Labels: migration.openshift.io/migplan-name=django +Annotations: openshift.io/touch: e99f9083-6567-11eb-8420-0a580a81020c +API Version: migration.openshift.io/v1alpha1 +Kind: MigMigration +... +Spec: + Mig Plan Ref: + Name: my_application + Namespace: openshift-migration + Stage: false +Status: + Conditions: + Category: Advisory + Last Transition Time: 2021-02-02T15:04:09Z + Message: Step: 19/47 + Reason: InitialBackupCreated + Status: True + Type: Running + Category: Required + Last Transition Time: 2021-02-02T15:03:19Z + Message: The migration is ready. + Status: True + Type: Ready + Category: Required + Durable: true + Last Transition Time: 2021-02-02T15:04:05Z + Message: The migration registries are healthy. + Status: True + Type: RegistriesHealthy + Itinerary: Final + Observed Digest: 7fae9d21f15979c71ddc7dd075cb97061895caac5b936d92fae967019ab616d5 + Phase: InitialBackupCreated + Pipeline: + Completed: 2021-02-02T15:04:07Z + Message: Completed + Name: Prepare + Started: 2021-02-02T15:03:18Z + Message: Waiting for initial Velero backup to complete. + Name: Backup + Phase: InitialBackupCreated + Progress: + Backup openshift-migration/c8b034c0-6567-11eb-9a4f-0bc004db0fbc-wpc44: 0 out of estimated total of 0 objects backed up (5s) + Started: 2021-02-02T15:04:07Z + Message: Not started + Name: StageBackup + Message: Not started + Name: StageRestore + Message: Not started + Name: DirectImage + Message: Not started + Name: DirectVolume + Message: Not started + Name: Restore + Message: Not started + Name: Cleanup + Start Timestamp: 2021-02-02T15:03:18Z +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Running 57s migmigration_controller Step: 2/47 + Normal Running 57s migmigration_controller Step: 3/47 + Normal Running 57s (x3 over 57s) migmigration_controller Step: 4/47 + Normal Running 54s migmigration_controller Step: 5/47 + Normal Running 54s migmigration_controller Step: 6/47 + Normal Running 52s (x2 over 53s) migmigration_controller Step: 7/47 + Normal Running 51s (x2 over 51s) migmigration_controller Step: 8/47 + Normal Ready 50s (x12 over 57s) migmigration_controller The migration is ready. + Normal Running 50s migmigration_controller Step: 9/47 + Normal Running 50s migmigration_controller Step: 10/47 +---- diff --git a/modules/migration-mtc-cr-manifests.adoc b/modules/migration-mtc-cr-manifests.adoc new file mode 100644 index 0000000000..ba02cbbb9c --- /dev/null +++ b/modules/migration-mtc-cr-manifests.adoc @@ -0,0 +1,362 @@ +// Module included in the following assemblies: +// +// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc +// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc +// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc + +[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. + +[id="directimagemigration_{context}"] +== DirectImageMigration + +The `DirectImageMigration` CR copies images directly from the source cluster to the destination cluster. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: DirectImageMigration +metadata: + labels: + controller-tools.k8s.io: "1.0" + name: +spec: + srcMigClusterRef: + name: <1> + namespace: openshift-migration + destMigClusterRef: + name: <2> + namespace: openshift-migration + namespaces: + - <3> +---- +<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. + +[id="directimagestreammigration_{context}"] +== DirectImageStreamMigration + +The `DirectImageStreamMigration` CR copies image stream references directly from the source cluster to the destination cluster. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: DirectImageStreamMigration +metadata: + labels: + controller-tools.k8s.io: "1.0" + name: directimagestreammigration_name +spec: + srcMigClusterRef: + name: <1> + namespace: openshift-migration + destMigClusterRef: + name: <2> + namespace: openshift-migration + imageStreamRef: + name: <3> + namespace: <4> + destNamespace: <5> +---- +<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 + +The `DirectVolumeMigration` CR copies persistent volumes (PVs) directly from the source cluster to the destination cluster. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: DirectVolumeMigration +metadata: + name: + namespace: openshift-migration +spec: + createDestinationNamespaces: false <1> + deleteProgressReportingCRs: false <2> + destMigClusterRef: + name: host <3> + namespace: openshift-migration + persistentVolumeClaims: + - name: <4> + namespace: <5> + srcMigClusterRef: + name: <6> + 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. +<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. + +[id="directvolumemigrationprogress_{context}"] +== DirectVolumeMigrationProgress + +The `DirectVolumeMigrationProgress` CR shows the progress of the `DirectVolumeMigration` CR. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: DirectVolumeMigrationProgress +metadata: + labels: + controller-tools.k8s.io: "1.0" + name: directvolumemigrationprogress_name +spec: + clusterRef: + name: source_cluster + namespace: openshift-migration + podRef: + name: rsync_pod + 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. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigAnalytic +metadata: + annotations: + migplan: <1> + name: miganalytic_name + namespace: openshift-migration + labels: + migplan: <2> +spec: + analyzeImageCount: true <3> + analyzeK8SResources: true <4> + analyzePVCapacity: true <5> + listImages: false <6> + listImagesLimit: 50 <7> + migPlanRef: + name: migplan_name <8> + 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. + +[id="migcluster_{context}"] +== `MigCluster` + +The `MigCluster` CR defines a host, local, or remote cluster. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigCluster +metadata: + labels: + controller-tools.k8s.io: "1.0" + name: host <1> + namespace: openshift-migration +spec: + isHostCluster: true <2> + azureResourceGroup: <3> + caBundle: <4> + insecure: false <5> + refresh: false <6> +# The 'restartRestic' parameter is relevant for a source cluster. +# restartRestic: true <7> +# The following parameters are relevant for a remote cluster. +# isHostCluster: false +# 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. +<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. + +[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. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigHook +metadata: + generateName: <1> + name: <2> + namespace: openshift-migration +spec: + activeDeadlineSeconds: <3> + custom: false <4> + image: <5> + playbook: <6> + targetCluster: source <7> +---- +<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`. +<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. + +[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: + +* 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. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigMigration +metadata: + labels: + controller-tools.k8s.io: "1.0" + name: migmigration_name + namespace: openshift-migration +spec: + canceled: false <1> + rollback: false <2> + stage: false <3> + quiescePods: true <4> + keepAnnotations: true <5> + verify: false <6> + migPlanRef: + name: <7> + 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. + +[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. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigPlan +metadata: + labels: + controller-tools.k8s.io: "1.0" + name: migplan_name + namespace: openshift-migration +spec: + closed: false <1> + srcMigClusterRef: + name: <2> + namespace: openshift-migration + destMigClusterRef: + name: <3> + namespace: openshift-migration + hooks: <4> + - executionNamespace: openshift-migration + phase: <5> + reference: + name: <6> + namespace: openshift-migration + serviceAccount: migration-controller + indirectImageMigration: true <7> + indirectVolumeMigration: false <8> + migStorageRef: + name: <9> + namespace: openshift-migration + namespaces: + - <10> + refresh: false <11> +---- +<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 migration phase during which a hook runs. One hook can be assigned to one phase. The expected values are `PreBackup`, `PostBackup`, `PreRestore`, and `PostRestore`. +<6> Optional: Specify the name of the `MigHook` CR. +<7> 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. +<8> 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. +<9> Specify the name of `MigStorage` CR. +<10> Specify one or more namespaces. +<11> 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. + +Different providers require different parameters. + +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigStorage +metadata: + labels: + controller-tools.k8s.io: "1.0" + name: migstorage_name + namespace: openshift-migration +spec: + backupStorageProvider: <1> + volumeSnapshotProvider: <2> + backupStorageConfig: + awsBucketName: <3> + awsRegion: <4> + credsSecretRef: + namespace: openshift-config + name: <5> + awsKmsKeyId: <6> + awsPublicUrl: <7> + awsSignatureVersion: <8> + volumeSnapshotConfig: + awsRegion: <9> + credsSecretRef: + namespace: openshift-config + name: <10> + 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`.