Migrating instances on a multi-cloud system

This feature is available in IBM® Cloud Pak System Version 2.3.4 and it enables users to migrate virtual system instances that are deployed on a multi-cloud environment profile to a remote multi-cloud environment profile. This move is a hot migration with minimal or zero downtime. This feature is available for only Linux virtual machines and is not applicable for Windows virtual system instances. The workload migration can be done only by using the REST API.

Before you begin migration, go through the Prerequisites section. The following prerequisites are reiterated for reference:
  • Take a backup of the virtual machines before you start the migration. If problems occur in migration, the backup helps to restore the virtual machines.
    Note: Though snapshots are migrated from the source to target, you cannot restore a snapshot that is taken on the source after the virtual machine is migrated to the target.
  • Make sure that no other migration is in running state. Only one migration is supported at a time. Run the following GET REST API to check whether only one migration is running then:
    GET REST Request URL: 
    http://9.9.9.9/admin/resources/migrate_deployment?state=running
    Note: In a multi-cloud system VSI migration, choose the source system where the source VSI was deployed (from the systems in the multi-cloud). Make sure that the target system is from the multi-cloud pair where the pattern was imported from the source system. Use the IP addresses of these source and target systems in the payload and target REST URL correctly for a smooth migration.
  • Make sure that Platform System Manager (PSM) services and compute nodes (CNS) are running and high availability (HA) is online.
  • Go through the Planning the migration, Known issues, and Troubleshooting sections.
Note: You can migrate by using the REST API only.
The POST method REST client with input parameters or payload: 
curl -k -X POST "https://<Target_System_IP_address>/admin/resources/migrate_deployment" --header "Content-Type: application/json" --header "X-IBM-PureSystem-API-Version: 1.0" --header "Authorization: Basic xyz" \
-d '{
   "source_deployment_id": "",
   "target_environment_profile_name": "",
   "target_cgs_for_mr": "",
   "instance_mapping": "",
   "source_rack_ipaddress": "",
   "source_admin_user": "",
   "source_admin_password": "",
   "name": "",
   "state": "",
   "target_ip_group": "",  
   "disable_multithread_vmrelocate": "",
   "deletion_timeout_min": "",
   "vm_user_credentials": "",
   "migration_type": "3"

}
Table 1. Values for input parameters or payload.
Type of instance Description
source_deployment_id It is the deployment ID of the source and is a mandatory parameter.
To retrieve the deployment ID, do the following steps:
  1. Log in to the source IBM Cloud Pak System.
  2. Go to IBM Workload Deployer > Virtual System Instance.
  3. Select the instance that you want to migrate.
  4. From the instance details, note down the ID.
target_environment_profile_name It is the target environment profile name and is a mandatory parameter.
To retrieve the target_environment_profile_name, do the following steps:
  1. Log in to the target IBM Cloud Pak System.
  2. Go to the Environment Profile page and note down the environment profile name.
Note: If the target_environment_profile_name is not available, then use target_environment_profile_id. For more information, see Known issues.
target_cgs_for_mr It is the array of all target cloud group names for each of the target virtual machines where workload is deployed and is a mandatory parameter.

To retrieve the target_cgs_for_mr, do the following steps:

  1. Log in to the target IBM Cloud Pak System.
  2. Go to the Environment Profile page and select your environment.
  3. Go to the Cloud Groups section and check whether the cloud group is available and is selected. Do this activity for each system in a multi-cloud pair.
target_cloud_group_name It is the target cloud group name where workload is deployed and is a mandatory parameter.
To retrieve the target_cloud_group_name, do the following steps:
  1. Log in to the target IBM Cloud Pak System.
  2. Go to the Environment Profile page and select your environment.
  3. Go to the Cloud Groups section and check whether the cloud group is available and is selected.
migration_type For multi-cloud virtual system instance migration, migration_type must be 3. The default value is 1. If you do not specify the value, then single-cloud migration is triggered.
instance_mapping This parameter consists of the placement information that is needed to place the virtual machine on the target system from the target multi-cloud system. The format is:
"['VM1_Name_from_VSI_Page':['source_rack_IP_where_VM1_is_deployed#target_rack_IP_where_VM1_will_be_deployed'], 'VM2_Name_from_VSI_Page':['source_rack_IP_where_VM2_is_deployed#target_rack_IP_where_VM1_will_be_deployed']]"
To retrieve the virtual machine name from the Virtual System Instances page, do these steps:
  1. Log in to the target IBM Cloud Pak System.
  2. Go to the Virtual System Instances page and select your instance.
  3. Expand Virtual machine perspective and check the name of each virtual machine.

    Local virtual machine names have hyperlinks, whereas remote virtual machines do not have hyperlinks. You can use these virtual machine names for instance_mapping.

Follow the same structure for all the virtual machines from the source deployment. '#' is used as a separator. Do not use any other special character.
source_rack_ipaddress It is the IP address of the source system and is a mandatory parameter.
source_admin_password It is the password credentials of the admin user of the source system.
target_ip_group It is a mandatory parameter.
Note:
  • All Network Interfaces that are associated to a virtual machine (source) is available in the Virtual System Instances page of the IBM Cloud Pak System user interface. Refer to those values before you construct your payload.
  • Migrations of virtual machines that have 7 or less NICs attached are only supported.
When you provide the payload, note these following points:

  • Specify the label followed by the IP group name. The format is 'ethX': '<IP group name>'.

    Here, the letter 'X' in the label denotes a number and it starts with 1.
    Note: The ethX is just a label in the payload to maintain the network interfaces in same sequence. It is not associated with the names of the NICs within virtual machines.
    Example: 
    target_ip_group:"['Windows':['eth1':'9xtarget','eth2':'9xtarget']]"

    In these examples, Windows is the node name and 9xtarget is the IP group name.

  • Verify whether all IPV4 network interfaces are captured in your construct.
  • The workload gets deployed and the source IP gets transferred in the provided IP group. Make sure that valid IP groups are available in the target environment profile and are attached with the target_environment_profile_name environment profile.
  • To retrieve the target_ip_group, do the following steps:
    1. Log in to the target IBM Cloud Pak System.
    2. Go to the Environment Profile page and select your environment.
    3. Expand your Cloud Groups and check whether the IP group is available and is selected.
name It is the name of the migration job and is an optional parameter.
state The value of the state is always start. It does not accept any other value.
premigration_validate It is an optional parameter and takes the following values:
  • yes/true

    Both validation and migration happen.

  • VALIDATE_ONLY

    Validation happens but no migration.

  • n/no/false

    Migration happens without validation.

Note: If no parameter is passed, validation gets triggered with default values. If validation is successful, then migration occurs. The default value is yes.
migration_timeout_min It is an optional attribute available as a part of the payload. Though you can customize this value, the default value of 60 minutes is sufficient for most of the migration use cases. This attribute must be used if the complete migration time extends beyond 60 minutes. You can specify any valid positive numeric value based on your requirement. The operation waits either until the migration is complete or the specified time is reached.
disable_multithread_vmrelocate It is relevant only for multi-virtual machine pattern migrations and is ignored for single virtual machine patterns. It is an optional boolean parameter with valid values “true” and “false”. At any particular point in time, there must not be more than one migration triggered on the target system. In few cases, it is observed that VMware encounters an issue when it relocates the two (or more than two) workloads simultaneously on target IBM Cloud Pak System. If this issue is observed, enable this flag to make it sequential automatically when you migrate the workload.
deletion_timeout_min It is an optional attribute. In few cases, after a successful Virtual System Instance migration on the target IBM Cloud Pak System, deletion of source Virtual System Instance might take extra time due to workload. Though the default value is 45 minutes, you can customize the time by using deletion_timeout_min parameter.
vm_user_credentials It is an optional attribute that is available as a part of the payload. This attribute must be used in the request payload when the Windows or Linux virtual machine password is changed before the migration.
Note: As a best practice, always provide a value for vm_user_credentials parameter.
For a single node: 
"vm_user_credentials": "['OS_Node':['user':'XXX','password':'YYY']]"
For a multi-node:
"vm_user_credentials": "['OS_Node':['user':'XXX','password':'YYY'], 'OS_Node_1':['user':'AAA','password':'BBB']]"
Note: The values of target_ip_group, target_environment_profile_name, and target_cloud_group_name are case-sensitive.
The following sample migrates a Virtual System Instance from source to target: 
curl -X POST \
  https://9.9.9.9/admin/resources/migrate_deployment \
  -H 'Authorization: Basic xyz' \
  -H 'Content-Type: application/json' \
  -H 'X-IBM-PureSystem-API-Version: 1.0' \  
  -d '{
"source_deployment_id": "d-4dc5-b45f-b2a932486385",
"migration_type": "3",
"target_environment_profile_name": "ep_ip",
"source_rack_ipaddress": "9.9.9.9",
"target_cgs_for_mr": "['OS_Node_1':' Mobility01','OS_Node':'Mobility02']",
"instance_mapping": "['OS_Node_1.11707155654444':[ 9.9.9.9#9.9.9.9'], 'OS_Node.11707155654220':['9.9.9.9#9.9.9.9']]",
"source_admin_user": "mob_source",
"source_admin_password": "mob_source",
"name": "Testmigration",
"state": "start",
"target_ip_group" : "['OS_Node':['eth0':'9xmob2','eth1':'10xmob2'], 'OS_Node_1':['eth0':'9xmob2','eth1':'10xmob2']]",
"migration_timeout_min" : "120",
"vm_user_credentials": "['OS_Node':['user':'XXX','password':'YYY'], 'OS_Node_1':['user':'XXX','password':'YYY']]"