Home > vSphere API > vSphere Inventory Structure Deep Dive

vSphere Inventory Structure Deep Dive

March 29th, 2010 Leave a comment Go to comments

This blog digs into the vSphere inventory structure, and changes in vSphere 4 from VI. It explains the difference between ESX and vCenter inventory tree, why the inventory path you see from vSphere Client doesn’t work with API. Much of the content is adapted from my book VMware VI and vSphere SDK by Prentice Hall.

Inventory vs. Inheritance hierarchy

Lost VMs or Containers? Too Many Consoles? Too Slow GUI? Time to learn how to "Google" and manage your VMware and clouds in a fast and secure HTML5 App.

My previous blog introduced the object model of the vSphere API. The UML diagram there shows how different managed object types are structured in the inheritance hierarchy.

The inventory hierarchy is quite different. It shows how different managed object instances are associated. With this understood, you can easily navigate among different managed objects in inventory tree of both ESX and vCenter. It’s critical for programming vSphere API because navigating the inventory is the primary way to get hold of managed objects.

Please note the difference here: the inheritance hierarchy is about the relationship of types, and inventory hierarchy is about the relationship of instances.

Inventory Structure in 2.5

The VI inventory tree consists of ManagedEntity objects. These object instances are linked together with parent-child relationship. The designers of vSphere API have done a great job to unify the structures of both ESX and VC. Without this consistency, the unified API to manage both ESX and vCenter is impossible.

The following diagram illustrates the hierarchy of the inventory tree for both ESX and VC server starting from a ServiceInstance object.

From the ServiceInstance object, you can get hold of the rootFolder which is a Folder managed object. Note that in VI SDK, you first get the ServiceContent object and then the rootFolder while you can get hold of the rootFolder directly in vSphere(VI) Java API.

The Folder object is a container type. What it can have as its child entity depends on its property childType, which is an array of strings. This property is set by the system and you cannot change it.

As you can tell from the figure, the rootFolder can have two different types of children, Folder and Datacenter. The real values stores are actually vim.Folder and vim.Datacenter. To save space, vim is ignored in the diagram.

Because root folder can have Folder objects as its children, you could have recursion in which Folder objects are nested to unlimited number of levels (not shown explicitly in the diagram). The nested structure is not only possible, but necessary in a big computing infrastructure where you want to organize the computing resources into a meaningful structure for easy management. For example, you could have folders for different locations, for different departments, for different categories, or a mixture of these.

From the root folder, there could be many Datacenter and/or Folder objects as its children. No matter how the structure looks like, the Folder/Datacenter recursion has to end up with a Datacenter object, which is the basic unit of the whole computing structure.

A Datacenter managed object doesn’t necessarily reflect a typical data center in a physical world which normally refers to a facility where a lot of servers are hosted. In vSphere, the Datacenter is more conceptual than physical. It is where the physical server and virtual machines are aggregated into a single management unit.

The Datacenter has two Folder objects attached to it. One contains VirtualMachine objects or nested Folder objects. For any sub Folder objects created underneath the top vmFolder, it has the same restriction on the childType, meaning you can only find either Folder or VirtualMachine objects there.

The other Folder object contains the ComputeResource object or Folder objects. The folder name hostFolder can cause confusion because you would expect it contains HostSystem directly based its name. Any sub Folder object created there can only have Folder or ComputerResource objects as its children. Although only ComputeResource is listed as the type, its sub type ClusterComputeResource can also show up anywhere ComputeResource does. So you could find a mixture of ComputerResource, ClusterComputerResource and Folder objects under a hostFolder.

ComputeResource is an aggregation of many computing resources from HostSystem, Datastore, Network, to ResourcePool. Because Datastore and Network are not managed entities, they are just omitted in the diagram. It’s easy to understand the HostSystem as part of the ComputeResource. How about ResourcePool?

The ResourcePool represents a set of physical resources: either a single host machine or aggregation from multiple hosts. These resources can be further divided into smaller chunks in different ways like ratio, absolute value etc. For each ComputeResource, there is only one root ResourcePool and the root has a recursive structure of ResourcePool objects underneath it.

Difference of ESX Inventory and vCenter Inventory

Now that the overall structure is clear, let’s look at the difference of the inventory of ESX and VC server. The difference mainly comes from quantities that different managed entities can show up. Overall, ESX server inventory tree is much simplified than that of VC server which can manage hundreds of ESX servers at a time.

In an ESX server inventory tree, there is always one Datacenter and one HostSystem, and the structure is pretty fixed. The following shows the hierarchy of inventory in an ESX server.

The inventory of VC server is very much similar in structure, but different in quantities and possibly nesting structures. One obvious difference is that there is one and only one HostSystem in an ESX inventory tree, and zero to many HostSystem instances in the VC server inventory tree.

What’s New in vSphere 4?

The inventory structure in vSphere 4 is compatible with 2.5. The navigations from one managed object instance to others are the same. So your old code should work as it is.

There are several additions/changes in vSphere 4 that you need to pay attention:

  1. Network, Datastore becomes a subtypes of ManagedEntity instead of ExtensibleManagedObject as in 2.5, meaning they are part of the inventory tree.
  2. DistributedVirtualSwitch, extended by VmwareDistributedVirtualSwitch, is added as a subtype of ManagedEntity. This reflects the key feature DVS that is new in vSphere 4.
  3. Network has a new subtype DistributedVirtualPortgroup, whose property config contains link to the distributed virtual switch. When you see a Network object, its concrete type could be DistributedVirtualPortgroup now. It’s very similar to the ComputeResource vs. ClusterComputeResource.
  4. ResourcePool has a new subtype VirtualApp. So the specific type of a object whose type is declared as ResourcePool could be VirtualApp.

The vSphere Java API 2.0 support the changes in vSphere. You should read this article for the compatibility tips.

Confusion About Inventory Path

Several vSphere API calls expect inventory path, for example, the SearchIndex’s findByInventoryPath() method. If you pass in something you see from a vSphere Client, it won’t work.

For the best user experience, vSphere Client hides some of the elements in the real path. For example, you don’t see an element called “vm” in a VI Client inventory tree. To find out exact inventory path, use MOB or the VIJava Browser.

The inventory path is separated by slashes “/”. For example, a path to a VM should be of the form “My Folder/My datacenter/vm/VM_name.” A leading slash or trailing slash is ignored. The root folder should NOT be included in the path. You can have space in your path like the following:

ha-datacenter/vm/SuSe Enterprise

Also, make sure all the strings in the path are names of entities, not the object IDs of the entities. For some top managed entities in the inventory tree, these two could be same.

To be notified for future posts, feel free to subscribe to this feed, and follow me at Twitter

Categories: vSphere API Tags: ,
  1. April 29th, 2011 at 19:43 | #1

    From what I’ve read about vCenter linked mode, it enables a common inventory view across multiple instances of vCenter Server.

    How does the VI Java API support linked mode? Does the VI Java API show the inventories from the linked vCenters as one? For example, if I do a search for “VirtualMachine” from the root folder after connecting to a single vCenter (which is linked to other vCenters), will I get all VMs from all the linked vCenters? If so, what about VM naming? Say a VM in vCenter A has the same name as a VM in vCenter B. Will I get two entries with the same name?

  2. May 1st, 2011 at 19:11 | #2

    Hi Rosanna,

    Great questions! Here is a new post on this:


  3. August 20th, 2014 at 13:23 | #3

    Hi Steve,

    I was wondering what the best way to programatically get the inventory path. Is this something I would need to build by looping through object parents to build the path? I’m finding that to be very expensive especially when trying to retrieve a list of several vms or hosts. Any pointers are welcome!

    thank you,

  4. August 21st, 2014 at 12:24 | #4

    For individual vms/hosts, you have to do that way. If you have multiple vms/hosts that share the same parents or grandparents …, you just need to get the path for the parent/grandparents once and share.


  1. March 30th, 2010 at 00:02 | #1
  2. May 5th, 2013 at 11:26 | #2
  3. July 10th, 2016 at 08:29 | #3