Introduction to the vSphere API Part 3 - Inventory Hierarchy

In Part 2 of the series, we took a look at the vSphere Object Model and how objects such as a Virtual Machine, ESXi host, Datacenter, etc. are represented in the API and how to access their properties and capabilities. In this article, we will take a look at the vSphere Inventory Hierarchy and how to go about navigating and searching through the vSphere Objects.

Overview

The vSphere API organizes its entities (Datacenter, HostSystem, VirtualMachine, etc) in an inventory hierarchy. This inventory hierarchy structure is similar for both a vCenter Server and an ESX(i) host, but for a vCenter Server, the inventory structure can be more complex. Understanding the hierarchy and the object relationships is crucial for navigating and searching through the vSphere API.

If you have connected using the vSphere Client to interact with an ESX(i) host or a vCenter Server, then you have already been exposed to the vSphere Inventory Hierarchy.

As you can see from the screenshot above, when you first login you will be presented with 4 distinct groupings:

Hosts and Clusters - This view provides you access to your ESX(i) hosts and vSphere Clusters

VMs and Templates - This view provides you access to your Virtual Machines, vApps and Virtual Machine Templates (which is just an immutable Virtual Machine)

Datastores and Datastore Clusters - This view provides you access to your Datastore and Datastore Clusters (known as StoragePod in the vSphere API)

If you want to search for a particular vSphere entity such as an ESXi host or Datastore, you would select one of these groupings and traverse its inventory tree. You could also organize the entities using the folder constructs which also allows you to have nested entities.

So how does this all relate back to the vSphere API Inventory Hierarchy? Well, these groupings actually represents the underlying inventory hierarchy. Also, a few things are abstracted when using the vSphere Client, but for the most part you are seeing how the inventory is organized and laid out. I mentioned earlier that the vSphere Inventory Hierarchy is similar for both an individual ESX(i) host as well as for a vCenter Server, which makes it possible to manage both types of system through a unified vSphere API.

vCenter Server Inventory Hierarchy:

When you first login, you will be presented with a special managed object singleton called the ServiceInstance which you can think of as the root of the inventory. From here you will find a single folder called rootFolder which can contain one or more child entities of either a Folder or Datacenter. As you traverse the rootFolder, in case you have nested folders, you will eventually end up at a Datacenter entity which then provides you access to 4 different types of folders: VM, Host, Datastore and Network. These are synonymous to the 4 groupings we saw earlier in the vSphere Client. As you can see from the diagram above, each Datacenter will have exactly one of these these top level folders and within these folders there can be various child entity types.

For example, in the HostFolder, we can have a ComputeResource (compute resources of an ESXi host) and ClusterComputeResource (aggregated compute resources to form a vSphere Cluster) which can in turn have multiple ResourcePool (set of compute resources which could be further divided) and HostSystem (individual ESXi host).

Similarly, to retrieve other types of vSphere entities such as VirtualMachine or StoragePod (Datastore Clusters) you just need to traverse down the appropriate top level folders as outline in the diagram.

ESX(i) Inventory Hierarchy:

The inventory hierarchy for a standalone ESX(i) host is pretty much a simplified single instance of the vCenter Server hierarchy. When we first login, we still have the ServiceInstance, but the rootFolder now contains only a single Datacenter (named ha-datacenter) entity, whereas before, you could have multiple or nested Folder and Datacenter entities. You still have the 4 top level folders (VM, Host, Datastore and Network), but for the HostFolder specifically will only have a single ComputeResource entity as well as a single root ResourcePool (child resource pools can still exists) and single HostSystem definition.

As you might have guessed, the biggest difference between the inventory hierarchy of a vCenter Server and standalone ESX(i) host is that for a vCenter Server, you could be managing thousands of ESX(i) hosts and tens of thousands of VirtualMachines and therefore the inventory will be more complex. Whereas with a standalone ESX(i) host, it is just single system and hence inventory is pretty straight forward.

Hopefully this article provides you with a better understanding of how the vSphere entities are organized within the inventory hierarchy and it helps you visualize where a particular entity resides within the vSphere API. Combining the understanding of the vSphere Object Model along with the Inventory Hierarchy, you will now be able to manage and configure any vSphere object as you would using the vSphere Client.

In the next two articles, we will take a look at some the free tools that can help you better understand and explore the vSphere API.

About 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.