A QUICK REFERENCE OF VSPHERE IDS

Posted on Aug 9, 2016 Updated on Sep 20, 2016

Here is a list of a number of the different IDs used in the virtual infrastructure and how they are used:

1. VC Instance UUID(aka serverGuid): This is a GUID that identifies the vCenter server.  This is accessible from the AboutInfo property in the VIM API.  The property name is AboutInfo#instanceUuid.  It’s set at install time and is persisted so the value is durable for a given VC instance.

To access this via PowerCLI you can use the following:

2. The ESX Host UUIDis read by the ESX host from the System Management BIOS (SMBIOS). This UUID is not generated by VMware, it is unique to the hardware and is set in the BIOS by the vendor.

To access this via PowerCLI you can use the following:

3. VC-VM Instance UUID: This is the vc.uuid property in the VM vmx configuration file and also the instanceUuid property on the VmConfigInfo for a VirtualMachine in the VIM API.  This UUID is used by vCenter to uniquely identify VMs that it is managed.  vCenter assigns this UUID to the VM after it is created.  There are different workflows where a VM may not have a UUID initially or may have a duplicate.  vCenter actively looks over the VM inventory and will automatically patch the VM instance UUID if it sees a duplicate.

The scope of this uniqueness scan is a vCenter instance.  If there are duplicate VC-VM Instance UUIDs, they will not be detected as duplicates unless the VMs are managed by the same vCenter instance.  This value can be changed through the API.

To access this via PowerCLI you can use the following:

4. VM SMBIOS UUID: This is the uuid.bios property in the VM vmx configuration file.  In the VIM API, this is the uuid property on the VmConfigInfo for a VirtualMachine managed object.  This UUID is visible to the guest OS as the SMBIOS UUID.  VMware generally try to avoid changing this UUID since it is often used by applications that manage the guest OS instances.  When the VM is migrated this UUID is maintained.

vCenter does a best effort to try to make sure these UUIDs are unique in an environment.  For operations like clone and deploy that create a new VM, a new UUID is provided to the VM by clearing the uuid.bios from the VM’s vmx file.  If the VM is copied without vCenter’s knowledge, 3rd party tools are advised to do the same thing as vCenter.  A new uuid.bios is generated the next time the VM is powered on.  This UUID is generated by the ESXi server so vCenter does not have to be in the control flow for the uuid.bios to be generated.

To access this via PowerCLI you can use the following:

5. VM Location ID: This identifier is stored in the VM configuration file as the variable uuid.location.  In the VIM API, the name is locationId also on the VmConfigInfo of the VirtualMachine.  This is one other detail that might be relevant to a 3rd party solution that might be moving the VM without vCenter’s knowledge.  This property is used in conjunction with the VM SMBIOS UUID.  This property is a hash of the VM’s configuration file and some UUID of the ESXi. The purpose of this UUID is to detect out-of-band migrations and copies of the VM.  If vSphere (or Workstation/Fusion) detect that the locationId is no longer valid, it will pop up dialog/question/error asking the user why the locationId is no longer valid.  The user is prompted to answer whether the VM was moved or copied.  The purpose is so that vSphere can determine whether it should keep the existing the SMBIOS UUID or generate a new one.

Recall, I mentioned that vCenter is doing a best effort to ensure the SMBIOS UUID is unique.  But when it detects a potential conflict, vCenter will not automatically patch the UUID since this could break 3rd party and VMware products that rely on the guest visible UUID to correlate the VM with other management entities in the environment.

The way 3rd party solutions can best interoperate with vCenter and it’s attempt to preserve a unique SMBIOS UUID is to be aware of these semantics.  If a 3rd party solution or program is moving the VM, it should clear out the uuid.location (ie. ConfigInfo.locationId) property.  On next power on, a new uuid.location will be generated, binding the VM to ESXi host and the file path where it is running.

Despite this however, there is a theoretical and real possibility that there could be duplicate SMBIOS UUIDs.  Because vCenter is deferring to what the user of the system what the the SMBIOS UUID should be, it will not change the UUID automatically if it detects conflicts.  If there SMBIOS UUIDs that are duplicated, it will not fix them.

To access this via PowerCLI you can use the following:

6. VM MoRef: The VM MoRef is a short key used by a vCenter instance to identify the VM.  This is the primary identifier used by the VIM API to refer to the VM.  The other identifiers can generally be used to find the VM, but the VM MoRef is the one that must ultimately be used to get data and issue operations to modify the VM.

In general, the MoRef is the important identifier because that’s what is used in the VC database to associate a VM to its stats, events, and configuration.

In environments where multiple vCenters are used, the MoRef will not necessarily be unique.  As a result, another identifier needs to paired with the VM MoRef or used instead.  In general, vSphere uses a combination of the vCenter instance UUID (ie. the serverGuid) with the MoRef to identify the VM for cross-vCenter scenarios like Linked Mode.

To access this via PowerCLI you can use the following: