×
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')
 
 

 

This documentation supports the 11.3 version of BMC Discovery.

To view an earlier version of the product, select the version from the Product version menu.
BMC Discovery 11.3 ... Developing The Pattern Language TPL VMware ESX and ESXi host discovery using custom patterns

VMware ESX and ESXi discovery using custom patterns and integration points

You can develop your custom patterns to discover information about the VMware ESX and ESXi hosts from the VMware vSphere API.

BMC recommend that you use the TPL vSphere functions rather than the patterns and integration points (vCenter/vSphere DIP definition blocks) described in this topic. 

The vCenter/vSphere DIP definition blocks will be deprecated in a future release and will be removed in a later release.

This page contains information about the following:

  • Conditions required for successful discovery of the VMware ESX and ESXi hosts.
  • Queries used by the patterns to retrieve information about the VMware ESX and ESXi hosts.

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.

The following topics are covered in this section:

Conditions for successful VMware ESX and ESXi hosts discovery

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 Configuring vCenter credentials.

    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.

  • While developing your custom patterns, ensure the following:

    • For VMware vCenter, in the definition block, type must be set to vcenter_discovery and group must be set to "vCenter".

      type := vcenter_discovery;
group := "vCenter";

    • For VMware vSphere, in the definition block, type must be set to vsphere_discovery and group must be set to "vSphere".

      type := vsphere_discovery;
group := "vSphere";

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

    Currently, complex MOR attributes are not retrieved by BMC Discovery.

  • BMC Discovery records the vCenter query error and query result in tw_svc_vsphere.log.
    For example, if you specify HostStorageSystem in the findObject query, the error in vmware sdk will be recorded in tw_svc_vsphere.log:

    Provider.threadPool1: 2013-08-29 20:31:26,510: 
com.tideway.integrations.vsphere.ProviderSession: INFO: Executing DIP query:
queryState:{object_type=HostStorageSystem, parameters=[], 
            properties=[storageDeviceInfo.multipathInfo.lun.id], 
            vcenter_only=true, query=[findObjects]}
queryParams:{}
state:{port=443, username=vmreadonly, vcenter_ip=137.72.94.9, 
       credential_id=dc70aa30f2f269288532ac16220b0b11, 
       endpoint=137.72.94.9, timeout=60000}
Provider.threadPool1: 2013-08-29 20:31:26,662: 
com.tideway.integrations.vsphere.Connection: ERROR: 137.72.94.9: 
Failed to get View: com.vmware.vim25.InvalidArgument

VMware ESX and ESXi hosts discovery queries

In BMC Discovery versions earlier than 9.0, the following queries are used by the patterns for VMware ESX and ESXi hosts discovery:

In BMC Discovery 9.0 and later versions, in addition to the above queries, the following queries have been added:

findObjects

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:

Following is an example of using findObjects to get name and hardware.systemInfo.uuid of HostSystem MOR:

// You must define the function
definitions vCenter 1.0
  """DIP queries for getting HostSystem information"""

  type := vcenter_discovery;
  group := "vCenter";

   define getHosts
        'return all the hosts managed by vCenter'
        query := "findObjects";
        object_type := "HostSystem";
        properties := "name", "hardware.systemInfo.uuid";
        vcenter_only := true;
    end define;
end definitions;

// In the pattern body, you use the function to retrieve name and
// hardware.systemInfo.uuid properties of HostSystem MOR
        hosts := vCenter.getHosts(endpoint:=vc_host);
        if hosts then
            for host_info in hosts do
                 host_vsphereid := host_info.vsphere_id;
                 host_name := host_info.name;
                 host_uuid := host_info.hardware_systemInfo_uuid;
                 log.debug("found Host name=%host_name%, 
                            vsphere_id=%host_vsphereid%, 
                            uuid=%host_uuid%");
            end for;
        end if;

vcenter_only flag

The vcenter_only flag in the above example means that the call is intended to talk only to VMware vCenter instances and will fail if directed at a VMware ESXi host. This is required because 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). For most queries, it must be false. Otherwise, the calls will fail if an ESX host is called directly.

You can see the result of the findObjects query in the tw_vsphere_log. Following is the result of the findObjects query from the above example:

Provider.threadPool1: 2013-09-27 21:13:55,138: 
com.tideway.integrations.vsphere.Connection: 
INFO: Create authenticated connection to https://137.72.94.9/sdk/vimService
Provider.threadPool1: 2013-09-27 21:13:56,790: 
com.tideway.integrations.vsphere.ProviderSession: 
INFO: Executing DIP query:
queryState:{object_type=HostSystem, parameters=[], 
            properties=[name, hardware.systemInfo.uuid], 
            vcenter_only=true, query=[findObjects]}
queryParams:{}
state:{port=443, username=vmreadonly, vcenter_ip=137.72.94.9, 
       credential_id=dc70aa30f2f269288532ac16220b0b11, endpoint=137.72.94.9, 
       timeout=60000}
Provider.threadPool1: 2013-09-27 21:13:58,817: 
com.tideway.integrations.vsphere.ProviderSession: 
INFO: returning ([-- 1: vSphereIntegrationResult
  hardware_systemInfo_uuid : 44454c4c-5900-104c-8051-c7c04f333253
                  name : pun-esx-rds36.bmc.com
            vsphere_id : host-1867
          vsphere_type : HostSystem
.....

traverseObjects

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:

  • query: traverseObjects
  • from_type: The initial MOR object type.
  • object_type: The Object type to traverse to.
  • properties: All the properties to be retrieved must be of simple type.
  • traversal: The traversal path
  • parameters: The vsphere_id of the initial MOR.

Following is an example of retrieving Datastore objects from HostSystem objects:

definitions vCenterDef 2.0
    """DIP queries for getting storage information"""

    type := vcenter_discovery;
    group := "vCenter";

    define getHosts
        'return all the hosts managed by vCenter'
        query := "findObjects";
        object_type := "HostSystem";
        properties := "name";
        vcenter_only := true;
    end define;

    define getStorageInHost
        'return the datastore in a given host.  
          Pass in vsphere_id of the host as from_id'
        query := "traverseObjects";
        from_type := "HostSystem";
        object_type := "Datastore";
        traversal := "datastore";
        properties := "name";
        parameters := from_id;
        vcenter_only := true;
    end define;

end definitions;

pattern vCenterTest 1.0
    triggers
        on si := SoftwareInstance created, confirmed where 
			type = 'VMware VirtualCenter Server' or 
 			type = 'VMware vCenter Server';
    end triggers;

    body

    host := model.host(si);
    log.debug("VCTEST Enter getHostStorageSystem");

    hosts := vCenterDef.getHosts(endpoint:=host);
    if hosts then
        for host_info in hosts do
            host_id := host_info.vsphere_id;
            host_name := host_info.name;
            log.debug("VCTEST get Host_ID %host_id% name %host_name%");
            storages := vCenterDef.getStorageInHost(endpoint:=host, from_id:=host_id);
            if storages then
                for storage_info in storages do
                    storage_id := storage_info.vsphere_id;
                    storage_name := storage_info.name;
                    log.debug("VCTEST get datastore id  %storage_id% datastore_name %storage_name%");
                end for;
            end if;
        end for;
     end if;
    end body;
end pattern;

getPropertyTable

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:

  • query: "getPropertyTable"
  • parameters: mor, type, property, and columns
    • mor: The MOR id (vsphere_id)
    • type: The MOR object type
    • property: The parent property path of MOR column
    • columns: The property of MOR (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.)

Following is an example of retrieving multipathing or LUN data properties from a storage device:

definitions vCenterDef 1.0
    """DIP queries for getting LUN information"""

    type := vcenter_discovery;
    group := "vCenter";

    define getHosts
        'return all the hosts managed by vCenter'
        query := "findObjects";
        object_type := "HostSystem";
        properties := "name";
        vcenter_only := true;
    end define;

    define getDiskInfo
        'return disk information'
        query := "getPropertyTable";
        parameters := mor, type, property, columns;
    end define;

end definitions;

   // In the body of the pattern, you define 
   // the parameters to be retrieved by this query
   // First, Let's get the HostSystems managed by the vCenter.
    hosts := vCenterDef.getHosts(endpoint:=host);
    if hosts then
        for host_info in hosts do
            host_id := host_info.vsphere_id;
            host_name := host_info.name;

            // Example to get scsiLun (serial number and device name) for HostSystem
            disks := vCenterDef.getDiskInfo(endpoint := host,
                     mor := host_id,
                     type := "HostSystem",
                     property := "config.storageDevice.scsiLun",
                     columns := ["serialNumber", "deviceName"]
                 );
            log.debug("VCTEST get scsiLun for %host_id% name %host_name%");
            if disks then
               for disk_info in disks do
                   log.debug("VCTEST get scsiLun serialnumber %disk_info.serialNumber%");
                   log.debug("VCTEST get scsiLun deviceName %disk_info.deviceName%");
               end for;
            end if;

           // Example to get multipathing / LUN data properties from a storage device
            disks := vCenterDef.getDiskInfo(endpoint := host,
                     mor := host_id,
                     type := "HostSystem",
                     property := "config.storageDevice.multipathInfo.lun",
                     columns := ["key"]
                 );
            log.debug("VCTEST get multipathInfo.lun %host_id% name %host_name%");
            if disks then
               for disk_info in disks do
                   log.debug("VCTEST get multipathInfo.lun key %disk_info.key%");
                   // For each lun, get the path name
                   luns := vCenterDef.getDiskInfo(endpoint := host,
                     mor := host_id,
                     type := "HostSystem",
                     property := "config.storageDevice.multipathInfo.lun[\"%disk_info.key%\"].path",
                     columns := ["name"]
                    );
                    log.debug("VCTEST get multipathInfo.lun.path %host_id% name %host_name%");
                    if luns then
                        for lun_info in luns do
                            log.debug("VCTEST get multipathInfo.lun.path %lun_info.name%");
                        end for;
                    end if;
               end for;
            end if;
        end for;
     end if;

getProperties

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

  • query: = "getProperties";
  • parameters: = mor, type, attributes;

Following is an example of retrieving scsiLun data properties from a storage device:

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.

.....
    define getPropertyInfo
        'retrieve properties from a given MOR'
        query := "getProperties";
        parameters := mor, type, attributes;
    end define;

    define getPropTable
        'retrieve a table of values from a given MOR properties'
        query := "getPropertyTable";
        parameters := mor, type, property, columns;
    end define;
    .....
    hosts := vCenterDef.getHosts(endpoint:=host);
    if hosts then
        for host_info in hosts do
            host_id := host_info.vsphere_id;
            host_name := host_info.name;

            disks := vCenterDef.getPropTable(endpoint := host,
                     mor := host_id,
                     type := "HostSystem",
                     property := "config.storageDevice.scsiLun",
                     columns := ["key"]
                 );
            log.debug("VCTEST get scsiLun %host_id% name %host_name%");
            if disks then
               for disk_info in disks do
                   log.debug("VCTEST get scsiLun key %disk_info.key%");
                   scsiLuns := vCenterDef.getPropertyInfo(endpoint := host,
                     mor := host_id,
                     type := "HostSystem",
                     attributes := ["config.storageDevice.scsiLun[\"%disk_info.key%\"].deviceName", "config.storageDevice.scsiLun[\"%disk_info.key%\"].capabilities.updateDisplayNameSupported"]
                    );
                    if scsiLuns then
                       for scsiLun in scsiLuns do
                         vsphere_id := scsiLun["vsphere_id"];
                         log.debug("VCTEST get scsiLun vsphereid %vsphere_id%");
                         keyDeviceName := "config_storageDevice_scsiLun[\"%disk_info.key%\"]_deviceName";
                         attrName := text.replace(keyDeviceName, '.', '_');
                         devName := scsiLun["%attrName%"];
                         log.debug("VCTEST get scsiLun devName %devName%");
                         keyCapName := "config_storageDevice_scsiLun[\"%disk_info.key%\"]_capabilities_updateDisplayNameSupported";
                         attrName := text.replace(keyCapName, '.', '_');
                         capName := scsiLun["%attrName%"];
                         log.debug("VCTEST get scsiLun capName %capName%");
                       end for;
                    end if;
               end for;
            end if;
         end for;
     end if;

You can see the result of the getProperties query in the tw_vsphere_log. Following is an example of the result of the getProperties query in the example:

Provider.threadPool1: 2013-09-27 21:14:01,736: 
com.tideway.integrations.vsphere.ProviderSession: 
INFO: Executing DIP query:
queryState:{query=[getProperties], parameters=[mor, type, attributes], properties=[]}
queryParams:{type=HostSystem, mor=host-1867, 
             attributes=[config.storageDevice.scsiLun["key-vim.host.ScsiLun-0005000000766d686261333a303a30"].deviceName, 
config.storageDevice.scsiLun["key-vim.host.ScsiLun-0005000000766d686261333a303a30"].capabilities.updateDisplayNameSupported]}
state:{port=443, username=vmreadonly, vcenter_ip=137.72.94.9, 
       credential_id=dc70aa30f2f269288532ac16220b0b11, endpoint=137.72.94.9, timeout=60000}
Provider.threadPool1: 2013-09-27 21:14:01,873: 
com.tideway.integrations.vsphere.ProviderSession: 
INFO: returning ([-- 1: vSphereIntegrationResult
  config_storageDevice_scsiLun["key-vim_host_ScsiLun-0005000000766d686261333a303a30"]_capabilities_updateDisplayNameSupported : true
  config_storageDevice_scsiLun["key-vim_host_ScsiLun-0005000000766d686261333a303a30"_deviceName : /vmfs/devices/genscsi/mpx.vmhba3:C0:T0:L0
            vsphere_id : host-1867
          vsphere_type : HostSystem

], {})
Was this page helpful? Yes No Submitting... Thank you
Last modified by Duncan Tweed on Oct 11, 2019

Comments

VMware ESX and ESXi discovery using discovery.vSphere functions
Displaying custom attributes
© Copyright 2004 - 2021 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2021 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.