IBM Cloud Orchestrator, Version 2.5.0.1

Migrating a KVM region

Migrate a KVM region from the IBM® Cloud Orchestrator V2.4.0.2 environment to an IBM Cloud Manager with OpenStack controller in your IBM Cloud Orchestrator V2.5.0.1 environment.

Before you begin

Alert users that the IBM Cloud Orchestrator V2.4.0.2 region is going to be migrated and it cannot be used any more in the IBM Cloud Orchestrator V2.4.0.2 environment. Ensure that no new user or project is added in the IBM Cloud Orchestrator V2.4.0.2 environment until the entire environment is migrated. Additionally, ensure that no new toolkits are imported or modified and that no categories or offerings are created or updated. Any such changes you make after running this procedure must be manually applied to the IBM Cloud Orchestrator V2.5.0.1 environment.

Alert users who are using virtual machines which are being managed by the KVM region that the virtual machines are shut down for the duration of the migration process. The migration of the KVM region is an offline migration as a number of data resources such as virtual machines, disks, and volumes needs to be cloned and copied to the IBM Cloud Orchestrator V2.5.0.1 region before being re-enabled. Depending on the number and size of the virtual machines and volumes deployed on the compute nodes in the region, the end-to-end migration might take a number of hours.

Procedure

List the details of the information in the OpenStack databases in your IBM Cloud Orchestrator V2.4.0.2 environment and save these details so that after the migration procedure is completed, you can check that it worked correctly:
1. If this is the first region to be migrated, log in to the IBM Cloud Orchestrator V2.4.0.2 Central Server 2 as root and save the output of the following commands:
```
source ~/keystonerc
keystone endpoint-list
keystone user-list
```
2. Log in to the IBM Cloud Orchestrator V2.4.0.2 Region Server as root and save the output of the following commands:
```
source ~/openrc
glance image-list
heat stack-list
cinder list
neutron net-list
neutron subnet-list
nova list
nova image-list
nova flavor-list
```
If any recent change occurred in your environment topologies, discover the current topologies as described in step 7 in Preparing for the migration.
Migrate the OpenStack data by logging in to the IBM Cloud Orchestrator V2.5.0.1 Server as root and running the following procedure. When the migration is started, the IBM Cloud Orchestrator V2.4.0.2 region is disabled and the managed virtual machine instances are shut down.
1. Export the OpenStack data from the IBM Cloud Orchestrator V2.4.0.2 Region Server by running the following commands:
```
cd /opt/ico_install/V2501/installer
./upgrade.py ico_upgrade.rsp --export-region
```
  As part of the export script, the Region Server services are stopped and disabled and so they no longer manage the hypervisors. All the instances managed by the Region are also stopped to enable the offline compute node migration.
2. Import the OpenStack data that you exported from the IBM Cloud Orchestrator V2.4.0.2 Region Server to the IBM Cloud Manager with OpenStack controller by running the following command:
```
./upgrade.py ico_upgrade.rsp --import-region
```
3. Migrate all the KVM compute nodes in the region by following the procedure described in Migrating KVM compute nodes.
4. Migrate the Cinder volumes in the region by following the procedure described in Migrating Cinder volumes.
5. Start the services on the IBM Cloud Manager with OpenStack controller to complete the migration by running the following command:
```
./upgrade.py ico_upgrade.rsp --start-services
```
  When the start services command completes, the OpenStack services for that region are started and the IBM Cloud Manager with OpenStack controller is able to manage the migrated hypervisor resources again.
  Note: If any of the compute nodes are not visible in the OpenStack Dashboard after restarting the services for the region, you must manually restart the openstack-nova-compute service by running the following command as user root on the relevant nodes:
```
systemctl restart openstack-nova-compute
```
To validate the region migration, check details of what was imported in the IBM Cloud Manager with OpenStack controller and compare the details with what you saved in step 1.
Log in to the IBM Cloud Manager with OpenStack controller as root and run the following commands:
```
source ~/v3rc
openstack endpoint list
openstack user list
openstack project list
openstack domain list
openstack image list
heat stack-list
cinder list
openstack network list
neutron subnet-list
nova list
openstack server list
openstack flavor list
```
Check that the OpenStack Dashboard in the IBM Cloud Orchestrator V2.5.0.1 environment is working as expected.
Log in to the OpenStack Dashboard as admin at the following URL:
```
https://icm_controller_fqdn
```
where icm_controller_fqdn is the fully qualified domain name of the IBM Cloud Manager with OpenStack controller. Check that the details of the users, projects, networks, images, instances, and volumes are as expected.
Log in to the OpenStack Dashboard as a non-admin user and check that the details of the users, projects, networks, images, instances, and volumes are as expected.
Troubleshoot any issues which occurred during the region migration.
If you see any critical errors in the output during the migration which indicate that the migration was not successful, run the following steps:
1. To reduce system downtime during the debug process, roll the migrated region back to its state prior to migration by executing the following command:
```
./upgrade.py ico_upgrade.rsp --rollback-region
```
  This command re-enables the Region Server services which were stopped and disabled and remove any migration flags so that the discovery process considers the region as unmigrated.
2. Return the virtual machine instances back to their pre-migration state. Check the instance details of what you saved in step 1 taking into account which virtual machines were previously started. Log in to the IBM Cloud Orchestrator V2.4.0.2 Administration user interface and restart those instances which you noted.
3. Debug any errors that are displayed on the console output and check the export and import logs in the /opt/ico_install/V2501/installer/upgrade/logs directory for any further issues which may have occurred during the data migration.