Storage Migrate a vCloud Director VM using Rest API

If you are using vCloud Director in your environment and if you have ever tried doing a Storage vMotion of a VM from vSphere directly, you will notice a warning saying that its not recommended to modify the entity since its managed by VCD.


This is because of the the fact that with VCD, the management layer lies with itself and not with vSphere. All changes to the entities should be made via vCD and not vSphere.

Although doing a storage migration will not break anything but as a best practice we should avoid that.

So what to do if one of your backend LUN is full and you need to evacuate that by migrating some vm’s to another datastore which have enough free space. The answer is by using “Rest API”.

About the VMware vCloud API

The VMware vCloud API provides support for developers who are building interactive clients of VMware vCloud Director using a RESTful application development style. vCloud API clients communicate with servers over HTTP, exchanging representations of vCloud objects. These representations take the form of XML elements.

You use HTTP GET requests to retrieve the current representation of an object, HTTP POST and PUT requests to create or modify an object, and HTTP DELETE requests to delete an object.

To know more about vCD Rest API please read vCloud API Programming Guide.

Which tools to use?

There are various tools available on internet which can be used to interact with vCD Rest API. Most common tools include:

1: Postman Rest Client (chrome extension) which can be added to chrome from webstore.

2: Rest Client for firefox. It can be downloaded from here

3: Using curl which can be downloaded from here

Since I am fan of command line, in my lab I have installed curl on one of my linux box.

Once you have downloaded and installed curl, you can follow below steps to storage migrate your VM.

Note: I am using API calls against my environment which is hosted in vCloud Air

1: Generate session key 

The first thing to use API is to generate an Auth token which then can be passed to the later commands. You need to authenticate against VCD first to get a session token.

# curl -sik -H “Accept:application/*+xml;version=5.6” -u “Administrator@system:Administrator password” -X POST https://vCloud Director FQDN]/api/sessions



curl -sik -H “Accept:application/*+xml;version=5.6” -u “admin@system” -X POST | grep auth

Enter host password for user ‘admin@system’:

x-vcloud-authorization: d18d26b54cb346c8a9a097ab24d7edf


Once you receive auth token, we have to change the header in above command to:

“x-vcloud-authorization: Auth Token”

2: Get Otg UUID

Next is to grab the Org UUID by executing below command:

# curl -sik -H “Accept:application/*+xml;version=5.6” -H “x-vcloud-authorization: d18d26b54cb346c8a9a097ab24d7edf” -X GET | grep bdd75fd4-a319-47d5-b4f2-77aad691488f

The above command will give you href to org URL


<Org href=”″ name=”bdd75fd4-a319-47d5-b4f2-77aad691488f” type=”application/”/>


3: Get Org VDC UUID

# curl -sik -H "Accept:application/*+xml;version=5.6" -H "x-vcloud-authorization: d18d26b54cb346c8a9a097ab24d7edf" -X GET | grep vdc

<Link rel="down" href="" name="Manish-Lab-DontDel" type="application/vnd.vmware.vcloud.vdc+xml"/>

4: Get list of vApps

curl -sik -H “Accept:application/*+xml;version=5.6” -H “x-vcloud-authorization: d18d26b54cb346c8a9a097ab24d7edf” -X GET | grep vapp

The above command will give you full list of all the vApps which you have created in vCD


<ResourceEntity href=”″ name=”Esxi” type=”application/vnd.vmware.vcloud.vAppTemplate+xml”/>

<ResourceEntity href=”” name=”Openfiler” type=”application/vnd.vmware.vcloud.vApp+xml”/>

<ResourceEntity href=”″ name=”CASRV01-VApp” type=”application/vnd.vmware.vcloud.vApp+xml”/>

<ResourceEntity href=”” name=”Esxi-2″ type=”application/vnd.vmware.vcloud.vApp+xml”/>

<ResourceEntity href=”″ name=”vCenterSrv” type=”application/vnd.vmware.vcloud.vApp+xml”/>

<ResourceEntity href=”″ name=”Esxi-1″ type=”application/vnd.vmware.vcloud.vApp+xml”/>

<ResourceEntity href=”″ name=”Alex-DC-VApp” type=”application/vnd.vmware.vcloud.vApp+xml”/>



5: Get VM UUID

Since now we have href to the vApps, we can now get UUID of the VM which we are planning to move to other datastore.

# curl -sik -H “Accept:application/*+xml;version=5.6” -H “x-vcloud-authorization: d18d26b54cb346c8a9a097ab24d7edf” -X GET

6: Get list of datastores

# curl -sik -H “Accept:application/*+xml;version=5.6” -H “x-vcloud-authorization: d18d26b54cb346c8a9a097ab24d7edf” -X GET

This query will return a lot of info about the datastores like provisioned storage, used space, free space available on datastore, datastore Mo-ref and href to datastores.


<DatastoreRecord datastoreType=”VMFS5″ isDeleted=”false” isEnabled=”true” moref=”datastore-108014″ name=”z_d10p15s3vnx0lu66_tStd_inuse” numberOfProviderVdcs=”1″ provisionedStorageMB=”13059087″ requestedStorageMB=”6521317″ storageMB=”10485504″ storageUsedMB=”7595588″ vc=”″ vcName=”vc-fqdn” href=”“/>

<DatastoreRecord datastoreType=”VMFS5″ isDeleted=”false” isEnabled=”true” moref=”datastore-19022″ name=”z_d10p15s3vnx0lu57_tSSDAcc_inuse” numberOfProviderVdcs=”1″ provisionedStorageMB=”7991302″ requestedStorageMB=”8479229″ storageMB=”10485504″ storageUsedMB=”2016348″ vc=”″ vcName=”vc-fqdn” href=”“/>

<DatastoreRecord datastoreType=”VMFS5″ isDeleted=”false” isEnabled=”true” moref=”datastore-17670″ name=”z_d10p15s3vnx0lu51_tStd_inuse” numberOfProviderVdcs=”1″ provisionedStorageMB=”12538920″ requestedStorageMB=”10196156″ storageMB=”10485504″ storageUsedMB=”6006352″ vc=”″ vcName=”vc-fqdn” href=”“/>

<DatastoreRecord datastoreType=”VMFS5″ isDeleted=”false” isEnabled=”true” moref=”datastore-17671″ name=”z_d10p15s3vnx0lu56_tSSDAcc_inuse” numberOfProviderVdcs=”1″ provisionedStorageMB=”8810546″ requestedStorageMB=”8773278″ storageMB=”10485504″ storageUsedMB=”7094757″ vc=”″ vcName=”vc-fqdn” href=”“/>

<DatastoreRecord datastoreType=”VMFS5″ isDeleted=”false” isEnabled=”true” moref=”datastore-19203″ name=”z_d10p15s3vnx0lu58_tSSDAcc_inuse” numberOfProviderVdcs=”1″ provisionedStorageMB=”6293195″ requestedStorageMB=”6070760″ storageMB=”10485504″ storageUsedMB=”2509893″ vc=”″ vcName=”vc-fqdn” href=”“/>

<DatastoreRecord datastoreType=”VMFS5″ isDeleted=”false” isEnabled=”true” moref=”datastore-66433″ name=”z_d10p15s3vnx0lu65_tStd_inuse” numberOfProviderVdcs=”1″ provisionedStorageMB=”7326909″ requestedStorageMB=”4607043″ storageMB=”10485504″ storageUsedMB=”3819394″ vc=”″ vcName=”vc-fqdn” href=”“/>


7: Find out datastore name where your VM is residing

To do this, dump the VM settings into an xml file and grep for datastore.

# curl -sik -H “Accept:application/*+xml;version=5.6” -H “x-vcloud-authorization: d18d26b54cb346c8a9a097ab24d7af0c” -X GET > vminfo.xml

# cat vminfo.xml | grep datastore




You can match the Mo-Ref returned with output of query 6 and you will know the name of the datastore where your VM is presently residing.

8: Prepare for migration

Now before we start migration, we need to create an input file which contains the destination datastore UUID where we want to send the VM. We will supply the input file alongwith API query to perform the storage migration.

Note: In output of query 6, we got a bunch of datastore alongwith details of free space on each datastore. You can select that datastore which has  max available free space.

Info about the necessary parameters can be obtained from API Schema guide

I created a file named ‘dest-ds.xml’ with below content:

<?xml version=”1.0″ encoding=”UTF-8″?>
<RelocateParams xmlns=”″>
<Datastore href=”” />

Make sure formatting is correct in the xml file else you will get error. My XML file looks like


If you have trouble with xml formatting, you can go to Online XML formatter and paste your text in XML Formatter area and click on Format XML


You will see the formatted xml as output


9: Perform the migration of VM

# curl -sik -H “Accept:application/*+xml;version=5.6” -H “x-vcloud-authorization: d18d26b54cb346c8a9a097ab24d7af0c” -H “Content-Type:application/vnd.vmware.vcloud.relocateVmParams+xml” -d @dest-ds.txt -X POST 

The above will generate a task id:

HTTP/1.1 202 Accepted
Date: Sat, 24 Dec 2016 13:39:22 GMT
Strict-Transport-Security: max-age=15768000; includeSubDomains
X-Frame-Options: SAMEORIGIN
x-vcloud-authorization: XXXXXXX

If you have access to backend vSphere, you can see the migration task there



In case if you dont have access to backend, you can monitor the migration process by using below query

# curl -sik -H “Accept:application/*+xml;version=5.6” -H “x-vcloud-authorization: d18d26b54cb346c8a9a097ab24d7af0c” -X GET | grep Progress


if the progress reads 100, it means migration have been completed.

I hope this post is informational to you. Feel free to share this on social media if it is worth sharing. Be sociable 🙂


One Comment

Add a Comment