Create a migration plan

You begin migrating VMs by creating a migration. This results in a migration plan object. Further review and customization of the generated plan is typically required before proceeding to execute the migration.

A migration is the central object with which you perform migration actions, monitor migration activities and status with migctl and the Google Cloud console. The migration object is implemented as a Kubernetes Custom Resource Definition (CRD), and is contained along with additional resources such as a Kubernetes PersistentVolumeClaim in the migration plan.

Before you begin

Add a migration source.
Find the VM ID, as described in the following section.
When using Compute Engine as the migration source, stop the source VM before you to create a migration. After the migration object has been created, you can restart the VM.

Find the VM ID

You can find the VM ID by browsing the VM inventory, or by finding it manually, depending on the source type.

Find the ID using VM inventory

When using migctl, you can view a list of VMs by issuing the following command:
```
migctl source list-vms <name> [ --refresh ] [ --wide ]
```
When using the Google Cloud console, browse to the source type, and you'll find a table listing all VMs of that type.

Manually find the ID

You can find the VM ID manually by source type:

Compute Engine

vmId -- Name of the VM as it appears in the Google Cloud console.

VMware

vmId -- ID or name of the VM to migrate as it is known on the source platform. You can use one of the following values.
- The VM name. If you're confident that each VM name is unique across your VMware deployment, the simple VM name works. If VM names might be duplicated, use the VM ID as described below.
  
  You can get the VM name from the vSphere web client, as shown in the following image.
- The VM ID from vSphere (also called a MoRef). This is visible from the URL of the vSphere web client when selecting the VM.
  
  You can find also the MoRef by using PowerCLI.

Naming requirements

You assign a name to a migration when you create it in Migrate to Containers. The name must meet the following requirements:

Contain at most 63 characters.
Contain only lowercase alphanumeric characters or "-" (hyphen).
Start with an alphanumeric character.
End with an alphanumeric character.

Supported workloads

Create a migration

Linux and Windows workloads

Create a migration by using the migctl tool or the Google Cloud console.

migctl

Stop the 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-src --vm-id my-id --type server-type
```
Where --vm-id specifies the name of the VM instance as shown in the source type console. Where --type is either --type=windows-iis-container or linux-system-container.

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.

Go to the Migrate to Containers page
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 Image Based System Container or Windows IIS 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

To define a migration, create a Migration file called my-migration.yaml.

In this file, the name field under sourceProviderRef specifies the name of a previously created SourceProvider and sourceId field specifies the name of the Compute Engine instance. Type will be either --type=windows-iis-container or linux-system-container.
```
apiVersion: anthos-migrate.cloud.google.com/v1
kind: Migration
metadata:
 name: my-migration
 namespace: v2k-system
spec:
 type: linux-system-container
 sourceSnapshotTemplate:
   spec:
     sourceProviderRef:
       name: 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
```

Tomcat workloads

Specify CATALINA_BASE and CATALINE_HOME

If you want to manually specify the values forCATALINA_BASE and CATALINA_HOME, use the following instructions. Note that if you provide either of these values, the fit assessment collection will not be used.

migctl

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
--type tomcat-container --parameters catalina-base=/catalina/base/path/,catalina-home=/catalina/home/path/

Where --vm-id specifies the name of the instance as shown in the servic console.

CRD

Set the tomcat-container appxplugin default values of CATALINA_BASE and CATALINA_HOME.

Create patch-tomcat-container.yaml file, assuming both CATALINA_BASE and CATALINA_HOME values are /opt/tomcat

spec:
  defaultArguments:
    - name: catalina-base
      value: /opt/tomcat
    - name: catalina-home
      value: /opt/tomcat

Apply the patch using:

kubectl -n v2k-system  patch appxplugins.anthos-migrate.cloud.google.com tomcat-container -n v2k-system --type merge --patch-file patch-tomcat-container.yaml

To define a migration, create a Migration file called my-migration.yaml.

In this file, sourceProvider specifies the name of a previously created SourceProvider and sourceId field specifies the name of the Compute Engine instance:

apiVersion: anthos-migrate.cloud.google.com/v1
kind: Migration
metadata:
 name: my-migration
 namespace: v2k-system
spec:
 type: tomcat-container
 sourceSnapshotTemplate:
   spec:
     sourceProviderRef:
       name: 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
```

WebSphere workloads

Specify WAS_HOME

The WAS_HOME environment variable specifies where WAS is traditionally installed, such as /opt/IBM/WebSphere/AppServer/. Migrate to Containers uses this value when you create a migration to run scripts that fetch information about an app and to determine the path of an app profile.

Migrate to Containers attempts to locate the WebSphere installation folder automatically by using the fit assessment collection and searching common paths where Linux binaries are installed. If Migrate to Containers fails to locate the installation folder, or to override the folder determined by the automatic search, you can set the value of WAS_HOME.

If you want to manually specify the value for WAS_HOME, fit assessment collection will not be used.

migctl

Stop the 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-was-src --vm-id my-id
--type websphere-container --parameters /opt/IBM/WebSphere/AppServer/

Where --vm-id specifies the name of the instance as shown in the servic console.

CRD

Set the websphere-container appxplugin default value of WAS_HOME.

Create patch-websphere-container.yaml file, assuming the WAS_HOME value is /opt/IBM

spec:
  defaultArguments:
    - name: was_home
      value: /opt/IBM

Apply the patch using:

kubectl -n v2k-system  patch appxplugins.anthos-migrate.cloud.google.com websphere-container -n v2k-system --type merge --patch-file patch--container.yaml

To define a migration, create a Migration filed called my-migration.yaml.

In this file, sourceProvider specifies the name of a previously created SourceProvider and sourceId field specifies the name of the Compute Engine instance:

apiVersion: anthos-migrate.cloud.google.com/v1
kind: Migration
metadata:
 name: my-migration
 namespace: v2k-system
spec:
 type: websphere-container
 sourceSnapshotTemplate:
   spec:
     sourceProviderRef:
       name: 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
```

JBoss workloads

Create a migration by using the migctl tool or the Google Cloud console.

migctl

Stop the 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-src --vm-id my-id --type=jboss-container --parameters jboss-home=/opt/jboss

Where --vm-id specifies the name of the VM instance as shown in the source type console.

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.

Go to the Migrate to Containers page
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 JBoss container.
Enter the source Instance Name. See Before you begin for more on determining the Instance Name.
Set the JBOSS_HOME parameter, use the JBoss installation path.
Click Create Migration.

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

CRD

To define a migration, create a Migration file called my-migration.yaml.

In this file, the name field under sourceProviderRef specifies the name of a previously created SourceProvider and sourceId field specifies the name of the Compute Engine instance. For the type field, enter jboss-container. You can add a list of discovery parameters under discoveryParameters. Each discoveryParameters parameter has 2 properties: name and value. When creating a JBoss migration, the discoveryParameters parameter named jboss-home which specifies the JBoss home path as its value is mandatory.
```
apiVersion: anthos-migrate.cloud.google.com/v1
kind: Migration
metadata:
  name: my-migration
  namespace: v2k-system
spec:
  type: jboss-container2
  discoveryParameters:
  - name: jboss-home
    value: /path-to-jboss-home
  sourceSnapshotTemplate:
    spec:
      sourceProviderRef:
        name: 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
```

Apache workloads

Create a migration by using the migctl tool or the Google Cloud console.

migctl

Stop the 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-src --vm-id my-id --type=apache-container
```
Where --vm-id specifies the name of the VM instance as shown in the source type console.

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.

Go to the Migrate to Containers page
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 Apache 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

To define a migration, create a Migration file called my-migration.yaml.

In this file, the name field under sourceProviderRef specifies the name of a previously created SourceProvider and sourceId field specifies the name of the Compute Engine instance. For the type field, enter apache-container.
```
apiVersion: anthos-migrate.cloud.google.com/v1
kind: Migration
metadata:
 name: my-migration
 namespace: v2k-system
spec:
 type: apache-container
 sourceSnapshotTemplate:
   spec:
     sourceProviderRef:
       name: 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

Wait for the migration creation phase to end:

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. A stopped VM is not required after this step.

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.

Go to the Migrate to Containers page
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. A stopped VM is not required after this step.

CRD

Use kubectl to get migration information and status MigrationStatus by specifying a JSONPath to the necessary field.

Wait for the migration creation phase to end:

Use two kubectl wait commands, one to wait for the "Ready" condition and the other for the "Failed" condition. The migration plan creation phase is running until the first condition is met.
```
unset pids; for cond in "Ready" "Failed"; do kubectl wait migrations.anthos-migrate.cloud.google.com my-migration -n v2k-system --for condition=$cond --timeout=15m & pids+=($!); done; wait -p met_pid -n ${pids[@]}
kill ${pids[@]/$met_pid} # terminate the process that did not complete.
```
When the wait command completes, the operation has completed, you can move on to the next step.

Get the migration plan status:

kubectl get migrations.anthos-migrate.cloud.google.com -n v2k-system -o jsonpath={.status.conditions[?(@.type==\"Ready\")].status} my-migration

Returns True when the migration plan is ready or False when it failed.

When the migration creation phase fails, use the following command to get the error message:

kubectl get migrations.anthos-migrate.cloud.google.com -n v2k-system  -o jsonpath={.status.conditions[?(@.type=="Ready")].message} my-migration

If you are migrating a Compute Engine VM, then restart it. A stopped VM is not required after this step.

What's next

Linux

Migrate

Deploy

Review generated artifacts.
Configure logging.
Mounting external volumes.
Deploy a workload to a target cluster.
Deploy migrated VMs.
Post-migration image updates.
Monitor migrated workload.
Test your migrate app and validate the migration.