vSphere Web Services SDK 5.0 Release Notes

Released 24-Aug-2011

Build 429209

Additions to the vSphere API in vSphere 5.0

For information about additions to the vSphere API (new managed object types, data object types, properties, and methods), see the vSphere API Reference. The main landing page for the vSphere API Reference contains links to this information in the section "What's New in vSphere API 5.0?". The vSphere API Reference is also available in the vSphere Web Services SDK, in the ReferenceGuide directory:

    SDK\vsphere-ws\docs\ReferenceGuide\index.html

Distribution Kit

Starting with vSphere 5.0, the vSphere Web Services SDK is distributed as part of the VMware vSphere Management SDK. To download the SDK distribution, use the Download link. The vSphere Management SDK is a collection of vSphere SDKs. When you extract the contents of the distribution kit, the vSphere Web Services SDK is contained in the vsphere-ws sub-directory:

Behavior Changes

The features described here were available in the 4.1 release of the API, but they function differently in the vSphere API 5.0.

• Behavior Changes for All vSphere 5.0 Servers
• Behavior Changes for ESX 5.0 Servers
• Behavior Changes for vSphere 5.0 vCenter Servers

Behavior Changes for All vSphere 5.0 Servers

Storage

• The SMS (Storage Management Service) API is no longer experimental. To communicate with the 5.0 SMS, client applications must use API stubs from the 5.0 SMS SDK. The 5.0 SMS is not backwards compatible with vSphere 4.x client stubs. The SMS SDK contains two sets of stubs, one for 5.0 communication and one for communication with previous servers.
• In vSphere 5.0, virtual machine snapshot redo files are located in the same directory as the disk snapshot. Previously, the virtual machine snapshot redo file was located in the same directory as the snapshot file (VirtualMachineFileInfo.snapshotDirectory).

Property Collector Notification Exclusions (Deprecation)

In most cases, vSphere Servers will track changes in property values. You can obtain property value updates by calling the WaitForUpdatesEx method and specifying a non-null value for the version parameter. For the properties in the following table, this behavior is deprecated and in a future release, vSphere Servers will not generate notification for these properties. These properties change continuously and this will avoid performance and scalability bottlenecks.

When the current behavior changes, you can use the PropertyCollector methods RetrievePropertiesEx or WaitForUpdatesEx to obtain the current value of these properties. If you use the PropertyCollector.WaitForUpdatesEx method, specify an empty string for the version parameter. Any other version value will not produce any property values.

Behavior Changes for ESX 5.0 Servers

• On ESXi 5.0 hosts, the HostServiceSystem methods StartService and StopService do not throw InvalidState faults. On hosts with ESX/ESXi 4.1 or earlier software, the methods throw InvalidState faults to indicate that the service is already running. ESXi 5.0 hosts do not throw a fault in this situation.

Behavior Changes for vSphere 5.0 vCenter Servers

The following sections provide information about behavior changes for vSphere 5.0 vCenter Servers.

• Performance Counters
• Clusters
• High Availability

Performance Counters

• Datastore performance counter name changed - sizeNormalizedClusterLatency changed to sizeNormalizedDatastoreLatency. The name for the datastore counter for normalized latency is sizeNormalizedDatastoreLatency. Previously, this counter in the PerformanceManager.perfCounter list was named sizeNormalizedClusterLatency. The 4.1 vSphere API Reference incorrectly identified this counter as sizeNormalizedDatastoreLatency. The counter name has been changed to correspond with the documentation.

Cluster Behavior

• ClusterComputeResource.ReconfigureComputeResource_Task method - vSphere 5.0 HA includes changes in cluster failover policy support (ClusterConfigSpecEx.dasConfig.admissionControlPolicy).
  • Number of host failures - The Server does not impose any restriction on the number of host failures for the ClusterFailoverLevelAdmissionControlPolicy (ClusterFailoverLevelAdmissionControlPolicy.failoverLevel). Previously, the number of failures was limited to a maximum of four.
  • Number of failover hosts - You can specify more than one failover host for the ClusterFailoverHostAdmissionControlPolicy. (ClusterFailoverHostAdmissionControlPolicy.failoverHosts[]).
• VirtualMachineRuntimeInfo.dasVmProtection property - vCenter Server uses the VirtualMachineRuntimeInfo.dasVmProtection property to indicate the vSphere HA (High Availability) protection state for the associated virtual machine.
• HostRuntimeInfo.dasHostState property - vCenter Server uses the HostRuntimeInfo.dasHostState property to indicate the vSphere HA availability state of an active host in a vSphere HA-enabled cluster. The host states are defined by the ClusterDasFdmAvailabilityState enum. The ClusterComputeResource.RetrieveDasAdvancedRuntimeInfo method no longer returns any host state information.
• DasAamHostInfo and DasAamNodeState data objects deprecated. - vCenter Server 5.0 does not use the DasAamHostInfo and DasAamNodeState data objects and will not return them under any circumstances.
• Heartbeat datastore changes - When you create or reconfigure an HA cluster, you can specify the policy for the choice of datastores to use for storage heartbeating (the ClusterDasConfigInfo.hbDatastoreCandidatePolicy property) and a preferred list of datastores (the ClusterDasConfigInfo.heartbeatDatastore property). Based on the policy setting and the preferred list, the vCenter Server chooses a list of datastores. The ClusterComputeResource.RetrieveDasAdvancedRuntimeInfo method returns the selected list in the ClusterDasAdvancedRuntimeInfo.heartbeatDatastoreInfo property.

High Availability Behavior

In vSphere 5.0, active hosts in an HA cluster form a fault domain. An FDM (Fault Domain Manager, also known as the HA agent) runs on each host. The FDM is responsible for monitoring host and virtual machine availability and restarting virtual machines under failure circumstances. For information about FDM, see the description of the ClusterDasFdmHostState data object in the vSphere API Reference.

The following sections contain tables of new or changed events and alarms, some of which have been changed or introduced for the FDM architecture. Events can be standard events defined for the vSphere API, or they can be dynamically typed EventEx events. EventEx events are identified by the com.vmware.vc.HA. prefix in the EventEx.eventTypeId property value.

Events

• New Events
• Changed Events
• Obsolete Events

Alarms

New Events

Changed Events

The following table lists existing events that are generated under new conditions.

Obsolete Events

The following table lists events that are no longer relevant.

Alarms

The default alarms for High Availability have been changed. The following tables list the default HA alarms for clusters, hosts, and virtual machines. These tables show the name of the alarm (AlarmSpec.name) and events that trigger and clear the alarm. These events can be standard events defined for the vSphere API, or they can be dynamically typed EventEx events. EventEx events are identified by the com.vmware.vc.HA. prefix in the EventEx.eventtypeId property value.

Default HA alarms on the cluster:

Default HA alarms on hosts:

Default HA alarms on virtual machines:

Resolved Issues

• Hardware chassis serial number available in HostSystemIdentificationInfo.identifierValue property. Previously, the vSphere API did not show the chassis serial number for managed servers from most hardware vendors. This has been fixed. The chassis serial number is available for all hardware vendors.
• ResignatureUnresolvedVmfsVolume_Task method returns a valid managed object reference to the new datastore. Previously, for clients connected to a vCenter Server, the ResignatureUnresolvedVmfsVolume_Task method returned an invalid managed object reference to the resolved datastore (the HostResignatureRescanResult.result property). This has been fixed in the current release.

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.
  
  
• vCenter Server might unexpectedly shut down and restart during cluster reconfiguration.

  If you call the ReconfigureComputeResource_Task method and pass a ComputeResourceConfigSpec object, the vCenter Server might fail and then restart. To avoid this behavior, pass a ClusterConfigSpecEx object to the method. This failure might also occur if you use the VMware vSphere Client to enable the storage-policy feature on a cluster or host. The failure is a result of a race condition, so the risk of failure is low.

• vSphere 5.0 Server WSDL files obtained directly from a Server are not complete.

  It is possible to retrieve the vSphere API WSDL files from an ESXi or vCenter Server. These WSDL files are not complete. You cannot use the server-based WSDL; SOAP toolkits cannot process it correctly because the Server does not have a complete set of the schema files. The vSphere Web Services SDK contains a complete WSDL file configuration (WSDL and schema files), located in the following directory of the vSphere Management SDK distribution:

      VMware-vSphere-SDK-5.0.0-429209\SDK\vsphere-ws\wsdl\vim25\

• UpdateCounterLevelMapping Method Consequences

vSphere 5.0 introduces the Performance Manager method UpdateCounterLevelMapping. This method changes the level of data collection for a set of performance counters. Use of this method can cause a significant increase in data collection and storage, along with a corresponding decrease in performance. See the description of the UpdateCounterLevelMapping method in the vSphere API Reference.

• JAX-WS Bindings for the vSphere Web Services SDK

  The vSphere Web Services SDK includes two kinds of Java stub bindings - Axis and JAX-WS (Java API for XML Web Services). The Axis bindings are deprecated in vSphere 5.0. The JAX-WS bindings are new for vSphere 5.0. The vSphere Web Services SDK contains examples of using the JAX-WS bindings to call vSphere API methods. These are located in the SDK directory SDK/vsphere-ws/java/JAXWS/sameples/com/vmware/. See the Developer's Setup Guide for information about how to set up your Java environment to use the vSphere API.

  If you have an existing Java application that uses the Axis bindings to call vSphere API methods, make the following changes to port the application to JAX-WS.

  1. SSL Connection setup and Access to vSphere API methods requires a VIM port object which defines method entry points. The JAX-WS operations for obtaining the VIM port object and performing setup for the SSL connection are different than the Axis operations.
     
     
     • The Axis implementation uses the following elements to support server connection and access to vSphere API methods:
       - VimServiceLocator class
       - VimServiceLocator.setMaintainSession method
       - VimServiceLocator.getVimPort method - VimPortType class
       
     • The JAX-WS implementation uses the following elements to support server connection and access to vSphere API methods:
       - VimService class
       - VimService.getVimPort method
       - VimPortType class
       - VimPort.BindingProvider request context class
       

     The following code fragment shows an example of using the JAX-WS bindings to set up a connection with a vSphere Server. The client creates a VimService object and uses the getVimPort method to access the VimPort object. The client then sets the request context properties for the SSL connection with the Server. The url value for ENDPOINT_ADDRESS_PROPERTY is the Server URL.

     VimPortType vimPort;
VimService vimService = new VimService();
try {
     vimPort = vimService.getVimPort();
     Map ctxt = ((BindingProvider) vimPort).getRequestContext();
     ctxt.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, url);
     ctxt.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);
} catch (Exception se) {
     se.printStackTrace();
}

  
  
  2. JAX-WS uses collection classes. In situations where the Axis bindings specify arrays, use Java lists. The following code fragment is an example of using the Java list operation add to set the pathSet property for the PropertySpec data object. The JAX-WS accessor method getPathSet returns a reference to the mapped XML representation of the list. Using this reference to add the property name will update the list.
     
         PropertySpec pSpec = new PropertySpec();
    [...]
    pSpec.getPathSet().add("name");
  
  
  3. JAX-WS generates SoapException faults for faults that are not referenced in the WSDL. The JAX-WS does not recognize faults that are not defined in com.vmware.vim25. To catch undeclared faults that may be generated during a session, your client must use try{}catch(SoapException se){} blocks. This is a known issue for JAX-WS.
  
  
  4. JAX-WS may return XML-formatted data in PropertyCollector updates. In some cases, JAX-WS may not deserialize the Server response to a PropertyCollector request correctly. When this happens, the ObjectUpdate.changeSet.val property will contain XML-formatted data.


• VirtualDiskManager.CopyVirtualDisk_Task method does not support the specification of a virtual disk type. The CopyVirtualDisk_Task method defines the destSpec parameter which identifies the disk and adapter types for the new virtual disk. The method ignores the destSpec values and uses a preallocated format (VirtualDiskType.preallocated) and a virtual BusLogic adapter (VirtualDiskAdapterType.busLogic).
• vDS (vNetwork Distributed Switch) merge operation may fail. Under certain conditions, a virtual distributed switch merge operation (DistributedVirtualSwitch.MergeDvs_Task) may fail in an unpredictable way. The error condition can occur with a virtual machine that uses ephemeral port groups (DistributedVirtualPortGroup.config.type) on two switches. If you attempt to merge the two switches, the method may produce one of the following situations.
  • Throws an InvalidArgument fault.
  • Executes to completion but produces invalid device backing on the virtual machine that is connected to the switches. In this case, subsequent power operations on the virtual machine will fail.
  To avoid these possibilities, wait five minutes after performing virtual machine power operations and make sure that there is no residual power operation activity before calling the MergeDvs_Task method.

Documentation Issues

• As of vSphere 5.0, vSphere bulletins are not stored on ESXi hosts. As a consequence, the QueryHostPatch_Task method does not return any data about installed bulletins. To obtain information about installed patches, use the ESXCLI command "esxcli software vib list". This command returns the complete list of VIBs (vSphere Installation Bundles) installed on the host.

  To manipulate VIBs on ESXi hosts, use the following vSphere API method and ESXCLI commands:

  Task	Method or Command
  Install a VIB	HostPatchManager.InstallHostPatchV2_Task
  Uninstall a VIB	esxcli software vib remove
  Retrieve a list of VIBs	esxcli software vib list

• The vSphere API Reference shows incorrect character case for host file system type values. The type values should be expressed in upper case. The following list shows the correct case for HostFileSystemVolume.type values.

      VMFS
      NFS
      CIFS
      VFAT
  

• 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.
• Documentation issues: performance counter documentation. The performance counter tables have been updated for vSphere 5.0. These tables show the complete list of performance counters that are available. For some counters, the documentation is not complete.

Deprecations Summary

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