How to Migrate VMware Cloud Director on-prem to VMware Cloud Director service

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 file to read into the migration tool
  • Run the migration tool (download the latest version from 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 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 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 file filled out.

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 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 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 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 file, open the properties file and re-add the UPGRADE_CATEGORY line as it will be removed.

Once the 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 ./

The script prompts you line by line to accept the values ​​entered in the 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.

When the appliance is in maintenance mode, you will see the steps completed to create the CDS instance and configure it. Once complete, you should see a final status showing success and the task ID that was completed for the migration.

You should now see the CDS instance that was migrated with the name specified during the migration.

When the installation is complete, in CDS, you will see that vCenter is displayed as disconnected. This is because there is no connection between CDS and vCenter/NSX-T until the reverse proxy has been deployed in the on-premises environment to facilitate communication. For instructions on completing the final step to establish this connection, see How do I attach a VMware Cloud Director instance to an SDDC via VMware Reverse Proxy.

Leave a Reply

Your email address will not be published. Required fields are marked *