(Quick Reference)

vCenter Plugin

The vCenter plugin polls a VMware® vCenter™ Server for information on the hypervisors and virtual machines it manages. The information it gathers for each system includes state, power, number of processors, total memory, available memory, and CPU load. The plugin stores this information in the MWS database for later retrieval during cluster queries.

To use the vCenter plugin, Moab Workload Manager (MWM) must be properly configured as described in the Configuring MWM section.

Creating a vCenter Plugin

To create a vCenter plugin, see Creating a Plugin. During plugin creation, refer to the Configuration section.

Configuration

Poll Interval

The Poll Interval must be at least 20 seconds.

Configuration Parameters

Parameter	Configuration Key	Required	Type	Default	Description
URL	url	Yes	String	-	The URL of the vCenter server. Example: `https://vcenter1`
Username	username	Yes	String	-	The username for accessing the vCenter server.
Password	password	Yes	String	-	The password for accessing the vCenter server.
Ignored Hypervisors	ignoredHypervisors	No	String	-	A comma-separated list of hypervisors not to report.
Ignored Virtual Machines	ignoredVirtualMachines	No	String	-	A comma-separated list of virtual machines not to report.
Ignore SSL Certificate Errors	ignoreCertificateErrors	No	Boolean	`false`	If true, ignore SSL certificate errors.
Ignore API Version	ignoreApiVersion	No	Boolean	`false`	If true, ignore the API version of the vCenter server.
Ignore State	ignoreState	No	Boolean	`false`	If true, do not report state.
Hypervisor Image Name	hypervisorImageName	No	String	-	If set, the reports generated will use this image name for all reported hypervisors. See Hypervisor Image Name section below.
Moab Partition	partition	No	String	`vcenter-<pluginid>`	The partition to use when reporting resources. Must be unique.

Configuration Notes

The names of these configuration keys are case-sensitive.
Make sure the url parameter refers to a vCenter server, not the hypervisor on which it is running (if any).
The ignoredHypervisors and ignoredVirtualMachines parameters prevent the listed systems from being reported to MWM during cluster queries. The values of these parameters are case-insensitive.
The plugin attempts to ignore vCenter servers. Nevertheless, it is good practice to list your vCenter server in your ignoredVirtualMachines list.
In general, do not set ignoreCertificateErrors to true in a production environment. Its effect is to ignore all SSL certificate problems, including self-signed certificates, expired certificates, and hostname mismatches (e.g., server X presents a certificate that was issued to server Y).

For more information on vCenter and SSL certificates, see this VMware Knowledge Base article.

By default, the vCenter plugin communicates only with vCenter servers running version 5.0 of the VMware vSphere Web Services API. To allow communication with servers running other versions of the API, set ignoreApiVersion to true. Doing so might produce unpredictable results.
By default, the vCenter plugin attempts to determine the state of hypervisors and virtual machines. To turn off this feature, set ignoreState to true.

Hypervisor Image Name

Moab Workload Manager will not recognize reported nodes as hypervisors unless an Image exists which matches the hypervisorImageName configuration parameter. This image must have the hypervisor field set to true, contain a valid hypervisor type (see the hypervisorType field or the extensions.xcat.hvType field), and have a list of virtualized images that it supports.

See "Managing Images for Nodes" in the Reporting State Data section for more information.

Plugin Management

For information on managing the vCenter plugin, including stopping it, starting it, and checking on its status, see the Plugin Management section of the guide.

Cluster Query Notes

This section contains information on the fields reported by the vCenter plugin during a cluster query.

`AMEMORY`

The total memory available (free) on the hypervisor or virtual machine, in MB.

`CMEMORY`

The total memory configured on the hypervisor or virtual machine, in MB.

`CONTAINERNODE`

The hypervisor on which a virtual machine is installed. This field is reported only on virtual machines.

`CPROC`

The number of configured processors on the hypervisor or virtual machine.

`CPULOAD`

A measure of the CPU load on a hypervisor or virtual machine. This number is calculated as follows:

Query the vCenter server for the three most recent "CPU used" samples (each sample spanning twenty seconds) for each CPU on this hypervisor or virtual machine.
For each CPU, calculate the average (arithmetic mean) of the three values.
Each value is the number of milliseconds that CPU was busy during the corresponding 20-second interval.
Each value is therefore between 0 and 20,000 (but see note below on sampling overlap).
Add all the averages and divide by 10,000.
The result is a Double between 0.0 and 1.0 per CPU. For example, on a system with four CPUs, the result is between 0.0 and 4.0.

Because of sampling overlap on very busy machines, the number can be higher than 1.0 per CPU.

`GMETRIC[cpuUtilization]`

A measure of the CPU utilization, as a percentage, on a hypervisor or virtual machine. This number is calculated as follows:

Query the vCenter server for the three most recent "CPU usage average" samples (each sample spanning twenty seconds) for each CPU on this hypervisor or virtual machine.
For each CPU, calculate the average (arithmetic mean) of the three values.
Each value is a percentage (multiplied by 100) representing the average usage of the CPU during the corresponding 20-second interval.
Each value is therefore between 0 and 10,000.
Calculate the average of the averages and divide by 100.
The result is a Double between 0.0 and 100.0.

`GMETRIC[vmcount]`

The number of virtual machines on this hypervisor. For virtual machines, the vmcount is always 1.

`PARTITION`

If you specify a value for the partition configuration parameter (see above), then PARTITION is reported as that value. Otherwise, PARTITION is reported as vcenter-<pluginid>. This field is reported only on hypervisors.

`POWER`

The power state of the hypervisor or virtual machine.

`STATE`

Hypervisor State

If the node is powered on and connected (responding to the vCenter server) and is not in maintenance mode, then report Up.
Else report Down.

Virtual Machine State

If the VM power is not on, then report Down.
Else if the VMware Tools package is not running on the guest OS, then report Unknown.
Else if the VMware Tools package reports that the guest OS is running, then report Up.
Else report Down.

`UPDATETIME`

The time that the hypervisor or virtual machine information was last updated, in seconds since the UNIX epoch.

Troubleshooting

The vCenter plugin logs all errors and warnings to the MWS log file, which is /opt/mws/log/mws.log by default. The stacktrace.log file, in the same directory as mws.log, can also be helpful in diagnosing problems. Also, see the Troubleshooting Installation section of the guide.

Caveats

The ignoreCertificateErrors parameter is sticky. That is, once set to true, the only way to clear it is to set it to false and then restart Tomcat.
If the name of a hypervisor or virtual machine contains at least one space, the plugin ignores that system.
After a hypervisor has been reported to Moab Workload Manager (MWM), removing it from MWM's node list is difficult. Therefore, be sure to set ignoredHypervisors before starting your vCenter plugin for the first time.
Similarly, be sure to set ignoredVirtualMachines before starting your vCenter plugin for the first time.