posted

14 Comments

By William Lam, Sr. Technical Marketing Engineer

In Part 1 of this article, I provide an overview of how to uniquely identify a virtual machine in both a vSphere vCenter and vCloud Director environment. In this article, we will look at an example environment and show you how to extract the information needed to uniquely identify a VM using both the vSphere API and vCloud API.

vSphere

We will begin by just looking at a vSphere environment (no vCloud Director). In the screenshot below, we have two different vCenter Servers (westcoast-vcenter and eastcoast-vcenter) and they are managing a single ESXi host each with a single VM.

If you recall from Part 1, to uniquely identify a VM in vSphere, we can use either the MoRef ID or instanceUUID. Using the following vSphere SDK for Perl script vmMoRefinder.pl (modified version of this script), we will take a look at these properties. To run the script you will need to have VMware vCLI installed on either a Windows/Linux system or you can use the VMware vMA appliance.

If you prefer to use PowerCLI then this script will perform similar actions to the Perl script.

Here is the Perl script running against the westcoast-vcenter:
$ ./vmMoRefFinder.pl –server westcoast-vcenter –username root –name MyVM1

Name: MyVM1
VM MoRe: vm-14
VM InstanceUUID: 501b8bde-95da-472a-4d2d-9d97ea394bbc
vCenter Name: westcoast-vcenter
vCenter InstanceUUID: 9B6C7A60-C60F-4C1D-A607-0A0CFA2C2D5A

Here is the Perl script running against the eastcoast-vcenter:
$ ./vmMoRefFinder.pl –server eastcoast-vcenter –username root –name MyVM2

Name: MyVM2
VM MoRef: vm-14
VM InstanceUUID: 502fb1ca-e9b8-82ae-3f9f-4a3ba85f081d
vCenter Name: eastcoast-vcenter
vCenter InstanceUUID: 63D30391-44E2-447E-A709-9DD1241C3DCC

Here is the PowerCLI script running when connected to both vCenter Servers:

Name                     : MyVM1
VM MoRef             : vm-14
VM InstanceUUID      : 501b8bde-95da-472a-4d2d-9d97ea394bbc
vCenter Name         : westcoast-vcenter
vCenter InstanceUUID : 9B6C7A60-C60F-4C1D-A607-0A0CFA2C2D5A

Name                     : MyVM2
VM MoRef             : vm-14
VM InstanceUUID      : 502fb1ca-e9b8-82ae-3f9f-4a3ba85f081d
vCenter Name         : eastcoast-vcenter
vCenter InstanceUUID : 63D30391-44E2-447E-A709-9DD1241C3DCC

Here is the same data in a table format for the two vCenter Servers:

vCenter Servers vCenter InstanceUUID VM MoRef VM InstanceUUID
westcoast-vcenter 9B6C7A60-C60F-4C1D-A607-0A0CFA2C2D5A vm-14 501b8bde-95da-472a-4d2d-9d97ea394bbc
eastcoast-vcenter 63D30391-44E2-447E-A709-9DD1241C3DCC vm-14 502fb1ca-e9b8-82ae-3f9f-4a3ba85f081d

Do you notice something interesting about the MoRef ID for the two different VMs that are hosted and managed by two different vCenter Servers? Yes, they are the same, but you might ask why is that? I thought we said MoRef ID is a unique identifier? As mentioned in Part, a MoRef ID is guaranteed to be unique, but only within the same vCenter Server. There is a possibility of seeing duplicate MoRef ID as shown with the example above and there is also possibility of seeing duplicate instanceUUID for a VM as well.

To uniquely identify a VM across vCenter Servers, you should use the combination of the unique identifier for a vCenter Server which is instanceUUID with either the VM’s MoReF ID or InstanceUUID (e.g. 9B6C7A60-C60F-4C1D-A607-0A0CFA2C2D5A-vm-14)

vCloud

Let’s say we are now interested in running vCloud Director and decide to import our existing VMs into vCloud Director. You have two import options: copy or move, “copy” will create a duplicate VM in vCloud Director and “move” will just move the same VM into the proper resource pool and VM folder being managed by vCloud Director. If you want to preserve the same instanceUUID and MoReF ID of the VM as you go from vSphere vCenter to vCloud Director, ensure you are performing the move operation.

Here is a screenshot of our two vCenter Servers now in a vCloud Director configuration

If you recall from Part 1, to uniquely identify a VM in vCloud Director, we need to use the href property. We will be using the curl utility, which is normally installed on most UNIX/Linux system to interact with the vCloud API. You can also use other REST tools such as RESTClient Firefox plugin if you do not want to use curl. You will need an account with the “System Administrator” role, which is specific to a group that only a vCloud Administrator (provider side) should use.

First we need to login to vCloud Director to retrieve authorization token that will be used throughout this example. In this example, we are connecting to a vCloud Director 1.5 instance and we need to set the header appropriately using -H option based on the version of vCloud Director you are using. The username/password is in the form of ‘username@org:password’ using the -u option and this will be a POST operation. Ensure you substitute the URL of your vCloud Director server. To get more information about the options used below, refer to the curl documentation or use man -k curl:

$ curl -i -k -H “Accept:application/*+xml;version=1.5” -u ‘administrator@system:vmware1!’ -X POST https://vcd/api/sessions

HTTP/1.1 200 OK
Date: Wed, 08 Feb 2012 23:26:12 GMT
x-vcloud-authorization: q7uX9eIAWQ0FegrrskkvTOPXiAo31wESTJ6ah5FRyE0=
Set-Cookie: vcloud-token=q7uX9eIAWQ0FegrrskkvTOPXiAo31wESTJ6ah5FRyE0=; Secure; Path=/
Content-Type: application/vnd.vmware.vcloud.session+xml;version=1.5
Date: Wed, 08 Feb 2012 23:26:12 GMT
Content-Length: 910

<?xml version=”1.0″ encoding=”UTF-8″?>
<Session xmlns=”http://www.vmware.com/vcloud/v1.5″ user=”administrator” org=”System” type=”application/vnd.vmware.vcloud.session+xml” href=”https://vcd/api/session/” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://www.vmware.com/vcloud/v1.5 http://10.20.181.101/api/v1.5/schema/master.xsd”>
    <Link rel=”down” type=”application/vnd.vmware.vcloud.orgList+xml” href=”https://vcd/api/org/”/>
    <Link rel=”down” type=”application/vnd.vmware.admin.vcloud+xml” href=”https://vcd/api/admin/”/>
    <Link rel=”down” type=”application/vnd.vmware.admin.vmwExtension+xml” href=”https://vcd/api/admin/extension”/>
    <Link rel=”down” type=”application/vnd.vmware.vcloud.query.queryList+xml” href=”https://vcd/api/query”/>
    <Link rel=”entityResolver” type=”application/vnd.vmware.vcloud.entity+xml” href=”https://vcd/api/entity/”/>
</Session>

If you successfully logged in, you will get an HTTP return code of 200 and the vCloud authorization token like the above highlighted in red. Make sure you verify the version of vCloud API by looking at the schemaLocation which is highlighted above in green.

Next, to find our two VMs in vCloud Director, we will leverage the new Query API. Since we only have two VMs, we can just search for all “adminVM” without the need of filtering. If you have more VMs, you may want to craft a filter and you can find more details in the Query API documentation.

Using the authorization token return from the previous command, we now pass that instead of the username/password and this will be a GET operation to the URL listed below:

$ curl -i -k -H “Accept:application/*+xml;version=1.5” -H “x-vcloud-authorization: q7uX9eIAWQ0FegrrskkvTOPXiAo31wESTJ6ah5FRyE0=-X GET https://vcd/api/query?type=adminVM

HTTP/1.1 200 OK
Date: Wed, 08 Feb 2012 23:27:20 GMT
Content-Type: */*;version=1.5
Date: Wed, 08 Feb 2012 23:27:20 GMT
Content-Length: 2428

……..
    <AdminVMRecord vmToolsVersion=”0″ vdc=”https://vcd/api/vdc/9f913a23-3d6c-44bf-95a4-8c47563fafa7″ vc=”https://vcd/api/admin/extension/vimServer/337a4193-de37-43c0-90ab-08d082766c96″ status=”POWERED_OFF” org=”https://vcd/api/org/0d020a29-90de-4000-a0ec-c8a630e65c61″ numberOfCpus=”1″ networkName=”VM Network” name=”MyVM1″ moref=”vm-14″ memoryMB=”256″ isVdcEnabled=”true” isVAppTemplate=”false” isPublished=”false” isDeployed=”false” isDeleted=”false” hostName=”10.20.182.92″ hardwareVersion=”8″ guestOs=”Other Linux (32-bit)” datastoreName=”vesxi50-1-local-storage” containerName=”MyVM1″ container=”https://vcd/api/vApp/vapp-0f5bdc4c-a0ec-4e6e-a8a0-cdec1bf89de0″ href=”https://vcd/api/vApp/vm-51201e8b-f910-40ab-b2b1-e5365a72f353″ pvdcHighestSupportedHardwareVersion=”8″ containerStatus=”RESOLVED”/>
    <AdminVMRecord vmToolsVersion=”0″ vdc=”https://vcd/api/vdc/c7022e00-dbf3-458c-b118-2cfee5250218″ vc=”https://vcd/api/admin/extension/vimServer/ebcad5a3-4356-4059-8d56-16c52c23dc1a” status=”POWERED_OFF” org=”https://vcd/api/org/ecd25f40-62d7-4009-9924-25db4df27774″ numberOfCpus=”1″ networkName=”VM Network” name=”MyVM2″ moref=”vm-14″ memoryMB=”256″ isVdcEnabled=”true” isVAppTemplate=”false” isPublished=”false” isDeployed=”false” isDeleted=”false” hostName=”10.20.182.95″ hardwareVersion=”8″ guestOs=”Other Linux (32-bit)” datastoreName=”vesxi50-2-local-storage” containerName=”MyVM2″ container=”https://vcd/api/vApp/vapp-ce7e478b-9200-45db-851b-f21657156fd2″ href=”https://vcd/api/vApp/vm-ab59412f-b6c8-424d-bc0e-1414e1341084″ pvdcHighestSupportedHardwareVersion=”8″ containerStatus=”RESOLVED”/>
</QueryResultRecords>

Here is the same data in a table format for the two VMs in vCloud Director:

VM Name MoRef HREF
MyVM1 vm-14 https://vcd/api/vApp/vm-51201e8b-f910-40ab-b2b1-e5365a72f353
MyVM2 vm-14 https://vcd/api/vApp/vm-ab59412f-b6c8-424d-bc0e-1414e134108

You should see a list of VM records found in vCloud Director and there are three properties that are of interest which are highlighted: name, moref and href. The first two are pretty self-explanatory and we can see that the MoRef ID has not changed when we performed the “move” import operation into vCloud Director. We also see the href property which is the unique identifier for a VM in vCloud Director. The reason for this is vCloud Director uses a single database and the generation of the UUID for a VM is unique and as part of the URL, it also includes the specific vCloud Director Cell address managing that VM instance.

To uniquely identify a VM across multiple vCloud Director Cells managing multiple vCenter Servers, you should use the href property.

vSphere and vCloud

Now that we can uniquely identify a VM in either a vSphere or vCloud environment, how do we go about correlating the two and go from a VM in vCloud Director back to a VM in vSphere vCenter? Continuing from our previous command, we can retrieve more information about the VM, which will provide the necessary details to map back to a vSphere vCenter Server.

Using the href value for the VM we are interested in, we wiill perform a GET operation on the URL:

$ curl -i -k -H “Accept:application/*+xml;version=1.5” -H “x-vcloud-authorization: q7uX9eIAWQ0FegrrskkvTOPXiAo31wESTJ6ah5FRyE0=” -X GET https://vcd/api/vApp/vm-51201e8b-f910-40ab-b2b1-e5365a72f353

HTTP/1.1 200 OK
Date: Wed, 08 Feb 2012 23:28:14 GMT
Content-Type: application/vnd.vmware.vcloud.vm+xml;version=1.5
Date: Wed, 08 Feb 2012 23:28:14 GMT
Content-Length: 14519

……..
    <VCloudExtension required=”false”>
       <vmext:VmVimInfo>
           <vmext:VmVimObjectRef>
               <vmext:VimServerRef type=”application/vnd.vmware.admin.vmwvirtualcenter+xml” name=”westcoast-vcenter” href=”https://vcd/api/admin/extension/vimServer/337a4193-de37-43c0-90ab-08d082766c96″/>
               <vmext:MoRef>vm-14</vmext:MoRef>
               <vmext:VimObjectType>VIRTUAL_MACHINE</vmext:VimObjectType>
           </vmext:VmVimObjectRef>
           <vmext:DatastoreVimObjectRef>
               <vmext:VimServerRef type=”application/vnd.vmware.admin.vmwvirtualcenter+xml” name=”westcoast-vcenter” href=”https://vcd/api/admin/extension/vimServer/337a4193-de37-43c0-90ab-08d082766c96″/>
               <vmext:MoRef>datastore-10</vmext:MoRef>
               <vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
           </vmext:DatastoreVimObjectRef>
           <vmext:HostVimObjectRef>
               <vmext:VimServerRef type=”application/vnd.vmware.admin.vmwvirtualcenter+xml” name=”westcoast-vcenter” href=”https://vcd/api/admin/extension/vimServer/337a4193-de37-43c0-90ab-08d082766c96″/>
               <vmext:MoRef>host-9</vmext:MoRef>
               <vmext:VimObjectType>HOST</vmext:VimObjectType>
           </vmext:HostVimObjectRef>
           <vmext:VirtualDisksMaxChainLength>1</vmext:VirtualDisksMaxChainLength>
       </vmext:VmVimInfo>
    </VCloudExtension>
……..

You can see there is a lot of information returned about the VM such as configurations and settings, but it also includes the vCloud Extension information that contains details about the underlying vSphere properties such as the vSphere VM MoRef ID, Datastore and ESXi host managing the VM. The two properties that we should key on is highlighted: vmext:MoRef and vmext:VimServerRef. The latter property provides information about the vCenter Server that is currently managing the VM in question. We need to perform one additional query using it’s href property.

To get details about the vCenter Server, we will perform another GET operation using the vCenter Server href URL provided from the last example:

$ curl -i -k -H “Accept:application/*+xml;version=1.5” -H “x-vcloud-authorization: q7uX9eIAWQ0FegrrskkvTOPXiAo31wESTJ6ah5FRyE0=” -X GET https://vcd/api/admin/extension/vimServer/337a4193-de37-43c0-90ab-08d082766c96

HTTP/1.1 200 OK
Date: Wed, 08 Feb 2012 23:29:14 GMT
Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml;version=1.5
Date: Wed, 08 Feb 2012 23:29:14 GMT
Content-Length: 3212

……..
    <vmext:Username>root</vmext:Username>
    <vmext:Url>https://10.20.183.48:443</vmext:Url>
    <vmext:IsEnabled>true</vmext:IsEnabled>
    <vmext:IsConnected>true</vmext:IsConnected>
    <vmext:ShieldManagerHost>10.20.183.95</vmext:ShieldManagerHost>
    <vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName>
    <vmext:Uuid>9B6C7A60-C60F-4C1D-A607-0A0CFA2C2D5A</vmext:Uuid>
……..

The results will provide details about the vCenter Server and vShield Manager. You will see two properties of interest as highlighted above: Uuid and Url. This is the instanceUUID and URL of the vCenter Server that can then be used inconjunction with the VM’s MoRef ID to map a VM in vCloud Director back to vSphere vCenter Server.

To come full circle, let’s take a look at what the vSphere environment now looks like after we had imported the two VMs earlier.

As you can see, our VM display name has slightly changed in vSphere. The reason for this is vCloud Director automatically appends the unique UUID that is generated to the VM name as a way to uniquely display the objects. You can easily generate the VM href property for vCloud Director by just looking at the UUID in the parenthesis (e.g. https://vcd/…./vm-UUID)

To complete the correlation, we will perform the same vSphere query as we did earlier to confirm the vCenter Server instanceUUID and VM’s MoRef that we found in our vCloud Director environment.

Here is the Perl script running against the westcoast-vcenter:
$ ./vmMoRefFinder.pl –server westcoast-vcenter –username root –name “MyVM1 (51201e8b-f910-40ab-b2b1-e5365a72f353)”

Name: MyVM1 (51201e8b-f910-40ab-b2b1-e5365a72f353)
VM MoRef: vm-14
VM InstanceUUID: 501b8bde-95da-472a-4d2d-9d97ea394bbc
vCenter Name: westcoast-vcenter
vCenter InstanceUUID: 9B6C7A60-C60F-4C1D-A607-0A0CFA2C2D5A

Here is the Perl script running against the westcoast-vcenter:
$ ./vmMoRefFinder.pl –server eastcoast-vcenter –username root –name “MyVM2 (ab59412f-b6c8-424d-bc0e-1414e1341084)”

Name: MyVM2 (ab59412f-b6c8-424d-bc0e-1414e1341084)
VM MoRef: vm-14
VM InstanceUUID: 502fb1ca-e9b8-82ae-3f9f-4a3ba85f081d
vCenter Name: eastcoast-vcenter
vCenter InstanceUUID: 63D30391-44E2-447E-A709-9DD1241C3DCC

Here is the PowerCLI script running when connected to both vCenter Servers:

Name                     : MyVM1
VM MoRef             : vm-14
VM InstanceUUID      : 501b8bde-95da-472a-4d2d-9d97ea394bbc
vCenter Name         : westcoast-vcenter
vCenter InstanceUUID : 9B6C7A60-C60F-4C1D-A607-0A0CFA2C2D5A

Name                     : MyVM2
VM MoRef             : vm-14
VM InstanceUUID      : 502fb1ca-e9b8-82ae-3f9f-4a3ba85f081d
vCenter Name         : eastcoast-vcenter
vCenter InstanceUUID : 63D30391-44E2-447E-A709-9DD1241C3DCC

Hopefully this example provided concrete details on how to uniquely identify a VM in a vSphere, vCloud or combination of the two environments. Though we used the vSphere SDK for Perl, PowerCLI 5.0.1 and the vCloud REST API in the examples above, this information can be obtained using any of our vSphere SDKs and vCloud SDKs.

Get notification of new blog postings and more by following lamw on Twitter:  @lamw

About the Author

William Lam

William Lam works as a Staff Engineer in VMware R&D and focuses Automation, Integration and Operations. William also runs a personal blog at www.virtuallyghetto.com. Previous to VMware, he was a Systems Engineer managing large vSphere installations and UNIX/Linux systems.