VMware

vSphere Web Services SDK 4.1 Release Notes

Last updated:   20-Jan-2011

VMware vSphere 4.1 Release date: 13 Jul 2010 vSphere Web Services SDK Build 251329

This document contains the following information:

New Features

  • vSphere Web Services SDK 4.1 supports the new features of vCenter Server and ESX/ESXi 4.1 systems. For information about additions and changes to the vSphere API, see What's New in vSphere API 4.1
  • Non-secure communication with a vSphere Client Plug-in - in vSphere 4.1, there is a new XML element defined for the vSphere Client Plug-in configuration file. The <supportNonSecureCommunication> tag specifies a non-secure HTTP connection between a vSphere Client and a plug-in Web server.

Known Issues

The vSphere Web Services SDK release 4.1 has the following known issues:

ESXi Performance metadata is available only from vCenter Server.
On an ESXi Server, the PerformanceManager defines a single performance interval that specifies rollup data collection every 5 minutes. This ESXi performance interval metadata is available from a vCenter Server in the PerformanceManager.historicalInterval list of PerfInterval objects. When you retrieve the historicalInterval property from an ESXi Server, the ESXi Server returns an empty property.
Certain PCI device properties might be represented as negative values.
The following HostPciDevice properties might be represented as negative values:

    deviceId
    subDeviceId
    vendorId
    subVendorId

A vSphere Server uses an unsigned short integer to represent PCI device and vendor identifiers. The WSDL representation of the identifier is a signed short integer. If the identifier is greater than 32767, the Server will convert it to its two's complement for the WSDL representation.

  • When you specify a PCI device ID for a virtual machine (VirtualPCIPassthroughDeviceBackingInfo.deviceId), you must use the HostPciDevice.deviceId value as retrieved and convert it to a string.
  • When you specify a PCI vendor ID for a virtual machine (VirtualPCIPassthroughDeviceBackingInfo.vendorId), you must use the retrieved HostPciDevice.vendorId value.
EventFilterSpec properties "type" and "eventTypeID" do not work - ESX Server only.
For a client that is connected to a vCenter Server, event filtering based on the event type works correctly. For client that is connected to an ESX host, event filtering using the type or eventTypeID properties does not work.
ResignatureUnresolvedVmfsVolume_Task method returns invalid reference - vCenter Server only.
For a client that connects to an ESX host, the ResignatureUnresolvedVmfsVolume_Task method returns a valid managed object reference to the resolved datastore (the HostResignatureRescanResult.result property). For a client that is connected to a vCenter Server, the method returns an invalid reference. The vCenter Server client cannot use this reference and there is no workaround for this problem.
Discrepancy for virtual machine guest heartbeat status values - vCenter Server only. For a client that connects to an ESX host, the guest heartbeat status for a virtual machine on that host is correct (VirtualMachine.guestHeartbeatStatus). A client that connects to a vCenter Server will see changing guest heartbeat status values for that same virtual machine. The vCenter Server reports incorrect status values that cycle between ManagedEntityStatus values of green and yellow or green and red. The value can change every 20 seconds. Currently, there is no workaround for this problem.
Duplicate data in performance counter database for certain counters - vCenter Server only. Client applications that connect to a vCenter Server can see duplicate performance data for some counters due to incorrect names. The vSphere statistics database contains duplicate data for the memory counters swapin and swapout. The duplicate data is identified by slightly different and incorrect names that use the wrong character case - swapIn and swapOut. You may encounter this if you use the QueryAvailablePerfMetrics method to obtain performance counter identifiers. The method will return two different identifiers for the same (duplicate) data. Each identifier is associated with a different name. You can also see duplicate data for these counters in the PerfCounterInfo array for the PerformanceManager.perfCounter property.

There are other counters that previously showed the same duplication. These have been fixed in vSphere 4.1, however if you have a client that connects to an earlier version you will see the duplication. This affects the following counters:

  • CPU - reservedCapacity (incorrect counter name is reservedcapacity)
  • Memory - reservedCapacity (incorrect counter name is reservedcapacity)
  • ManagementAgent - swapin, swapout (incorrect counter names are swapIn and swapOut)
vSphere Web Services SDK sample program file SSPI.cpp does not compile on the supported platforms (Microsoft Visual Studio 2005 and Microsoft Visual Studio 2008). The SDK sample SSPICIMClient requires the SSPI.dll file to perform pass through authentication. For information about how to fix this, see the VMware Knowledge Base article about the SSPI.cpp sample file.
HA (High Availability) event HostDasOkEvent not generated. When an HA error occurs on a host, the ESX Server generates the event HostDasErrorEvent. The vSphere API Reference indicates that the Server generates HostDasOkEvent when the HA service returns to its normal state, but the Server does not generate this event.
Virtual machine VMCI communication setting not propagated until restart. You can set the VirtualMachineVMCIDevice.allowUnrestrictedCommunication property to control VMCI socket access, but any change to the property will not take effect until the virtual machine is restarted.
WSDL incompatibility between 2.5 (and earlier) clients and vCenter Server 4.0 (and later). When vCenter Server performs a group power on, if there is more than one fault thrown per VM, the Server generates a GenericDrsFault fault. Pre-4.0 clients cannot handle this fault (the client will exit). There is no workaround for this situation. The best solution is to upgrade to vSphere client 4.0 or later.
vSphere API Reference issues:
 
You cannot remove an existing VirtualMachineConfigSpec.extraConfig option. The description of the VirtualMachineConfigSpec.extraConfig property states that you can remove an extra config option. The documentation is not correct. You can add a new option and you can reset the value for an existing option. You cannot remove an existing option.
Memory usage counter expressed as hundredth of a percent.
The document incorrectly states that memory usage is a percentage of the total configured or available memory. The usage counter value is expressed as a hundredth of a percent (1 = 0.01%), using a value between 0 and 10,000.
API versions reference page not updated in the vSphere Web Services SDK distribution. The vSphere API Reference contains a page that shows which versions of the API support the various elements. The SDK distribution contains the vSphere 4.0 version of that page; it does not show the elements added for 4.1. You can see the 4.1 version on the API Versions Reference page of the API Reference.
Context not identified for the Folder.CreateDVS_Task method. DistributedVirtualSwitch objects are located in network folders in the vSphere inventory. When you call the CreateDVS_Task method, you must provide a reference to a network folder. For more information about inventory structure, see the description of the ServiceInstance managed object in the vSphere API Reference.
DVPortgroupConfigSpec.type required for AddDVPortgroup_Task method. You must specify a portgroup type when you add a portgroup to a DistributedVirtualPortgroup. The DVPortgroupConfigSpec documentation indicates that the type property is optional.
Memory Counters - swapin. The table in the vSphere API Reference shows an incorrect collection level for the swapin counter. The correct level for the counter is 2.

API Behavior Changes

The features described on this page were available in the 4.0 release of the API, but they function differently in the vSphere API 4.1.

Behavior Changes for vSphere 4.1 ESXi Servers

300 second sampled performance data is available only from a vCenter Server.

The vSphere Web Services SDK Programming Guide v4.1 describes the system-defined performance interval for ESX/ESXi hosts. This performance interval specifies rollup data collection every 5 minutes. You cannot retrieve 5‐minute rollup data from an ESXi Server directly. You can use a vCenter Server connection to obtain 5‐minute rollup data for an ESXi Server.

Behavior Changes for All vSphere 4.1 Servers

Inventory

WaitForUpdates and CheckForUpdates methods deprecated. The WaitForUpdates and CheckForUpdates methods have been deprecated in vSphere 4.1. Use the WaitForUpdatesEx method, which allows you to set a time limit to wait for a non-empty result and to set a limit on the size of a single response.
CheckForUpdates method returns null to indicate no property updates. The CheckForUpdates method is documented as returning null if there are no updates for the specified properties. In versions prior to vSphere 4.1, CheckForUpdates returns an UpdateSet object with a zero-length filterSet update list. In 4.1, the method returns null, as documented. If you have written code based on the original incorrect behavior, it will no longer work. In 4.1, CheckForUpdates has been deprecated; use the WaitForUpdatesEx method with WaitOptions.maxWaitSeconds set to zero.
RetrieveProperties and RetrieveContents methods deprecated. The RetrieveProperties and RetrieveContents methods have been deprecated in vSphere 4.1. Use the RetrievePropertiesEx and RetrieveContentsEx methods, which allow you to set a limit on the size of a single response.
New property for PropertyFilterSpec data object. In vSphere 4.1, the property reportMissingObjectsInResults has been added to the PropertyFilterSpec data object. This affects filter creation (the CreateFilter method), update sets (the WaitForUpdatesEx method), and the results of property retrieval (the RetrievePropertiesEx and ContinueRetrievePropertiesEx methods).

Networking

DistributedVirtualPortgroup - ESX and vCenter differentiation. On ESX hosts, the ESX Server provides information about port groups that are referenced by local virtual machines or the host service console. This is a change from previous releases in which an ESX Server provides information about all port groups associated with the virtual distributed switch containing the relevant port group(s).

vCenter Server handling of port group representation has not changed. A vCenter Server will provide information about all port groups in all datacenters that it manages.
DVPortgroupConfigInfo for different port group types. An ESX Server will provide complete DVPortgroupConfigInfo data only if the port group type (DVPortgroupConfigInfo.type is ephemeral. For other port group types (earlyBinding and lateBinding), the configuration data only includes the name and type of the port group. In previous releases, the Server provides complete configuration data regardless of the port group type.
DistributedVirtualSwitch MoveDVPort_Task method. When you move a distributed virtual port to another DistributedVirtualPortgroup, a virtual machine that uses the port will reconfigure its network interface so that it is bound to the destination port group.
portConfigResetAtDisconnect default value. The default value of DVPortgroupPolicy.portConfigResetAtDisconnect is now true.
DistributedVirtualSwitch performProductSpecOperation method. Previously, the performProductSpecOperation method only updated the Nexus 1000v DistributedVirtualSwitch switch. The method now also upgrades the version of the VMware virtual switch.
IPV6 stack enabled by default. In ESX 4.1, the IPv6 stack is enabled by default. (Both IPv4 and IPv6 are enabled by default.) Previously, you had to enable IPv6 explicitly.
Host IPv6 addresses are not initialized. The host network configuration data includes a list of data objects describing the vNic adapters on the host. This data includes IPv6 address properties for both host and service console adapters.

HostNetworkSystem.networkConfig.vnic[].spec.ip.ipV6Config.ipV6Address[]
HostNetworkSystem.networkConfig.consoleVnic[].spec.ip.ipV6Config.ipV6Address[]

Previously, the ESX Server used default values from the IPv6 stack to initialize the IPv6 addresses. Now, the Server does not set the properties. To retrieve the network addresses, use the HostNetworkSystem.networkInfo property.

Storage

Database Size Estimates. The ResourcePlanningManager.estimateDatabaseSize method uses an updated algorithm to compute an estimated database size based on a particular inventory description and performance interval. Compared to output from the 4.0 algorithm, the current method produces a different estimate for a particular set of input data.

Performance Counters

Changed statistics levels for performance counters.

The following counters for the resource groups CPU and Memory have different default levels for vSphere 4.1. These counters have been deprecated.

Resource GroupCounterOld LevelNew Level
CPUguaranteed2 (4)4
Memoryheap2 (4)4
Memoryheapfree2 (4)4
Memoryswapunreserved2 (4)4

Other

Out-of-range handling (UpdateProgress method). Previously, the UpdateProgressOutOfBounds fault if you specified a percentDone value outside the range of 0..100. As of vSphere 4.0, the method behavior changed so that it adjusted the percent done value to the closest boundary. This change was not described in the 4.0 documentation.

Behavior Changes for vSphere 4.1 vCenter Servers

Events and Tasks

Fault tolerance events - virtual machine name suffix for primary/secondary. As of vSphere 4.1, event objects encode information that allows you to distinguish events generated for a fault tolerance primary virtual machine from those generated for its secondary. Events generated for virtual machines include the VmEventArgument object, which includes the name of the virtual machine. In vSphere 4.1, if the event corresponds to a primary virtual machine, the name includes the suffix "\p". If the event corresponds to a secondary virtual machine, the name includes the suffix "\s".
Filtering events for primary and secondary fault tolerance virtual machines. You can filter events for a primary fault tolerance virtual machine and all of its secondary fault tolerance virtual machines. When you call the CreateCollectorForEvents or QueryEvents method, use the entity property in the EventFilterSpec data object to set the EventFilterSpecByEntity fields. Set the entity property to the primary fault tolerance virtual machine, and set the recursion property to "all".
Event Manager processing. Event Manager now processes new events in batches. This change reduces the load on the repository and improves the scalability of vCenter. Batch processing increases the interval before availability. It may take up to 5 seconds before you can successfully query for newly posted events (for example, using event collectors).

In previous releases, the Event Manager processed each event individually and wrote it to the repository immediately. The event was available immediately after the repository posting.

Clusters

EVC-enabled clusters required for FT pairs. In vSphere 4.0 and later, you must enable EVC (Enhanced vMotion Compatibility) in a cluster to use DRS (Distributed Resource Scheduling) for FT (Fault Tolerance) primary and secondary virtual machine pairs in that cluster. You must use the vSphere Client to enable EVC for a cluster.

If EVC is not enabled, vCenter automatically creates overrides to disable DRS for FT primary/secondary pairs in the cluster (ClusterConfigSpecEx.drsVmConfigSpec[].info.enabled = "false"). Attempts to remove the overrides or to enable DRS operations will fail.
DRS override specification for secondary FT virtual machines not supported. You can specify a DRS behavior override (ClusterConfigSpecEx.drsVmConfigSpec[].info) for a primary FT virtual machine, but you cannot specify a DRS override for a secondary FT virtual machine. The secondary virtual machine will inherit whatever setting applies to its primary virtual machine.

You configure a DRS override when you reconfigure cluster compute resources. The spec parameter to the ClusterComputeResource.ReconfigureComputeResource_Task method is a ClusterConfigSpecEx object. Among other things, this object specifies the DRS behavior and configuration for individual virtual machines.

The ClusterConfigSpecEx.drsVmConfigSpec property is an array of ClusterDrsVmConfigSpec objects, each of which corresponds to the virtual machine identified by the ClusterDrsVmConfigSpec.info.key property. The array cannot contain DRS configuration information (the ClusterDrsVmConfigInfo object) that refers to a secondary virtual machine. The reconfigure method will throw the fault CannotChangeDrsBehaviorForFtSecondary.

In previous versions, it was possible to include an override for a secondary if the configuration specification also disabled DRS for the virtual machine.
Initial placement of virtual machines in EVC-enabled cluster. If a cluster has EVC enabled, DRS can now initially place FT primary virtual machines. In an EVC-enabled cluster, the DRS behavior of a primary FT VM is governed by the following settings:
  • The override specified for the primary FT virtual machine. The override applies to both the primary and its secondary virtual machine.
  • If there is no override specified for the virtual machine, DRS uses the cluster default behavior (ClusterDrsConfigInfo.defaultVmBehavior).
When you use the VirtualMachine.PowerOnVM_Task method, DRS will treat a primary FT virtual machine as it does any other virtual machine. Once the primary is powered on, vSphere Center will attempt to place the secondary.

As in vSphere 4.0, when you use the Datacenter.PowerOnMultiVM_Task method to power on an FT virtual machine, DRS attempts to find an initial placement for both the primary and secondary virtual machines. If the attempt fails, vCenter will attempt to place and power on only the primary FT virtual machine. If it can power on the primary but not the secondary, it will then disable FT for the virtual machine, and it will generate a config issue (ManagedEntity.configIssue) alerting the user that it has taken this action. See the description of the ManagedEntity.configIssue property.
DRS Load Balancing of Primary and Secondary FT Virtual Machines in an EVC-enabled Cluster In an EVC-enabled cluster (Enhanced VMotion Compatability), DRS (Distributed Resource Scheduling) can now load balance powered-on primary and secondary FT virtual machines in the cluster. The DRS behavior is governed by the DRS behavior setting for each virtual machine. If there is no DRS override configured for an FT virtual machine, DRS uses the cluster default.
Disabling High Availability with active FT hosts in a cluster. In vSphere 4.1, you can disable HA (High Availability) in a cluster while there are FT virtual machines registered on hosts in the cluster. To disable HA for a cluster, set ClusterConfigSpecEx.dasConfig.enabled to false, and specify the cluster configuration specification in a call to the ClusterComputeResource.ReconfigureComputeResource_Task method.

While HA is disabled, powered on FT virtual machines will continue to run, but HA will not restart any virtual machines after a failure. When HA is disabled, the following operations are not supported on FT virtual machines:
  • Turn on FT (VirtualMachine.CreateSecondaryVM_Task)
  • Enable FT (VirtualMachine.EnableSecondaryVM_Task)
  • Power on an FT virtual machine (VirtualMachine.PowerOnVM_Task)
  • Test failover and test secondary restart (VirtualMachine.TerminateFaultTolerantVM_Task
You cannot disconnect a host if only one virtual machine of an FT pair is registered to the host. If a host has FT virtual machines on it, the following conditions must exist before you can disconnect the host (HostSystem.DisconnectHost_Task method).
  • The host must be in maintenance mode (existing behavior).
  • Any primary FT virtual machines registered to the host must have their corresponding secondary virtual machines also registered to the same host.
  • Any secondary FT virtual machines registered to the host must have their corresponding primary virtual machines also registered to the same host.
HA override for secondary virtual machines not supported. You cannot specify HA (High Availability)override behavior for secondary virtual machines when you reconfigure cluster compute resources. However, as in vSphere 4.0, an override specified for a primary virtual machine will apply to its secondary as well.

The spec parameter to the ClusterComputeResource.ReconfigureComputeResource_Task method is a ClusterConfigSpecEx object. Among other things, this object specifies high availability behavior and configuration for individual virtual machines.

The ClusterConfigSpecEx.dasVmConfigSpec property contains an array of ClusterDasVmConfigSpec objects, each of which provides access to a virtual machine (the ClusterDasVmConfigInfo.key property). The array cannot contain HA configuration information that refers to a secondary virtual machine. The reconfigure method will throw the fault CannotChangeHaSettingsForFtSecondary.

In previous versions, it was possible to include an override for a secondary, but the override was ignored.
Powering On Virtual Machines - InsufficientResourcesException fault. DRS now checks for the number of network ports available on the host while powering on virtual machines. Before this, DRS would power on virtual machines even if there were too few network ports to accomodate them. DRS now tracks the number of network ports, and will throw the fault InsufficientResourcesFault if there are too few network ports.
VirtualMachine.runtime.memoryOverhead property updated every 10 minutes. The VirtualMachine.runtime.memoryOverhead property is now updated every 10 minutes instead of every 20 seconds. This is for scalability reasons. If you want to see changes more quickly, use the overhead statistic that is available as one of the Performance Manager memory counters.
Saving ResourcePool.runtime.memory data. By default, the ResourcePool.runtime.memory values are no longer saved to the database for performance reasons. If you want to read these values directly from the database, you can direct the Server to store them in the database by setting the value vpxd.cluster.SaveResUsageToDb to True in the file vpxd.cfg. You must restart the vpxd daemon for the updated configuration to take effect.

Provisioning

Generating a new UUID for a virtual machine. You can generate a new UUID for a virtual machine when you reconfigure the virtual machine. Specify an empty string for the instanceUuid property of the VirtualMachineConfigSpec data object when you call the ReconfigVM_Task method. Virtual Center will generate a new instance UUID for the virtual machine.
Profile.export (new privilege) The exportProfile method requires the privilege Profile.export.

Deprecations Summary

Several properties and types defined for the API have been deprecated in vSphere 4.1. This table lists each deprecated API element and identifies the new feature that takes its place.

Name of deprecated type, method, or property As of vSphere API 4.1, use instead...
Methods
PropertyCollector.CheckForUpdates PropertyCollector.WaitForUpdatesEx
PropertyCollector.RetrieveProperties PropertyCollector.RetrievePropertiesEx
PropertyCollector.WaitForUpdates PropertyCollector.WaitForUpdatesEx
VirtualMachine.AcquireMksTicket VirtualMachine.AcquireTicket
Data Objects
VirtualMachineMksTicket VirtualMachineTicket
Data Object Properties
ClusterVmToolsMonitoringSettings.enabled ClusterVmToolsMonitoringSettings.vmMonitoring
HostCapability.replayUnsupportedReason HostCapability.replayCompatibilityIssues
VirtualDisk.shares StorageIOAllocationInfo.shares
VirtualMachineRuntimeInfo.memoryOverhead PerformanceManager memory overhead counter