cloudstack/tools/migration/10to21Upgrade.txt

CloudStack Migration: 1.0.x to 2.1.x

How it works:

There are four major steps to migrating a 1.0.x system's data to version 2.1.x of the CloudStack:
    1. Users in the 1.0.x system need to be re-created in the 2.1.x system
    2. Public IPs that are allocated in the 1.0.x system need to be allocated in the 2.1.x sytem
    3. Port forwarding and load balancer rules that were created in the 1.0.x system need to be re-created in the 2.1.x system
    4. Virtual machines and the data on their root/data disks need to be migrated

To accomplish steps 1, 2, and 3, the CloudStack Migration tool automatically reads information from 1.0.x system's database and re-creates the data in the 2.1.x system through a combination of API calls and direct SQL inserts.
To accomplish step 4, the tool creates a direct link between 1.0.x storage servers and 2.1.x XenServers, and copies volume data using the XenServer API.

The overall process should take between 15-30 minutes per VM, depending on the speed of your private network and the size of the volumes involved. 


What you need:

1. A running 1.0.x system that has one zone and one pod.
2. Necessary hardware for the 2.1.x system: one or more management servers, and one or more XenServers that are all on the same public network as the 1.0.x system.
    * The 2.1.x management server must be able to access the 1.0.x management server's database, as well as the 1.0.x system's storage servers.
3. The 10to21Upgrade.tgz package.  



How to run the migration tool:

1. If you DO NOT have a 2.1.x system installed and running: Do a fresh 2.1.x install (please refer to the admin guide for instructions), taking into account the following special instructions:
        * Before you add any XenServer host, add one public IP range into the system with exactly two public IPs; these must be unallocated in the 1.0.x system.
	* After adding all of your XenServer hosts in the UI, verify that the secondary storage VM and console proxy VM started. Then, add remainining public IPs as a second IP range.

2. Register a bootable ISO and note down its database ID (you will need this for step 6). The OS of the ISO doesn't matter.
   If you already have a bootable ISO in the 2.1 system, you can use its database ID in step 6. 
        * If you have no preference about which ISO to use, simply enter the following URL to register an Ubuntu 10.04 ISO:
        http://localhost:8096/client/api?command=registerIso&bootable=true&zoneid=1&ispublic=true&name=Ubuntu&displayText=Ubuntu&url=http://ftp.ucsb.edu/pub/mirrors/linux/ubuntu/10.04/ubuntu-10.04.1-desktop-amd64.iso&ostypeid=59
        * Else, use the following API command (replacing variables as necessary):
        http://localhost:8096/client/api/?command=registerIso&bootable=true&zoneid=1&ispublic=true&name=ISO_NAME&displayText=ISO_DISPLAY_TEXT&url=ISO_URL&ostypeid=ISO_OS_TYPE_ID
        * To determine the ISO_OS_TYPE_ID, run the following API command and find the ID that corresponds to the OS of the ISO:
        http://localhost:8096/client/api/?command=listOsTypes
        
3. For every service offering in the 1.0.x system:
        * Make sure there is a service offering in the 2.1.x system with the same cpu #, cpu speed, and RAM size.
        * Make sure there is a disk offering in the 2.1.x system with the same disk size. 1.0.x allowed for creating service offerings with disk sizes that had an arbitrary number of MB.
          However, in 2.1.x, disk offerings must be created in multiples of 1 GB. If there is a service offering in the 1.0.x system with a disk size that is not a
          multiple of 1 Gb (1024 MB), create a disk offering in the 2.1.x system that is the 1.0.x disk size rounded to the next GB. For example, a disk size of 2000 MB in 1.0.x
          will correspond to a disk offering with size 2 GB in the 2.1.x system.

4. Install Python on the 2.1.x management server, if it isn't already installed. Version 2.4 or above is required.

5. Download 10to21Upgrade.tgz to any folder on the 2.1.x management server, and uncompress it.

6. Fill out upgrade.properties. Instructions about various fields are included in the file itself.

7. If you DO have a 2.1.x system installed and running:
        * Add a new public IP range in the 2.1.x system that corresponds to the public IP range in the 1.0.x system.
          The public IP ranges that already exist in the 2.1.x system must not overlap with the IP range in the 1.0.x system.
        * Run "python upgrade.py publicips". This will immediately allocate the public IPs of all users in the 1.0.x system, so that existing 2.1.x users can't allocate them.

8. Run "python upgrade.py" on the 2.1.x management server. Status information will be printed out to the console.
        * If there is an error, please contact Cloud.com Support and send us the migration log. By default, this file is called "migrationLog" and is in the same directory as upgrade.py. 
        * After the cause for an error has been resolved, you can run upgrade.py again from the beginning; it will skip over any work that has already been done.
        * If you would like to re-enable a user on 1.0.x system, simply stop all of the user's VMs that have been migrated on the 2.1.x system, and start the user's VMs on the 1.0.x system.