Migrate a VM by using Migrate to Containers
In this quickstart, you create a simple Compute Engine virtual machine (VM), then use Migrate to Containers to migrate the VM to a Google Kubernetes Engine (GKE) processing cluster in the Cloud. This section refers strictly to Image Based System Container migrations.
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 to Containers migration environment on
Google Cloud. migctl
is available in Cloud Shell.
Before you begin
Enable support for Compute Engine
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.
- Enable the Compute Engine 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 Google Cloud CLI.
- Set up default Google Cloud CLI 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. -
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
- Follow the instructions to authorize the gcloud CLI to use your Google Cloud account.
- Create a new configuration or select an existing one.
- Choose a Google Cloud project.
- Choose a default Compute Engine zone.
- Choose a default Compute Engine region.
- Set your default project ID:
gcloud config set project PROJECT_ID
- Set your default Compute Engine region (for example,
us-central1
):gcloud config set compute/region COMPUTE_REGION
- Set your default Compute Engine zone (for example,
us-central1-c
):gcloud config set compute/zone COMPUTE_ZONE
- Update
gcloud
to the latest version:gcloud components update
gcloud init
gcloud config
By setting default locations, you can avoid errors in gcloud CLI like the
following: One of [--zone, --region] must be supplied: Please specify location
.
Create 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.
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
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
In the Google Cloud console, go to the VM instances page.
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.
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.
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
In the VM instances page, locate the row for the instance you created and copy the External IP address.
Paste the instance's IP address to your browser address bar. Prefix it with
http://
.You should now see the "Hello World!" page.
In the VM instances page, select the checkbox at the left end of the row for the instance you created.
At the top of the page, click the Stop button to stop the VM.
Create a processing cluster and install Migrate to Containers
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 to Containers and execute the migration.
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.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"
Install Migrate to Containers.
migctl
To enable Migrate to Containers to access Container Registry and Cloud Storage, you must create a service account with the storage.admin role:
In Cloud Shell, create the
m4a-install
service account:gcloud iam service-accounts create m4a-install \ --project=PROJECT_ID
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"
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
Connect to the cluster.
gcloud container clusters get-credentials migration-processing \ --zone zone --project project-id
In Cloud Shell, set up Migrate to Containers components on your processing cluster by using the
migctl
command-line tool included with Migrate to Containers:migctl setup install --json-key=m4a-install.json
Validate the Migrate to Containers 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
Console
Google Cloud console can help you with the installation process by generating the necessary installation commands and running them in Cloud Shell.
Open the Migrate to Containers page in the Google Cloud console.
Click Add Processing Cluster.
Select the cluster you created above,
migration-processing
, from the drop-down list.Execute each of the commands in Cloud Shell to:
- Create a service account that allows Migrate to Containers to access Container Registry and Cloud Storage.
- Install Migrate to Containers components.
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 to Containers has been successfully deployed.
migctl doctor [✓] Deployment [✓] Docker registry [✓] Artifacts repo [!] Source Status
Select Done after installation succeeds.
Qualify source workloads
For this quickstart, which uses a Compute Engine VM to serve up a simple "Hello World!" web page, you don't need to run fit assessment. However, for the typical case where you're migrating your own VMs, we recommend that you run the fit assessment tool. This tool runs on a VM workload to determine the workload's fit for migration to a container, and generates an assessment report that describes any issues that must be resolved before migration. For more information see About the fit assessment tool.
Migrate the VM
In the following steps, you create a migration plan with migration details, then use it to migrate the VM.
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:
In Cloud Shell, create the
m4a-ce-src
service account:gcloud iam service-accounts create m4a-ce-src \ --project=PROJECT_ID
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"
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"
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
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
Open the Migrate to Containers page in the Google Cloud console.
Click Add Source.
Select a cluster where you have already installed the Migrate to Containers components from the drop-down list .
Click Next.
Specify the name of the migration as
quickstart-source
.Set the Source type to Compute Engine.
Click Next.
Select the project that contains the VM that you want to migrate.
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.
Click Next.
Select Add Source.
Create a migration.
Create a migration by using the migctl
tool or the
Google Cloud console.
migctl on Google Cloud
Compute Engine
Stop the Compute Engine VM. The VM must be stopped for you to create a migration. After the migration completes, you can restart the VM.
Create the migration:
migctl migration create my-migration --source my-ce-src --vm-id my-id
Where
--vm-id
specifies the name of the Compute Engine instance as shown in the Google Cloud console.
VMware
migctl migration create my-migration --source my-vmware-src --vm-id My_VMware_VM
Where --vm-id
specifies the name of the VM instance. You can specify either the VM name,
such as MyVM2
, or the VM MoRef ID (Managed Object Reference ID), such as vm-14
.
See Before you begin for more on determining the VM ID.
AWS
migctl migration create my-migration --source my-aws-src --vm-id i-1234567890abcdef0
Where --vm-id
specifies the name of the VM instance. The name of the VM instance is shown in the AWS UI
and is in form i-##########
. See Before you begin for more on determining the VM ID.
Azure
migctl migration create my-migration --source my-azure-src --vm-id /subscriptions/a1b5c3d4-c3d9-a1a2-e5f6-a1t2c3d4k5f6/resourceGroups/MyResourceGroup/providers/Microsoft.Compute/virtualMachines/my-virtual-machine
Where --vm-id
specifies the name of the VM instance. The name of the VM instance is shown in the Azure UI.
See Before you begin for more on determining the VM ID.
migctl on VMware
migctl migration create my-migration --source local-vmware-src --vm-id My_VMware_VM
Where --vm-id
specifies the name of the VM instance. You can specify either the VM name,
such as MyVM2
, or the VM MoRef ID (Managed Object Reference ID), such as vm-14
.
See Before you begin for more on determining the VM ID.
migctl on AWS
migctl migration create my-migration --source local-aws-src --vm-id My_AWS_VM
Where --vm-id
specifies the name of the AWS instance.
See Before you begin for more on determining the VM ID.
Console
If the migration source is a Compute Engine VM, stop the Compute Engine VM. The VM must be stopped for you to create a migration. After the migration completes, you can restart the VM.
Open the Migrate to Containers page in the Google Cloud console.
Click the Migrations tab to display a table containing the available migrations.
Click Create Migration.
Enter the Migration name.
Select the migration source that you created in Adding a migration source.
Set the Workload type as Linux system container.
Enter the source VM ID. See Before you begin for more on determining the VM ID.
Click Create Migration.
When migration creation completes, the Status column displays Migration plan generated.
CRD
Create a Migration
my-migration.yaml
file to define a migration.In this file,
sourceProvider
specifies the name of a previously created SourceProvider andsourceId
specifies the name of the Compute Engine instance:apiVersion: anthos-migrate.cloud.google.com/v1beta2 kind: Migration metadata: name: my-migration namespace: v2k-system spec: appType: tomcat-container osType: Linux sourceSnapshot: sourceProvider: my-ce-src sourceId: my-id
If you are migrating a Compute Engine VM, stop the VM. The VM must be stopped for you to create a migration. After the migration completes, you can restart the VM.
Apply the file:
kubectl apply -f my-migration.yaml
Monitor migration creation
Use the migctl
tool or the Google Cloud console
to monitor the progress of migration creation.
migctl Google Cloud
Wait until the migration has completed:
migctl migration status my-migration NAME CURRENT-OPERATION PROGRESS STEP STATUS AGE my-migration GenerateMigrationPlan [1/3] CreateSourceSnapshots Running 13s
If you are migrating a Compute Engine VM, then restart it. The VM must be stopped for you to create a migration.
migctl on VMware
Wait until the migration has Completed:
migctl migration status my-migration NAME CURRENT-OPERATION PROGRESS STEP STATUS AGE my-migration GenerateMigrationPlan [1/3] CreateSourceSnapshots Running 13s
migctl on AWS
Wait until the migration has Completed:
migctl migration status my-migration NAME CURRENT-OPERATION PROGRESS STEP STATUS AGE my-migration GenerateMigrationPlan [1/3] CreateSourceSnapshots Running 13s
Console
When migration status show that the migration has been created, you can move on to the next step:
Open the Migrate to Containers page in the Google Cloud console.
Click the Migrations tab to display a table containing the available migrations.
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 detailed status, or the Events tab to see migration events.
When migration creation completes, the Status displays Migration plan generated.
If you are migrating a Compute Engine VM, then restart it. The VM must be stopped for you to create a migration.
CRD
Use kubectl
to get migration information and status by specifying a JSONPath
to the necessary field.
Get the migration operation:
kubectl get migrations.anthos-migrate.cloud.google.com -n v2k-system my-migration -o jsonpath={.status.currentOperation}
Returns
GenerateMigrationPlan
.Get the migration status:
kubectl get migrations.anthos-migrate.cloud.google.com -n v2k-system my-migration -o jsonpath={.status.status}
When the status shows that the operation has completed, you can move on to the next step.
If you are migrating a Compute Engine VM, then restart it. The VM must be stopped for you to create a migration.
- Review the migration plan.
You can edit the migration plan by using the migctl
tool or the Google Cloud console.
migctl
You must download the migration plan before you can edit it:
Download the migration plan. The plan is represented by GenerateArtifactsFlow:
migctl migration get my-migration
Edit the downloaded migration plan,
my-migration.yaml
, in a text editor.When your edits are complete, save and upload the revised migration plan:
migctl migration update my-migration --file my-migration.yaml
Repeat these steps if more edits are necessary.
Console
Edit the migration plan in the Google Cloud console by using the YAML editor.
Open the Migrate to Containers page in the Google Cloud console.
Click the Migrations tab to display a table containing the available migrations.
In the row for your desired migration, select the migration Name to open the Details tab.
Select the YAML tab.
Edit the migration plan as necessary.
When you are done editing, you can either:
Save the migration plan. You will then have to manually execute the migration to generate the migration artifacts. Use the procedure shown in Executing a migration.
Save and generate the artifacts. Execute the migration by using your edits to generate the migration artifacts. The process is the same as described in Executing a migration. You can then monitor the migration as described in Monitoring a migration.
CRD
You must download the migration plan, edit it, then apply it.
Get the name of the
GenerateArtifactsFlow
:kubectl get migrations.anthos-migrate.cloud.google.com -n v2k-system my-migration -o jsonpath={.status.resources.generateArtifacts.name}
The naming pattern is returned in the form of
generate-artifacts-flow-id
.Get the
GenerateArtifactsFlow
by name and write to a file namedmy-plan.yaml
:kubectl get generateartifactsflows.anthos-migrate.cloud.google.com -n v2k-system generate-artifacts-flow-id -o yaml > my-plan.yaml
Edit the migration plan as necessary.
Apply the file:
kubectl apply -f my-plan.yaml
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
<pre class="devsite-terminal" suppresswarning=true>
migctl migration status my-migration
</pre>
When the migration completes, you should see a message such as the following:
<pre class="devsite-terminal" suppresswarning=true>
migctl migration status my-migration
NAME CURRENT-OPERATION PROGRESS STEP STATUS AGE
my-migration GenerateArtifacts [1/1] ExtractImage Completed 14m23s</pre>
Console
0. Open the Migrate to Containers page in the Google Cloud console.
<p><a href="https://console.cloud.google.com/anthos/migrate" target="console" class="button button-primary">Go to the Migrate to Containers page</a></p>
0. 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.
0. When migration creation completes, the **Status** displays **Migration plan generated**.
Deploy the migrated workload
Use the
migctl migration generate-artifacts
command or the GCP Console to generate the target container artifacts as part of processing a VM for migration.migctl
migctl migration generate-artifacts my-migration
CRD
Create a GenerateArtifactsTask
my-generate.yaml
file to define a migration.In this file, set the value of the
name
field formigration
to the name you specified in the Migration yaml when you created the migration:apiVersion: anthos-migrate.cloud.google.com/v1beta2 kind: GenerateArtifactsTask metadata: name: my-migration-task namespace: v2k-system spec: migration: name: my-migration
Apply the file:
kubectl apply -f my-generate.yaml
Console
Open the Migrate to Containers page in the Google Cloud console.
Click the Migrations tab to display a table containing the available migrations.
In the row for the desired migration, select Generate artifacts in the Next steps dropdown.
View the status of a migration by:
Viewing the Status column for the row for your migration.
Clicking the migration Name. The migration Details tab opens. Click the Monitoring tab to see the status details, or the Events tab to see migration events.
When you generate artifacts for Tomcat workloads, Migrate to Containers writes the artifacts and then uploads them to a Cloud Storage bucket. The artifact directory file contains:
- Dockerfile - The Dockerfile used to build the image for your migrated VM.
deployment_spec.yaml
- The YAML file that configures your workload.
You can use
kubectl apply
with this file to deploy the workload to a cluster, such as a production or test cluster.- Directories and files that are extracted from the source and used by the Dockerfile.
To check the migration progress:
migctl
migctl migration status my-migration NAME CURRENT-OPERATION PROGRESS STEP STATUS AGE my-migration GenerateArtifacts [1/1] ExtractImage Running 12m2s
When the migration completes, you should see a message such as the following when you request status with migctl migration status.
migctl migration status my-migration NAME CURRENT-OPERATION PROGRESS STEP STATUS AGE my-migration GenerateArtifacts [1/1] ExtractImage Completed 14m23s
You can also add the
-v
flag to get error and warning information. See Monitoring a migration for more.CRD
Use
kubectl
to get execution information and status by specifying a JSONPath to the necessary field.Get the migration operation:
kubectl get migrations.anthos-migrate.cloud.google.com -n v2k-system my-migration -o jsonpath={.status.currentOperation}
Returns
GenerateArtifacts
.Get the migration status:
kubectl get migrations.anthos-migrate.cloud.google.com -n v2k-system my-migration -o jsonpath={.status.status}
When the status shows that the operation has completed, you can move on to the next step.
Console
Open the Migrate to Containers page in the Google Cloud console.
Click the Migrations tab to display a table containing the available migrations.
View the status of a migration by:
Clicking the migration name. The Migration details panel opens to display the migration status and other information.
Viewing the Status column for the row for your migration.
When the Status of the migration is Artifacts generated you can move on to the next step.
Add the
-v
flag to get error and warning information. See the next step for more information.Open the
deployment_spec.yaml
file and locate theService
object whose name isquickstart-instance
.Beneath the
Service
definition, paste anotherService
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
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.
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
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.