Upgrade Migrate to Containers and plugins

Important: The Migrate to Containers UI in the Google Cloud console, migctl, and CRDs that use processing clusters to migrate workloads to Google Cloud are now deprecated. They are supported for existing users until May 2024, after which they will no longer be available. If you're new to Migrate to Containers, then use the Migrate to Containers CLI to perform migrations on your local machine. For more information, see Migrate to Containers CLI architecture.

This document describes how to upgrade your current installation of Migrate to Containers to version 1.15.0 and upgrade your Migrate to Containers plugins to the latest version.

You typically delete all existing migrations before you perform the upgrade. If any migrations are currently running, wait for them to complete and then delete them. However, do not delete your migration sources. Migration sources are updated as part of the upgrade process.

Note: If you are still using 1.8.x or previous versions of Migrate to Containers, then you can no longer upgrade to version 1.15.0.

Use migctl to perform the upgrade

The upgrade process you use is based on the environment where you run migctl:

• When using Google Kubernetes Engine (GKE) or GKE Enterprise processing clusters in Google Cloud, you run migctl in Cloud Shell.

  In Cloud Shell, the latest release of migctl is installed automatically. You then only have to upgrade your processing clusters.

• When using an Google Distributed Cloud Virtual for Bare Metal processing cluster, install migctl on your admin workstation.

  You first download and install the latest release of migctl on your on-prem admin workstation, then use it to upgrade your processing clusters.

Upgrade Migrate to Containers

To upgrade a previous release of Migrate to Containers to version 1.15.0:

1. Connect to your processing cluster:

   migctl on Google Cloud

   1. Visit the GKE menu in Google Cloud console.

      Visit the GKE menu

   2. In the list of clusters, locate the cluster you are using as a processing cluster and click its Connect button.

   3. In the Connect to the cluster dialog, under Command-line access, click Run in Cloud Shell to run the connect command in Cloud Shell.

      gcloud container clusters get-credentials cluster-name --zone zone-name --project project-name
      

   migctl on Google Distributed Cloud Virtual for Bare Metal

   1. Connect to your cluster. For more information, see Manage clusters from the Google Cloud console.

2. Check for any existing migrations and delete them:

   1. List current migrations:

      migctl migration list
      
      NAME                STATUS      CURRENT-OPERATION
      my-migration        Completed   GenerateArtifacts
      another-migration   Running     GenerateMigrationPlan

   2. Delete all completed migrations, one by one, using the following command:

      migctl migration delete my-migration

   3. For any migration that is currently running, repeat "Step a" above and wait for it to complete. Then delete it.

      Note: If you have any migrations in an error state, you do not have to delete them. Instead, you can perform the upgrade by including the --force option in the upgrade command: migctl setup upgrade --force. This option configures migctl to recreate any migrations in the error state as part of the upgrade to see if they can be completed.

3. Use the migctl version command to determine your current version. For example:

   migctl version

   Returns:

   Migrate to Containers version: 1.10.1

4. Upgrade the cluster:

   migctl on Google Cloud

   1. Upgrade to 1.15.0:

      1. In Cloud Shell run the command:

         migctl setup upgrade

         Note: If you cancel the upgrade for any reason by entering Ctrl+c, you can rerun it.

         The command:

         • Uninstalls the old version of Migrate to Containers, and installs version 1.15.0.

         • Upgrades existing migration sources to version 1.15.0.

   migctl on Google Distributed Cloud Virtual for Bare Metal

   1. Deploy migctl on your admin workstation:

      wget https://modernize-release.storage.googleapis.com/v1.15.0/linux/amd64/migctl
      sudo cp migctl /usr/local/bin/
      sudo chmod +x /usr/local/bin/migctl
      . <(migctl completion bash)

   2. Upgrade to 1.15.0:

      1. Run the upgrade:

         migctl setup upgrade --gkeop

         Note: If you cancel the upgrade for any reason by entering Ctrl+c, you can rerun it.

         The command:

         • Uninstalls the old version of Migrate to Containers, and installs version 1.15.0.

         • Upgrades existing migration sources to version 1.15.0.

5. Validate the upgrade by running the migctl doctor command.

   Before the upgrade has completed, you might see a message such as the following. If so, wait a few minutes for the upgrade to finish before running migctl doctor again.

   migctl doctor
   [✓] Deployment
     [✓] Admission Controller
     [!] Components
       Job controllers-deploy-cert is not ready
       Job controllers-upgrade is not ready
   

   In the following example output, the check mark indicates that Migrate to Containers has been successfully upgraded.

   migctl doctor
   [✓] Deployment
   [✓] Docker registry
   [✓] Artifacts repo
   [✓] Source Status
   

   If you are upgrading to version 1.6 or later, migctl doctor now displays the Docker registry, Artifacts repo, and Source Status fields, where:

   • Docker registry and Artifacts repo display [✓] if your data repositories are configured correctly. See Defining data repositories if there is an error associated with the Docker registry or artifacts repository.

   • Source Status shows [!] until you define your first migration source. See Adding a migration source more (Linux) or Adding a migration source more (Windows).

6. After the upgrade completes, you must recreate your migrations to validate that the migration sources were upgraded successfully. See Creating a migration.

Upgrade Migrate to Containers plugins

Migrate to Containers uses plugins to manage the modernization logic for different journeys of the supported workloads. To use the features available in the latest version of the plugins, you need to upgrade the plugins, and then create a new migration. Upgrading the plugins doesn't affect an ongoing migration.

Note: To upgrade the plugins to the latest version, you must first upgrade Migrate to Containers to version 1.15.0.

To upgrade the plugins to the latest version, run the following command:

JOB_NAME=plugins-updater-NAME
kubectl apply -f - <<EOF
apiVersion: batch/v1
kind: Job
metadata:
  name: $JOB_NAME
  namespace: v2k-system
spec:
  backoffLimit: 20
  template:
    spec:
      serviceAccountName: plugins-updater-sa
      containers:
      - name: plugins-updater
        image: us-docker.pkg.dev/migrate-modernize-public/modernize-plugins-prod/plugins-updater:latest
        imagePullPolicy: Always
      restartPolicy: OnFailure
EOF

Replace NAME with a string to add to your job name.

To view the status of the upgrade, run the following command:

kubectl get job -n v2k-system  plugins-updater-NAME

Replace NAME with the same string you added to your job name.

The output displays the status of the job, as shown below:

NAME                                COMPLETIONS   DURATION   AGE
plugins-updater-upgrade             1/1           12s        37s

If you see 1/1 in the Completions column, it means that the job is complete and the plugins are updated.

After the upgrade is complete, to delete the job, run the following command:

kubectl delete  job -n v2k-system  plugins-updater-NAME

Replace NAME with the same string you added to your job name.

What's next

• Learn how to define data repositories.