VMware announced the availability of the migration tool to migrate an on-premises VMware Cloud Director deployment to the VMware Cloud Director service in November 2022.
This blog will demonstrate how to perform a migration of an on-premises VMware Cloud Director deployment to the VMware Cloud Director service using the migration tool provided by VMware, as explained in the documentation How do I migrate from On-premises VMware Cloud Director to VMware Cloud Director service using the migration tool.
An overview of the necessary steps is:
- Set the requirements to run the migration tool if this is to be done from a Windows machine
- Create a migration.properties file to read into the migration tool
- Run the migration tool (download the latest version from https://github.com/vmware-samples/cloud-director-service-migration and extract to the host you want to perform the migration from
Before running the migration tool, install the necessary packages for Linux or on Windows, use a shell such as cygwin to run the tool. The instructions below demonstrate the migration tool on Windows using cygwin. See Migration Tool Prerequisites for a complete list of migration tool requirements.
For cygwin, install curl, jq, zip, ssh, scp, sshpass and md5sum.
Create a migration properties file
You don’t need to create the migration.properties file to perform a migration, but it makes it easier to see the data in a file, and if for some reason you need to run the script again, you don’t have to keep typing the same information in.
For cygwin, in the default location when you open it, CD to /tmp and create the file called migration.properties. Enter the following keys and their corresponding values:
- SITE_NAME – this is the VMware Cloud Director site name that will be migrated, such as vcd-site1
- SITE_ADMIN_USERNAME – this would generally be the admin account
- IS_APPLIANCE – tells the tool if VMware Cloud Director is an appliance deployment
- CSP_ORG_ID – this is the long organization ID for your organization in the VMware portal. For more information on how to find this information, see
- CSP_ORG_REFRESH_TOKEN – this is the token generated in the VMware portal to use to run tasks such as mappings, migrations and other functions. For more information, see How do I generate an API token.
- CELL_USERNAME – this would generally be root
- DBHOST_USERNAME – this will generally be root
Here is an example of a migration.properties file filled out.
SITE_NAME=vcd-01a.corp.local SITE_ADMIN_USERNAME=administrator IS_APPLIANCE=true CSP_ORG_ID=abcdef-ghjk-1234-5678-abcdef CSP_ORG_REFRESH_TOKEN=12345678910_Root_NAME USERNAME=root_DBBUSERNAME=root
Note that if your VMware Cloud Director instance is not publicly available, such as a lab instance for dev/test/UAT, you will need to add an extra line to the migration.properties file. The migration tool connects to the VCD to verify the version before attempting a migration and does so by connecting to the public DNS name specified in the migration.properties file, so if it is not publicly available, add the line below with the possible values in the file. link. You will have to replace version with the major version number being migrated, such as 10.3, 10.4, etc.
Below is an example of my completed migration.properties file with UPGRADE_CATEGORY added since the VCD instance is not publicly available.
If you run the migration script and for some reason it fails after the point where it starts reading in the migration.properties file, open the properties file and re-add the UPGRADE_CATEGORY line as it will be removed.
Once the migration.properties file is complete, save it and open your cygwin bash or whatever bash you are using. Navigate to the directory where the migration tool was extracted and run the script by running ./migrate.sh.
The script prompts you line by line to accept the values entered in the migration.properties file, or if the file does not exist, manually enter the information when prompted.
- Migration properties file found, want to reuse. Enter y to read entries from the properties file.
- On-prem VCD site FQDN name (found: name_from_file). Enter y to use the value from the properties file.
- On-prem VCD admin username (found: admin_user). Enter y to use the value from the properties file.
- Enter admin password for on-prem VCD site name_from_file. Enter the password for the admin account specified to connect to VCD.
- Is VCD name_from_file device based? Enter y to indicate that it is a device-based VCD.
- Username for cell name_from_file found. Enter y to use the user specified in the file.
- Enter password for cell name_from_file. Enter the password of the account specified to connect to the VCD device.
- CSP ORG ID found csp_org_from_file. Enter y to use the organization ID specified in the file.
- CSP ORG update token found token_from_file. Enter y to use the CSP organization token specified in the file.
- Enter CDI name to migrate: This will be the name of the CDS instance in the VMware portal. Enter the name you want the CDS to be called. Note that this will also be the site name in the VCD.
In the screenshot below, you can see that you have to answer each question per line.
The migration tool will collect the database information from the VCD database cell, upload it to an S3 bucket, create the CDS instance, and import the database dump into the new instance. You can see in the screenshot above on the last line in the bottom red box that it is dumping the database from vcd-01a.corp.local to prepare it to upload to an S3 bucket.
After the database dump completes, the script uploads the files to an S3 bucket to be imported to create the CDS instance. In the screenshot below, the top red box shows that the files were collected and then uploaded. The lower red box shows that the VMware Cloud Director on prem device being migrated is put into maintenance mode to avoid configuration changes between the migration and the CDS instance coming online.
You should now see the CDS instance that was migrated with the name specified during the migration.