VMware ESX and ESXi discovery using discovery.vSphere functions

You can develop custom patterns to discover information about the VMware ESX and ESXi hosts from the VMware vSphere API using the discovery.vSphere* functions.

Conditions for successful VMware ESX and ESXi hosts discovery

To learn how to upload patterns to the appliance, activate or deactivate patterns on the appliance, and delete patterns which are no longer required, see Knowledge-management.

For successful VMware ESX and ESXi hosts discovery, you must ensure the following conditions:

Define the VMware vCenter and vSphere discovery credentials. For more information, see Adding-credentials.
Note
BMC Discovery uses the vSphere API to communicate directly with VMware ESX and ESXi hosts where no VMware vCenter credentials are available. Running a large number of VMware vSphere or vCenter queries can have performance impact on both the VMware vCenter server and the corresponding VMware vSphere hosts. To avoid this, the API must be used sparingly.
By default, BMC Discovery retrieves the vsphere_id and vsphere_type attributes for the requested ManagedObjectReference (MOR). To refer to an MOR property in your pattern, you must replace the periods (.) with underscores (_).
For example, in the pattern, you can refer to the host_system.hardware.systemInfo.uuid attribute as host_system.hardware_systemInfo_uuid.
Note
Currently, complex MOR attributes are not retrieved by BMC Discovery.
The vcenter_only flag previously used is no longer required as you can test whether the target is a VMware vCenter instance or a VMware ESXi host and retrive properties accordingly. For example, both the ESXi hosts and vCenter use the same API, but some calls only make sense when talking to vCenter (for example, listing all the managed hosts).

discovery.vSphereFindObjects

discovery.vSphereFindObjects(target, "object_type", ["property", "property", ...])

It queries to search from the root folder the instances of an object type and returns the requested properties for each object found. The required parameters are:

target - the ESX/ESXi node if discovering using vSphere or via vCenter, or the vCenter node if discovering information about the vCenter server.
object_type - a vSphere managed object name specified in the VMware documentation. For example, Folder, Datacenter, ComputeResource, ResourcePool, or HostSystem.
properties - list of properties to retrieve. Each must be simple type (string, int, boolean, and so on), no objects, or lists.

This code example shows retrieving the name and hardware.systemInfo.uuid of HostSystem MOR:

hosts := discovery.vSphereFindObjects(vc_host, "HostSystem", ["name", "hardware.systemInfo.uuid"]);

Parameter name	Description
target	the ESX/ESXi node if discovering using vSphere or via vCenter, or the vCenter node if discovering information about the vCenter server.
object_type	a vSphere managed object name specified in the VMware documentation. For example, Folder, Datacenter, ComputeResource, ResourcePool, or HostSystem.
properties	list of properties to retrieve. Each must be simple type (string, int, boolean, and so on), no objects, or lists.

discovery.vSphereTraverseToObjects

discovery.vSphereTraverseToObjects(target, "from_type", "object_type", ["property", "property", ...], traversal, parameters)

It queries to traverse from the initial object to instances of an object type and get properties on those objects. You will need to know the vsphere_id (MOR ID) from Managed Object Type that you want to start traversing with. It returns the requested properties for each object found. The required parameters are:

target - the ESX/ESXi node if discovering using vSphere or via vCenter, or the vCenter node if discovering information about the vCenter server.
start_vsphere_type - the starting point, given as a vSphere managed object name specified in the VMware documentation. For example, Folder, Datacenter, ComputeResource, ResourcePool, or HostSystem.
start_vsphere_id - MOR (managed object reference) where to start from. The type and id together uniquely identify a managed object in the system we are communicating with.
traversal - this is a property name which tells how to get from the start_vsphere_type/start_vsphere_id to end_vsphere_type. It is a simple string.
end_vsphere_type - the managed object type at the end of the traversal. All managed objects of different type are dropped.
properties - List of properties to retrieve. Each must be simple type (string, int, boolean, and so on), no objects, or lists.

This code example shows retrieving Datastore objects from HostSystem objects:

discovery.vSphereTraverseToObjects(host, "HostSystem", storage_info.storage_id, "datastore", "Datastore", ["name"])

discovery.vSphereGetProperties

discovery.vSphereGetProperties(target, vsphere_type, vsphere_id, ["property", "property", ...])

It queries to retrieve properties from a given MOR and returns the requested properties for each object found.The required parameters are:

target - the ESX/ESXi node if discovering using vSphere or via vCenter, or the vCenter node if discovering information about the vCenter server.
vsphere_type - a vSphere managed object name specified in the VMware documentation. For example, Folder, Datacenter, ComputeResource, ResourcePool, or HostSystem.
vsphere_id - MOR (managed object reference). The type and id together uniquely identify a managed object in the system we are communicating with.
properties - List of properties to retrieve. Each must be simple type (string, int, boolean, and so on), no objects, or lists.

This code example shows retrieving scsiLun data properties from a storage device:

discovery.vSphereGetProperties(host, "HostSystem", host_id, ["config.storageDevice.scsiLun[\"%disk_info.key%\"].deviceName", "config.storageDevice.scsiLun[\"%disk_info.key%\"].capabilities.updateDisplayNameSupported"])

Note

As scsiLun is an array, you must retrieve the scsiLun key first and then the attribute for each key. If the attribute does not exist, then BMC Discovery may throw an ECA Error in tw_svc_reasoning.log.

discovery.vSphereGetPropertyTable

discovery.vSphereGetPropertyTable(target, vsphere_type, vsphere_id, table, [column, column, ...] )

It queries to retrieve a table of values from a given MOR and is intended to be used to retrieve nested properties from lists and arrays. The query returns multiple NodeState objects, one for each DataObject in the list or array. The required parameters are:

target - the ESX/ESXi node if discovering using vSphere or via vCenter, or the vCenter node if discovering information about the vCenter server.
vsphere_type - a vSphere managed object name specified in the VMware documentation. For example, Folder, Datacenter, ComputeResource, ResourcePool, or HostSystem.
vsphere_id - MOR (managed object reference). The type and id together uniquely identify a managed object in the system we are communicating with.
table - name of table property on managed object.
column - list of properties to retrieve from each entry in the table. It must not be the composite column name. For example, key or deviceName is a valid column. However, capacity.block is not a valid column.

This code example shows retrieving multipathing or LUN data properties from a storage device:

discovery.vSphereGetPropertyTable(host, "HostSystem", host_id, "config.storageDevice.scsiLun", ["serialNumber", "deviceName"])