Installing the Migration Toolkit for Containers

    After you install the Migration Toolkit for Containers Operator on OKD 4.8 by using the Operator Lifecycle Manager, you manually install the legacy Migration Toolkit for Containers Operator on OKD 3.

    By default, the MTC web console and the pod run on the target cluster. You can configure the Migration Controller custom resource manifest to run the MTC web console and the Migration Controller pod on a source cluster or on a remote cluster.

    After you have installed MTC, you must configure an object storage to use as a replication repository.

    You must install the Migration Toolkit for Containers (MTC) version that is compatible with your OKD version.

    You cannot install MTC 1.6.x on OKD versions 3.7 to 4.5 because the custom resource definition API versions are incompatible.

    You can migrate workloads from a source cluster with MTC 1.5.1 to a target cluster with MTC 1.6.x as long as the MigrationController custom resource and the MTC web console are running on the target cluster.

    1 Latest z-stream release.

    You can install the legacy Migration Toolkit for Containers Operator manually on OKD 3.

    Prerequisites

    • You must be logged in as a user with cluster-admin privileges on all clusters.

    • You must have access to registry.redhat.io.

    • You must have podman installed.

    • You must create an and copy it to each node in the cluster.

    Procedure

    1. Log in to registry.redhat.io with your Red Hat Customer Portal credentials:

    2. Download the operator.yml file for your OKD version:

      • OKD version 3.7:

        1. $ sudo podman cp $(sudo podman create \
        2.   registry.redhat.io/rhmtc/openshift-migration-legacy-rhel8-operator:v1.5.1):/operator-3.7.yml ./

      • OKD version 3.9 to 3.11:

        1. $ sudo podman cp $(sudo podman create \
        2.   registry.redhat.io/rhmtc/openshift-migration-legacy-rhel8-operator:v1.5.1):/operator.yml ./

    3. Download the controller.yml file:

      1. $ sudo podman cp $(sudo podman create \
      2.   registry.redhat.io/rhmtc/openshift-migration-legacy-rhel8-operator:v1.5.1):/controller.yml ./

    4. Log in to your OKD 3 cluster.

    5. Verify that the cluster can authenticate with registry.redhat.io:

      1. $ oc run test --image registry.redhat.io/ubi8 --command sleep infinity

    6. Create the Migration Toolkit for Containers Operator object:

      1. $ oc create -f operator.yml

      Example output

      1. namespace/openshift-migration created
      2. rolebinding.rbac.authorization.k8s.io/system:deployers created
      3. serviceaccount/migration-operator created
      4. customresourcedefinition.apiextensions.k8s.io/migrationcontrollers.migration.openshift.io created
      5. role.rbac.authorization.k8s.io/migration-operator created
      6. rolebinding.rbac.authorization.k8s.io/migration-operator created
      7. clusterrolebinding.rbac.authorization.k8s.io/migration-operator created
      8. deployment.apps/migration-operator created
      9. Error from server (AlreadyExists): error when creating "./operator.yml":
      10. rolebindings.rbac.authorization.k8s.io "system:image-builders" already exists (1)
      11. Error from server (AlreadyExists): error when creating "./operator.yml":
      12. rolebindings.rbac.authorization.k8s.io "system:image-pullers" already exists
      1You can ignore Error from server (AlreadyExists) messages. They are caused by the Migration Toolkit for Containers Operator creating resources for earlier versions of OKD 3 that are provided in later releases.

    7. Create the MigrationController object:

      1. $ oc create -f controller.yml

    8. Verify that the MTC pods are running:

      1. $ oc get pods -n openshift-migration

    You install the Migration Toolkit for Containers Operator on OKD 4.8 by using the Operator Lifecycle Manager.

    Prerequisites

    • You must be logged in as a user with cluster-admin privileges on all clusters.

    Procedure

    1. In the OKD web console, click Operators → OperatorHub.

    2. Use the Filter by keyword field to find the Migration Toolkit for Containers Operator.

    3. Select the Migration Toolkit for Containers Operator and click Install.

    4. Click Install.

      On the Installed Operators page, the Migration Toolkit for Containers Operator appears in the openshift-migration project with the status Succeeded.

    5. Click Migration Toolkit for Containers Operator.

    6. Under Provided APIs, locate the Migration Controller tile, and click Create Instance.

    7. Click Create.

    8. Click Workloads → Pods to verify that the MTC pods are running.

    For OKD 4.1 and earlier versions, you must configure proxies in the MigrationController custom resource (CR) manifest after you install the Migration Toolkit for Containers Operator because these versions do not support a cluster-wide proxy object.

    For OKD 4.2 to 4.8, the Migration Toolkit for Containers (MTC) inherits the cluster-wide proxy settings. You can change the proxy parameters if you want to override the cluster-wide proxy settings.

    You must configure the proxies to allow the SPDY protocol and to forward the Upgrade HTTP header to the API server. Otherwise, an Upgrade request required error is displayed. The MigrationController CR uses SPDY to run commands within remote pods. The Upgrade HTTP header is required in order to open a websocket connection with the API server.

    Direct volume migration

    DVM supports only one proxy. The source cluster cannot access the route of the target cluster if the target cluster is also behind a proxy.

    Prerequisites

    • You must be logged in as a user with cluster-admin privileges on all clusters.

    Procedure

    1. Get the MigrationController CR manifest:

      1. $ oc get migrationcontroller <migration_controller> -n openshift-migration

    2. Update the proxy parameters:

      1. apiVersion: migration.openshift.io/v1alpha1
      2. kind: MigrationController
      3. metadata:
      4.   name: <migration_controller>
      5.   namespace: openshift-migration
      6. ...
      7. spec:
      8.   stunnel_tcp_proxy: http://<username>:<password>@<ip>:<port> (1)
      9.   httpProxy: http://<username>:<password>@<ip>:<port> (2)
      10.   httpsProxy: http://<username>:<password>@<ip>:<port> (3)
      11.   noProxy: example.com (4)
      1Stunnel proxy URL for direct volume migration.
      2Proxy URL for creating HTTP connections outside the cluster. The URL scheme must be http.
      3Proxy URL for creating HTTPS connections outside the cluster. If this is not specified, then httpProxy is used for both HTTP and HTTPS connections.
      4Comma-separated list of destination domain names, domains, IP addresses, or other network CIDRs to exclude proxying.

      Preface a domain with . to match subdomains only. For example, .y.com matches x.y.com, but not y.com. Use * to bypass proxy for all destinations. If you scale up workers that are not included in the network defined by the networking.machineNetwork[].cidr field from the installation configuration, you must add them to this list to prevent connection issues.

      This field is ignored if neither the httpProxy nor the httpsProxy field is set.

    3. Save the manifest as migration-controller.yaml.

    4. Apply the updated manifest:

      1. $ oc replace -f migration-controller.yaml -n openshift-migration

    For more information, see Configuring the cluster-wide proxy.

    You must configure an object storage to use as a replication repository. The Migration Toolkit for Containers (MTC) copies data from the source cluster to the replication repository, and then from the replication repository to the target cluster.

    MTC supports the 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.

    The following storage providers are supported:

    • Multi-Cloud Object Gateway (MCG)

    • Amazon Web Services (AWS) S3

    • Google Cloud Platform (GCP)

    • Microsoft Azure Blob

    • Generic S3 object storage, for example, Minio or Ceph S3

    • All clusters must have uninterrupted network access to the replication repository.

    • If you use a proxy server with an internally hosted replication repository, you must ensure that the proxy allows access to the replication repository.

    Configuring Multi-Cloud Object Gateway

    You can install the OpenShift Container Storage Operator and configure a Multi-Cloud Object Gateway (MCG) storage bucket as a replication repository for the Migration Toolkit for Containers (MTC).

    Installing the OpenShift Container Storage Operator

    You can install the OpenShift Container Storage Operator from OperatorHub.

    Prerequisites

    • Ensure that you have downloaded the pull secret from the Red Hat OpenShift Cluster Manager site as shown in Obtaining the installation program in the installation documentation for your platform.

      If you have the pull secret, add the redhat-operators catalog to the OperatorHub custom resource (CR) as shown in Configuring OKD to use Red Hat Operators.

    Procedure

    1. In the OKD web console, click Operators → OperatorHub.

    2. Use Filter by keyword (in this case, OCS) to find the OpenShift Container Storage Operator.

    3. Select the OpenShift Container Storage Operator and click Install.

    4. Select an Update Channel, Installation Mode, and Approval Strategy.

    5. Click Install.

      On the Installed Operators page, the OpenShift Container Storage Operator appears in the openshift-storage project with the status Succeeded.

    Creating the Multi-Cloud Object Gateway storage bucket

    You can create the Multi-Cloud Object Gateway (MCG) storage bucket’s custom resources (CRs).

    Procedure

    1. Log in to the OKD cluster:

      1. $ oc login -u <username>

    2. Create the NooBaa CR configuration file, noobaa.yml, with the following content:

      1. apiVersion: noobaa.io/v1alpha1
      2. kind: NooBaa
      3. metadata:
      4.   name: <noobaa>
      5.   namespace: openshift-storage
      6. spec:
      7.  dbResources:
      8.    requests:
      9.      cpu: 0.5 (1)
      10.      memory: 1Gi
      11.  coreResources:
      12.    requests:
      13.      cpu: 0.5 (1)
      14.      memory: 1Gi

    3. Create the NooBaa object:

      1. $ oc create -f noobaa.yml

    4. Create the BackingStore CR configuration file, bs.yml, with the following content:

      1. kind: BackingStore
      2. metadata:
      4.   - noobaa.io/finalizer
      5.   labels:
      6.     app: noobaa
      7.   name: <mcg_backing_store>
      8.   namespace: openshift-storage
      9. spec:
      10.   pvPool:
      11.     numVolumes: 3 (1)
      12.     resources:
      13.       requests:
      14.         storage: <volume_size> (2)
      15.     storageClass: <storage_class> (3)
      16.   type: pv-pool
      1Specify the number of volumes in the persistent volume pool.
      2Specify the size of the volumes, for example, 50Gi.
      3Specify the storage class, for example, gp2.

    5. Create the BackingStore object:

      1. $ oc create -f bs.yml

    6. Create the BucketClass CR configuration file, bc.yml, with the following content:

    7. Create the BucketClass object:

      1. $ oc create -f bc.yml

    8. Create the ObjectBucketClaim CR configuration file, obc.yml, with the following content:

      1. apiVersion: objectbucket.io/v1alpha1
      2. kind: ObjectBucketClaim
      3. metadata:
      4.   name: <bucket>
      5.   namespace: openshift-storage
      6. spec:
      7.   bucketName: <bucket> (1)
      8.   storageClassName: <storage_class>
      9.   additionalConfig:
      10.     bucketclass: <mcg_bucket_class>
      1Record the bucket name for adding the replication repository to the MTC web console.

    9. Create the ObjectBucketClaim object:

      1. $ oc create -f obc.yml

    10. Watch the resource creation process to verify that the ObjectBucketClaim status is Bound:

      1. $ watch -n 30 'oc get -n openshift-storage objectbucketclaim migstorage -o yaml'

      This process can take five to ten minutes.

    11. Obtain and record the following values, which are required when you add the replication repository to the MTC web console:

      • S3 endpoint:

        1. $ oc get route -n openshift-storage s3

      • S3 provider access key:

        1. $ oc get secret -n openshift-storage migstorage \
        2.  -o go-template='{{ .data.AWS_ACCESS_KEY_ID }}' | base64 --decode

      • S3 provider secret access key:

        1. $ oc get secret -n openshift-storage migstorage \
        2.  -o go-template='{{ .data.AWS_SECRET_ACCESS_KEY }}' | base64 --decode

    You can configure an Amazon Web Services (AWS) S3 storage bucket as a replication repository for the Migration Toolkit for Containers (MTC).

    Prerequisites

    • The AWS S3 storage bucket must be accessible to the source and target clusters.

    • You must have the AWS CLI installed.

      • You must have access to EC2 Elastic Block Storage (EBS).

      • The source and target clusters must be in the same region.

      • The source and target clusters must have the same storage class.

      • The storage class must be compatible with snapshots.

    Procedure

    1. Create an AWS S3 bucket:

      1. $ aws s3api create-bucket \
      2.     --bucket <bucket> \ (1)
      3.     --region <bucket_region> (2)

    2. Create the IAM user velero:

      1. $ aws iam create-user --user-name velero

    3. Create an EC2 EBS snapshot policy:

      1. $ cat > velero-ec2-snapshot-policy.json <<EOF
      2. {
      3.     "Version": "2012-10-17",
      4.     "Statement": [
      5.         {
      6.             "Effect": "Allow",
      7.             "Action": [
      8.                 "ec2:DescribeVolumes",
      9.                 "ec2:DescribeSnapshots",
      10.                 "ec2:CreateTags",
      11.                 "ec2:CreateVolume",
      12.                 "ec2:CreateSnapshot",
      13.                 "ec2:DeleteSnapshot"
      14.             ],
      15.             "Resource": "*"
      16.         }
      17.     ]
      18. }
      19. EOF

    4. Create an AWS S3 access policy for one or for all S3 buckets:

      1. $ cat > velero-s3-policy.json <<EOF
      2. {
      3.     "Version": "2012-10-17",
      4.     "Statement": [
      5.         {
      6.             "Effect": "Allow",
      7.             "Action": [
      8.                 "s3:GetObject",
      9.                 "s3:DeleteObject",
      10.                 "s3:PutObject",
      11.                 "s3:AbortMultipartUpload",
      12.                 "s3:ListMultipartUploadParts"
      13.             ],
      14.             "Resource": [
      15.                 "arn:aws:s3:::<bucket>/*" (1)
      16.             ]
      17.         },
      18.         {
      19.             "Effect": "Allow",
      20.             "Action": [
      21.                 "s3:ListBucket",
      22.                 "s3:GetBucketLocation",
      23.                 "s3:ListBucketMultipartUploads"
      24.             ],
      25.             "Resource": [
      26.                 "arn:aws:s3:::<bucket>" (1)
      27.             ]
      29.     ]
      30. }
      1To grant access to a single S3 bucket, specify the bucket name. To grant access to all AWS S3 buckets, specify * instead of a bucket name as in the following example:

      Example output

      1. "Resource": [
      2.     "arn:aws:s3:::*"

    5. Attach the EC2 EBS policy to velero:

      1. $ aws iam put-user-policy \
      2.   --user-name velero \
      3.   --policy-name velero-ebs \
      4.   --policy-document file://velero-ec2-snapshot-policy.json

    6. Attach the AWS S3 policy to velero:

      1. $ aws iam put-user-policy \
      2.   --user-name velero \
      3.   --policy-name velero-s3 \
      4.   --policy-document file://velero-s3-policy.json

    7. Create an access key for velero:

      1. $ aws iam create-access-key --user-name velero
      2. {
      3.   "AccessKey": {
      4.         "UserName": "velero",
      5.         "Status": "Active",
      6.         "CreateDate": "2017-07-31T22:24:41.576Z",
      7.         "SecretAccessKey": <AWS_SECRET_ACCESS_KEY>, (1)
      8.         "AccessKeyId": <AWS_ACCESS_KEY_ID> (1)
      9.     }
      10. }
      1Record the AWS_SECRET_ACCESS_KEY and the AWS_ACCESS_KEY_ID for adding the AWS repository to the MTC web console.

    Configuring Google Cloud Platform

    You can configure a Google Cloud Platform (GCP) storage bucket as a replication repository for the Migration Toolkit for Containers (MTC).

    Prerequisites

    • The GCP storage bucket must be accessible to the source and target clusters.

    • You must have gsutil installed.

    • If you are using the snapshot copy method:

      • The source and target clusters must be in the same region.

      • The source and target clusters must have the same storage class.

      • The storage class must be compatible with snapshots.

    Procedure

    1. Log in to gsutil:

      1. $ gsutil init

      Example output

    2. Set the BUCKET variable:

      1. $ BUCKET=<bucket> (1)

    3. Create a storage bucket:

      1. $ gsutil mb gs://$BUCKET/

    4. Set the PROJECT_ID variable to your active project:

      1. $ PROJECT_ID=`gcloud config get-value project`

    5. Create a velero IAM service account:

      1. $ gcloud iam service-accounts create velero \
      2.     --display-name "Velero Storage"

    6. Create the SERVICE_ACCOUNT_EMAIL variable:

      1. $ SERVICE_ACCOUNT_EMAIL=`gcloud iam service-accounts list \
      2.   --filter="displayName:Velero Storage" \
      3.   --format 'value(email)'`

    7. Create the ROLE_PERMISSIONS variable:

      1. $ ROLE_PERMISSIONS=(
      2.     compute.disks.get
      3.     compute.disks.create
      4.     compute.disks.createSnapshot
      5.     compute.snapshots.get
      6.     compute.snapshots.create
      7.     compute.snapshots.useReadOnly
      8.     compute.snapshots.delete
      9.     compute.zones.get
      10. )

    8. Create the velero.server custom role:

      1. $ gcloud iam roles create velero.server \
      2.     --project $PROJECT_ID \
      3.     --title "Velero Server" \
      4.     --permissions "$(IFS=","; echo "${ROLE_PERMISSIONS[*]}")"

    9. Add IAM policy binding to the project:

      1. $ gcloud projects add-iam-policy-binding $PROJECT_ID \
      2.     --member serviceAccount:$SERVICE_ACCOUNT_EMAIL \
      3.     --role projects/$PROJECT_ID/roles/velero.server

    10. Update the IAM service account:

      1. $ gsutil iam ch serviceAccount:$SERVICE_ACCOUNT_EMAIL:objectAdmin gs://${BUCKET}

    11. Save the IAM service account keys to the credentials-velero file in the current directory:

      1. $ gcloud iam service-accounts keys create credentials-velero \
      2.  --iam-account $SERVICE_ACCOUNT_EMAIL

    You can configure a Microsoft Azure Blob storage container as a replication repository for the Migration Toolkit for Containers (MTC).

    Prerequisites

    • You must have an .

    • You must have the Azure CLI installed.

    • The Azure Blob storage container must be accessible to the source and target clusters.

    • If you are using the snapshot copy method:

      • The source and target clusters must be in the same region.

      • The source and target clusters must have the same storage class.

      • The storage class must be compatible with snapshots.

    Procedure

    1. Set the AZURE_RESOURCE_GROUP variable:

      1. $ AZURE_RESOURCE_GROUP=Velero_Backups

    2. Create an Azure resource group:

      1. $ az group create -n $AZURE_RESOURCE_GROUP --location <CentralUS> (1)
      1Specify your location.

    3. Set the AZURE_STORAGE_ACCOUNT_ID variable:

      1. $ AZURE_STORAGE_ACCOUNT_ID=velerobackups

    4. Create an Azure storage account:

      1. $ az storage account create \
      2.   --name $AZURE_STORAGE_ACCOUNT_ID \
      3.   --resource-group $AZURE_RESOURCE_GROUP \
      4.   --sku Standard_GRS \
      5.   --encryption-services blob \
      6.   --https-only true \
      7.   --kind BlobStorage \
      8.   --access-tier Hot

    5. Set the BLOB_CONTAINER variable:

      1. $ BLOB_CONTAINER=velero

    6. Create an Azure Blob storage container:

      1. $ az storage container create \
      2.   -n $BLOB_CONTAINER \
      3.   --public-access off \
      4.   --account-name $AZURE_STORAGE_ACCOUNT_ID

    7. Create a service principal and credentials for velero:

    8. Save the service principal credentials in the credentials-velero file:

      1. $ cat << EOF  > ./credentials-velero
      2. AZURE_SUBSCRIPTION_ID=${AZURE_SUBSCRIPTION_ID}
      3. AZURE_TENANT_ID=${AZURE_TENANT_ID}
      4. AZURE_CLIENT_ID=${AZURE_CLIENT_ID}
      5. AZURE_CLIENT_SECRET=${AZURE_CLIENT_SECRET}
      6. AZURE_RESOURCE_GROUP=${AZURE_RESOURCE_GROUP}
      7. AZURE_CLOUD_NAME=AzurePublicCloud

    Additional resources for configuring a replication repository