openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 21:46:22 +01:00
Code Issues Releases Activity

Merge pull request #29742 from openshift-cherrypick-robot/cherry-pick-29058-to-enterprise-4.8

Browse Source 
[enterprise-4.8] MIG414: MTC API documentation (1.4.1)
This commit is contained in:
Vikram Goyal
2021-02-25 00:58:21 +10:00
committed by GitHub
parent a125578310 2db45de37e
commit fc05312cc6
5 changed files with 852 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc
View File

@@ -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]

48
migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc
View File

@@ -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]

48
migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc
View File

@@ -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]

367
modules/migration-migrating-applications-api.adoc Normal file
View File

@@ -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: <cluster_secret>
namespace: openshift-config
type: Opaque
data:
saToken: <sa_token> <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: <remote_cluster>
namespace: openshift-migration
spec:
exposedRegistryPath: <exposed_registry_route> <1>
insecure: false <2>
isHostCluster: false
serviceAccountSecretRef:
name: <remote_cluster_secret> <3>
namespace: openshift-config
url: <remote_cluster_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 <cluster_name>
----
. Create a `Secret` CR manifest for the replication repository called `storage-secret.yaml`:
+
[source,yaml]
----
apiVersion: v1
kind: Secret
metadata:
namespace: openshift-config
name: <migstorage_creds>
type: Opaque
data:
aws-access-key-id: <key_id_base64> <1>
aws-secret-access-key: <secret_key_base64> <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 "<key>" | 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: <storage_name>
namespace: openshift-migration
spec:
backupStorageConfig:
awsBucketName: <bucket_name> <1>
credsSecretRef:
name: <storage_secret_ref> <2>
namespace: openshift-config
backupStorageProvider: <storage_provider_name> <3>
volumeSnapshotConfig:
credsSecretRef:
name: <storage_secret_ref> <4>
namespace: openshift-config
volumeSnapshotProvider: <storage_provider_name> <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 <migstorage_name>
----
. Create a `MigPlan` CR manifest called `migplan.yaml`:
+
[source,yaml]
----
apiVersion: migration.openshift.io/v1alpha1
kind: MigPlan
metadata:
name: <migration_plan>
namespace: openshift-migration
spec:
destMigClusterRef:
name: host
namespace: openshift-migration
indirectImageMigration: true <1>
indirectVolumeMigration: true <2>
migStorageRef:
name: <migstorage_ref> <3>
namespace: openshift-migration
namespaces:
- <application_namespace> <4>
srcMigClusterRef:
name: <remote_cluster_ref> <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 <migplan_name> -n openshift-migration
----
. Create a `MigMigration` CR manifest called `migmigration.yaml`:
+
[source,yaml]
----
apiVersion: migration.openshift.io/v1alpha1
kind: MigMigration
metadata:
name: <migmigration_name>
namespace: openshift-migration
spec:
migPlanRef:
name: <migplan_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 <migmigration_name> -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
----

362
modules/migration-mtc-cr-manifests.adoc Normal file
View File

@@ -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: <directimagemigration_name>
spec:
srcMigClusterRef:
name: <source_cluster_ref> <1>
namespace: openshift-migration
destMigClusterRef:
name: <destination_cluster_ref> <2>
namespace: openshift-migration
namespaces:
- <namespace> <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: <source_cluster_ref> <1>
namespace: openshift-migration
destMigClusterRef:
name: <destination_cluster_ref> <2>
namespace: openshift-migration
imageStreamRef:
name: <image_stream_name> <3>
namespace: <source_image_stream_namespace> <4>
destNamespace: <destination_image_stream_namespace> <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: <directvolumemigration_name>
namespace: openshift-migration
spec:
createDestinationNamespaces: false <1>
deleteProgressReportingCRs: false <2>
destMigClusterRef:
name: host <3>
namespace: openshift-migration
persistentVolumeClaims:
- name: <pvc_name> <4>
namespace: <pvc_namespace> <5>
srcMigClusterRef:
name: <source_cluster_ref> <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: <migplan_name> <1>
name: miganalytic_name
namespace: openshift-migration
labels:
migplan: <migplan_name> <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: <azure_resource_group> <3>
caBundle: <ca_bundle_base64> <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: <destination_cluster_url> <9>
# serviceAccountSecretRef:
# name: <source_secret_ref> <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: <hook_name_prefix> <1>
name: <hook_name> <2>
namespace: openshift-migration
spec:
activeDeadlineSeconds: <3>
custom: false <4>
image: <hook_image> <5>
playbook: <ansible_playbook_base64> <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: <migplan_ref> <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: <source_migcluster_ref> <2>
namespace: openshift-migration
destMigClusterRef:
name: <destination_migcluster_ref> <3>
namespace: openshift-migration
hooks: <4>
- executionNamespace: openshift-migration
phase: <migration_phase> <5>
reference:
name: <hook_name> <6>
namespace: openshift-migration
serviceAccount: migration-controller
indirectImageMigration: true <7>
indirectVolumeMigration: false <8>
migStorageRef:
name: <migstorage_name> <9>
namespace: openshift-migration
namespaces:
- <namespace> <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: <storage_provider> <1>
volumeSnapshotProvider: <2>
backupStorageConfig:
awsBucketName: <3>
awsRegion: <4>
credsSecretRef:
namespace: openshift-config
name: <storage_secret> <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`.