vSphere Inventory Structure Deep Dive

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

This entry was posted in vSphere API and tagged , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.


  1. Posted April 29, 2011 at 7:43 pm | Permalink

    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. Posted May 1, 2011 at 7:11 pm | Permalink

    Hi Rosanna,

    Great questions! Here is a new post on this:


  3. Posted August 20, 2014 at 1:23 pm | Permalink

    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. Posted August 21, 2014 at 12:24 pm | Permalink

    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.


3 Trackbacks

  • […] for ServiceInstance. The safer way is to get them from the content property of ServiceInstance or retrieving from inventory tree in your application. The Managed Object Browser is an excellent tool to find out the type and value […]

  • […] vSphere Inventory Structure Deep Dive by Steve Jin […]

  • […] The vSphere MOB (Managed Object Browser) is not a well known tool and unless you are a developer, you probably do not know of its existence. The simplest way to describe the vSphere MOB is that it is a debugging tool to graphical visualize all entities within the vSphere API through a web browser. It is often used to better understand the vSphere API/inventory and aide in developing your own vSphere application or script. For a detailed deep dive of the vSphere inventory, check out Steve Jin's post here. […]

Post a Comment

Your email is never published nor shared. Required fields are marked *


You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__ doublecloud.org.

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.