Quickstart

In this quickstart, you create a simple Compute Engine virtual machine (VM), then use Migrate for Anthos and GKE to migrate the VM to a Google Kubernetes Engine (GKE) processing cluster in the Cloud.

You can perform the steps in the quickstart by using either the migctl tool or the Google Cloud Console. migctl is a command-line tool for setting up and managing a Migrate for Anthos and GKE migration environment on Google Cloud. migctl is available in Cloud Shell.

Before you begin

Enable support for Compute Engine

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

4. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

6. Enable the Compute Engine API.

   Enable the API

Enable and configure GKE

Before you start, make sure you have performed the following tasks:

• Ensure that you have enabled the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• Ensure that you have installed the Cloud SDK.
• Set up default gcloud command-line tool settings for your project by using one of the following methods:
• Use gcloud init, if you want to be walked through setting project defaults.
• Use gcloud config, to individually set your project ID, zone, and region.

gcloud init

1. Run gcloud init and follow the directions:

   gcloud init

   If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

   gcloud init --console-only

2. Follow the instructions to authorize the gcloud tool to use your Google Cloud account.
3. Create a new configuration or select an existing one.
4. Choose a Google Cloud project.
5. Choose a default Compute Engine zone.
6. Choose a default Compute Engine region.

Note: You can override these default settings in the gcloud tool by using the --project, --zone, and --region flags.

gcloud config

1. Set your default project ID:

   gcloud config set project PROJECT_ID

2. Set your default Compute Engine region (for example, us-central1):

   gcloud config set compute/region COMPUTE_REGION

3. Set your default Compute Engine zone (for example, us-central1-c):

   gcloud config set compute/zone COMPUTE_ZONE

4. Update gcloud to the latest version:

   gcloud components update

Note: You can override these default settings in the gcloud tool by using the --project, --zone, and --region flags.

By setting default locations, you can avoid errors in gcloud tool like the following: One of [--zone, --region] must be supplied: Please specify location.

Creating a VM with a web server

In the following steps, you create a simple Compute Engine VM that serves a "Hello World!" web page. Having the page gives you something to test after migration.

1. Run the following command to create the VM instance that you migrate.

   Specify a zone that is the same zone in which you create a GKE cluster later in this topic.

   gcloud compute instances create quickstart-instance \
     --project=project-id  --zone=zone --machine-type=e2-standard-2 \
     --subnet=default --scopes="cloud-platform" \
     --tags=http-server,https-server --image=ubuntu-minimal-1604-xenial-v20210119a \
     --image-project=ubuntu-os-cloud --boot-disk-size=10GB --boot-disk-type=pd-standard \
     --boot-disk-device-name=quickstart-instance
   

2. Run the following command to create a firewall rule that allows requests to the instance over HTTP.

   gcloud compute --project=project-id firewall-rules create default-allow-http \
     --direction=INGRESS --priority=1000 --network=default --action=ALLOW \
     --rules=tcp:80 --source-ranges=0.0.0.0/0 --target-tags=http-server
   

3. In the Google Cloud Console, go to the VM instances page.

   Go to the VM instances page

4. In the list of virtual machine instances, click SSH in the row of the instance you just created.

   For more on connecting by SSH, see Connecting to instances.

5. In the quickstart-instance command window, use the package manager to install the apache2 package.

   sudo apt-get update && sudo apt-get install apache2 -y
   

   After installing Apache, the operating system automatically starts the Apache server.

6. In the same command window, overwrite the Apache web server default web page with the following command:

   echo '<!doctype html><html><body><h1>Hello World!</h1></body></html>' | sudo tee /var/www/html/index.html
   

7. In the VM instances page, locate the row for the instance you created and copy the External IP address.

8. Paste the instance's IP address to your browser address bar. Prefix it with http://.

   You should now see the "Hello World!" page.

9. In the VM instances page, select the checkbox at the left end of the row for the instance you created.

10. At the top of the page, click the Stop button to stop the VM.

    Note: The VM must be stopped for you to migrate it. You can start it again after you create the migration below, either by using the Google Cloud Console or by using the 'migctl migration create' command.

Creating a processing cluster and installing Migrate for Anthos and GKE

In the following steps, you create a GKE cluster in the Cloud that you use as a processing cluster. This is where you install Migrate for Anthos and GKE and execute the migration.

1. In Cloud Shell, use the following command to create a new Kubernetes cluster to use as a processing cluster.

   When specifying the machine-type value, be sure to specify a machine type that has at least 15 GB of memory.

   Note: Be sure you specify the same zone here that you specified when creating the VM.

   gcloud container clusters create migration-processing \
     --project=project-id --zone=zone --machine-type e2-standard-4 \
     --image-type ubuntu --num-nodes 1 \
     --subnetwork "projects/project-id/regions/region/subnetworks/default"
   

2. Install Migrate for Anthos and GKE.

   migctl

   To enable Migrate for Anthos and GKE to access Container Registry and Cloud Storage, you must create a service account with the storage.admin role:

   1. In Cloud Shell, create the m4a-install service account:

      gcloud iam service-accounts create m4a-install \
        --project=PROJECT_ID

   2. Grant the storage.admin role to the service account:

      gcloud projects add-iam-policy-binding PROJECT_ID  \
        --member="serviceAccount:m4a-install@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/storage.admin"

   3. Download the key file for the service account:

      gcloud iam service-accounts keys create m4a-install.json \
        --iam-account=m4a-install@PROJECT_ID.iam.gserviceaccount.com \
        --project=PROJECT_ID 

   4. Connect to the cluster.

      gcloud container clusters get-credentials migration-processing \
        --zone zone --project project-id
      

   5. In Cloud Shell, set up Migrate for Anthos and GKE components on your processing cluster by using the migctl command-line tool included with Migrate for Anthos and GKE:

      migctl setup install --json-key=m4a-install.json
      

   6. Validate the Migrate for Anthos and GKE installation.

      Use the migctl doctor command to confirm a successful deployment.

      migctl doctor
      

      It may take more than a minute before the command returns the following success result.

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

      Note: Source Status shows [!] until you define your first migration source below.

   Console

   Google Cloud Console can help you with the installation process by generating the necessary installation commands and running them in Cloud Shell.

   1. Open the Migrate for Anthos and GKE page in the Cloud Console.

      Go to the Migrate to containers page

   2. Click Add Processing Cluster.

   3. Select the cluster you created above, migration-processing, from the drop-down list.

   4. Execute each of the commands in Cloud Shell to:

      • Create a service account that allows Migrate for Anthos and GKE to access Container Registry and Cloud Storage.
      • Install Migrate for Anthos and GKE components.
      Note: You are prompted to authorize Cloud Shell when you run the first command.

   5. Use the last Cloud Shell command to monitor the installation status.

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

      migctl doctor
      [!] Deployment
       validation job is in-progress
      

      In the following example output, the check mark indicates that Migrate for Anthos and GKE has been successfully deployed.

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

      Note: Source Status shows [!] until you define your first migration source below.

   6. Select Done after installation succeeds.

Migrating the VM

In the following steps, you create a migration plan with migration details, then use it to migrate the VM.

1. Specify the migration source as a Compute Engine VM. This step adds the source specification to the migration plan.

   migctl

   To use Compute Engine as a migration source, you must first create a service account with the compute.viewer and compute.storageAdmin roles:

   1. In Cloud Shell, create the m4a-ce-src service account:

      gcloud iam service-accounts create m4a-ce-src \
        --project=PROJECT_ID

   2. Grant the compute.viewer role to the service account:

      gcloud projects add-iam-policy-binding PROJECT_ID  \
        --member="serviceAccount:m4a-ce-src@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/compute.viewer"

   3. Grant the compute.storageAdmin role to the service account:

      gcloud projects add-iam-policy-binding PROJECT_ID  \
        --member="serviceAccount:m4a-ce-src@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/compute.storageAdmin"

   4. Download the key file for the service account:

      gcloud iam service-accounts keys create m4a-ce-src.json \
        --iam-account=m4a-ce-src@PROJECT_ID.iam.gserviceaccount.com \
        --project=PROJECT_ID 

   5. Create the migration source:

      migctl source create ce quickstart-source --project project-id --json-key=m4a-ce-src.json
      

      Where m4a-ce-src.json specifies the service account you created above.

   Console

   1. Open the Migrate for Anthos and GKE page in the Cloud Console.

      Go to the Migrate to containers page

   2. Click Add Source.

   3. Select a cluster where you have already installed the Migrate for Anthos and GKE components from the drop-down list .

   4. Click Next.

   5. Specify the name of the migration as quickstart-source.

   6. Set the Source type to Compute Engine.

   7. Click Next.

   8. Select the project that contains the VM that you want to migrate.

   9. Create a service account that enables you to use Compute Engine as a migration source by selecting Create a new service account. You are prompted to enter the name of the new service account.

   10. Click Next.

   11. Select Add Source.

2. Create a migration.

   migctl

   This command creates a migration plan that defines what to migrate.

   migctl migration create my-migration --source quickstart-source \
     --vm-id quickstart-instance --intent Image
   

   When the migration status shows that the migration has been created, you can move on to the next step:

   migctl migration status my-migration
   
   NAME           CURRENT-OPERATION      PROGRESS STEP                   STATUS   AGE
   my-migration   GenerateMigrationPlan  [1/3]    CreateSourceSnapshots  Running  13s

   Console

   1. Open the Migrate for Anthos and GKE page in the Cloud Console.

      Go to the Migrate to containers page

   2. Click Create Migration.

   3. Set the Migration name as migration.

   4. Select the migration source you created in the previous step: quickstart-source.

   5. Set the source VM name or ID to quickstart-instance.

   6. Set the Migration intent as Image.

   7. Click Create Migration.

      When the migration completes, the Status column displays Migration plan generated.

3. Review the migration plan.

   In this Quickstart, you only review the migration plan. However, you can also edit it. See Customizing a migration plan for more.

   migctl

   You must download the migration plan to review it:

   1. Download the migration plan:

      migctl migration get my-migration
      

   2. Open the downloaded migration plan, my-migration.yaml, in a text editor to review it.

   3. If you made any changes, upload the edited migration plan (no changes are required to complete the quickstart):

      migctl migration update my-migration --file my-migration.yaml
      

   Console

   Review the migration plan in the Google Cloud Console by using the YAML editor:

   1. In the row for the desired migration, select the migration Name to open the Details tab.

   2. Select the YAML tab.

   3. Review the migration plan.

   4. Click the "X" icon in the upper-right corner to close the plan without editing it.

4. Migrate the VM using the migration plan.

   This step migrates the VM and generate artifacts you can use to deploy the workload.

   migctl

   migctl migration generate-artifacts my-migration
   

   Console

   1. Open the Migrate for Anthos and GKE page in the Cloud Console.

      Go to the Migrate to containers page

   2. In the row for the desired migration, select Generate artifacts in the Next steps dropdown.

5. After the migration begins, check its status until it finishes.

   The migration can take several minutes. During this time, checking the status reports the migration's current state.

   migctl

   migctl migration status my-migration
   

   When the migration completes, you should see a message such as the following:

   migctl migration status my-migration
   
   NAME            CURRENT-OPERATION       PROGRESS        STEP            STATUS    AGE
   my-migration    GenerateArtifacts       [1/1]           ExtractImage    Completed 14m23s

   Console

   1. Open the Migrate for Anthos and GKE page in the Cloud Console.

      Go to the Migrate to containers page

   2. View the status of a migration by:

      • Viewing the Status column for the row for your migration.

      • Clicking the migration name. The Migration details page opens. Click the Monitoring tab to see the status details, or the Events tab to see migration events.

   3. When migration creation completes, the Status displays Migration plan generated.

Deploying the migrated workload

In the following steps, you get the deployment artifacts you generated during migration, then use them to deploy your migrated workload to the cluster. As a last step, you confirm that the "Hello World!" web page is available from your migrated app.

1. Once the migration is complete, download the generated YAML artifacts.

   migctl

   migctl migration get-artifacts my-migration
   

   Console

   1. Open the Migrate for Anthos and GKE page in the Cloud Console.

      Go to the Migrate for Anthos and GKE page

   2. Click the migration Name in the row for the desired migration. The migration Details tab for the VM opens.

   3. Select the Artifacts tab.

   4. Select Docker file, deployment spec and other artifacts to open the Cloud Storage bucket containing the artifacts.

   5. Select all files, then select Download.

      Note: If you enabled Cloud Audit Logs Data Access logs on the bucket, then attempting to download these files can return an HTTP 403 error. As a workaround:

      1. Select a file name in the bucket, such as Dockerfile, to view details about the file. Included in the details is the gsutil URI.

      2. For each artifact, use gsutil to download the artifact based on its gsutil URI:

         gsutil cp gsutil URI ./

         For example:

         gsutil cp gs://bucket-name/ae2e-7f-48-57-6be/Dockerfile ./

   The downloaded artifact files generated during the migration include:

   • deployment_spec.yaml -- The YAML file that configures your workload.
   • Dockerfile -- The Dockerfile used to build the image for your migrated VM.
   • migration.yaml -- A copy of the migration plan.
   • blocklist.yaml -- The list of container services to disable based on your settings in the migration plan. See Customizing the services list.
   • logs.yaml -- A list of log files detected on the source VM. Data written to these log files by the migrated workload is forwarded to Cloud Logging. See Customizing log data written to Cloud Logging.

2. Open the deployment_spec.yaml file and locate the Service object whose name is quickstart-instance.

3. Beneath the Service definition, paste another Service that exposes port 80 for access to your web server over HTTP, then save the file.

   Paste the highlighted code so that you have the following in your deployment spec.

   apiVersion: v1
   kind: Service
   metadata:
     creationTimestamp: null
     name: quickstart-instance
   spec:
     clusterIP: None
     selector:
       app: quickstart-instance
     type: ClusterIP
   status:
     loadBalancer: {}
   
   ---
   
   apiVersion: v1
   kind: Service
   metadata:
     name: hello-service
   spec:
     selector:
       app: quickstart-instance
     ports:
       - protocol: TCP
         port: 80
         targetPort: 80
     type: LoadBalancer
   
   

   ---

4. Apply the deployment spec YAML to deploy the workload.

   kubectl apply -f deployment_spec.yaml
   

   It may take a few minutes for the deployment to finish.

5. Check for an external IP address.

   kubectl get service hello-service
   

   When the web server is ready, you see an external IP address for the hello-service you added.

   kubectl get service hello-service
   NAME            TYPE           CLUSTER-IP      EXTERNAL-IP    PORT(S)        AGE
   hello-service   LoadBalancer   10.23.241.124   ##.##.###.##   80:32611/TCP   5m4s
   

6. Test the migration by opening a browser and visiting the web page at the external IP address (be sure to use HTTP, rather than HTTPS).

   http://##.##.###.##
   

You can execute bash commands on the container with your migrated workload. For more, see the Troubleshooting topic.

Clean up

To avoid unnecessary Google Cloud charges, use the Google Cloud Console to delete your project if you do not need it.

What's next

• Benefits of migrating to containers
• Migration journey to GKE
• Getting started