VMware

vSphere Web Services SDK 5.0 Release Notes

Released 24-Aug-2011

Build 429209

Any version numbers contained in this document are placeholders and do not represent any commitment by VMware to have any specific features in the software included in any specific versions.

This document contains the following information:

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:

VMware-vSphere-SDK-5.0.0-build-num
    SDK
        eam
        sms-sdk
        vsphere-ws


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

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.

Managed Object
or Data Object
Property
ComputeResourcesummary.overallStatus
ClusterComputeResourcedrsFault
drsRecommendation
summary.overallStatus
DistributedVirtualSwitchsummary.vm
HostDiagnosticPartitionCreateDescriptionlayout
HostDiagnosticPartitionInfolayout
HostSystemcapability.ftSupported
configManager
summary.overallStatus
ManagedEntity configStatus
declaredAlarmState.overallStatus
disabledMethod
overallStatus
recentTask
triggeredAlarmState
ResourcePoolsummary
runtime
TaskManagerrecentTask
VirtualMachine layout
layoutEx
runtime.device
runtime.maxCpuUsage
runtime.maxMemoryUsage
storage
summary.overallStatus
summary.runtime.device
summary.runtime.maxCpuUsage
summary.runtime.maxMemoryUsage
summary.storage
VmfsDatastoreOptioninfo.layout

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

  • 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

Alarms

New Events

EntityEventDescription
Host com.vmware.vc.HA.HostIncompatibleWithHA Issued by VC when an attempt is to include an incompatible host in a HA cluster
com.vmware.vc.HA.AllIsoAddrsPingable The FDM on a host can ping all isolation addresses.
com.vmware.vc.HA.AllHostAddrsPingable The FDM on a host can now ping the management interfaces of all the other hosts in the cluster.
com.vmware.vc.HA.NotAllHostAddrsPingable The FDM on a host cannot ping the management interfaces of all other hosts in the cluster.
com.vmware.vc.HA.AutoStartDisabled Indicates that autostart has been disabled on a host. Autostart is not supported in a vSphere HA-enabled cluster.
com.vmware.vc.HA.HostHasNoIsolationAddrsDefined Indicates that a host is missing isolation addresses for isolation detection.
com.vmware.vc.HA.HostPartitionedFromMasterEvent Indicates that a master HA agent is reporting that the host is partitioned.
com.vmware.vc.HA.HostAgentStatedChangeEvent Indicates a change in state for the FDM on the host.
com.vmware.vc.HA.HostAgentErrorEvent Indicates an FDM error. Possible causes:
  • FDM is not reachable.
  • FDM is reachable but not usable due to a local APD (All Paths Down), socket issue, invalid host list, or other host issue.
If all agents are reported as being unreachable, it indicates that there is a global APD impacting the host due to a cross-host networking failure or a total cluster failure.
Datastore com.vmware.vc.HA.HeartbeatDatastoreChanged Indicates that the datastore is being used or is no longer being used for HA heartbeating.
com.vmware.vc.HA.HeartbeatDatastoreNotSufficient Indicates that the vCenter Server was unable to identify the number of heartbeat datastores for the host (default value is two).
Virtual
Machine
com.vmware.vc.HA.VmProtectedEvent Indicates that a virtual machine has transitioned to the vSphere HA protected state.
com.vmware.vc.HA.VmNotProtectedEvent Indicates that a virtual machine has remained in the unprotected state for a period of time. (This is a warning level event.)
com.vmware.vc.HA.VmUnprotectedEvent Indicates that a virtual machine has been unprotected because it has been powered off as a result of user action. (This is an informational level event.)
Cluster com.vmware.vc.HA.VcConnectedToMasterEvent Indicates that the vCenter Server discovered and connected to the FDM master on the named host.
com.vmware.vc.HA.VcDisconnectedFromMasterEvent Indicates that the vCenter Server disconnected from the FDM master on the named host.
com.vmware.vc.HA.VcCannotFindMasterEvent Indicates that the vCenter Server has been unable to connect to a master after a period of time. Possible causes - election has not converged or all agents are unreachable.
com.vmware.vc.HA.InvalidMaster Indicates that an FDM on the named host is claiming to be a master, but it is not a valid master.

Changed Events

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

EntityEventNew Conditions
Host com.vmware.vc.HA.DasHostIsolatedEvent Event generated when a host is isolated, if the process of isolation does not prevent the Server from learning of the transition. Previously, the vCenter Server generated the event after the host came out of isolation.
com.vmware.vc.HA.DasHostFailedEvent Host failed event represents host failures more accurately. Previously, the Server also generated host failure events for isolated or partitioned hosts.
Cluster HostMonitoringStateChangedEvent Indicates that host monitoring state has changed. In vSphere 5.0, it also indicates that HA agents are being upgraded.
com.vmware.vc.HA.DasFailoverHostFailedEvent Indicates that one or more configured failover hosts has failed. Previously, this event indicated the failure of the single failover host.

Obsolete Events

The following table lists events that are no longer relevant.

EntityEventNotes
Host HostExtraNetworksEvent  
HostMissingNetworksEvent  
HostUserWorldSwapNotEnabledEvent  
com.vmware.vc.HA.HostDasErrorEvent Replaced by com.vmware.vc.HA.HostAgentErrorEvent.
HostDasOkEvent  
com.vmware.vc.HA.DasAgentRunningEvent  
Cluster HostPrimaryAgentNotShortNameEvent  
HostIpInconsistentEvent  
HostDasDisablingEvent  
DasAgentUnavailableEvent  
DasAgentFoundEvent  
com.vmware.vc.HA.DasTotalClusterFailureEvent  
com.vmware.vc.HA.DasHostMonitoringDisabledEvent Replaced by HostMonitoringStateChangedEvent. This event is still used in vCenter Server to report a configuration issue when HA is disabled, but the event is not logged.

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:

Name (AlarmSpec.name)Trigger event(s)Clear event(s)
Insufficient vSphere HA failover resources InsufficientFailoverResourcesEvent (yellow) FailoverLevelRestored
Cannot find vSphere HA master agent com.vmware.vc.HA.VcCannotFindMasterEvent (red) com.vmware.vc.HA.VcConnectedToMasterEvent
DasDisableEvent
vSphere HA failover in progress com.vmware.vc.HA.ClusterFailoverActionInitiatedEvent (yellow) com.vmware.vc.HA.ClusterFailoverActionCompletedEvent

Default HA alarms on hosts:

Name (AlarmSpec.name)Trigger event(s)Clear event(s)
Host HA status com.vmware.vc.HA.HostAgentErrorEvent
com.vmware.vc.HA.HostIsolatedEvent
com.vmware.vc.HA.HostPartitionedFromMasterEvent
com.vmware.vc.HA.DasHostFailedEvent
(red)
com.vmware.vc.HA.HostDasAgentHealthyEvent

Default HA alarms on virtual machines:

Name (AlarmSpec.name)Trigger event(s)Clear event(s)
VM monitoring error VmDasResetFailedEvent (red) NA
VM monitoring action VmDasBeingResetEvent
VmDasBeingResetWithScreenshotEvent (yellow)
NA
Failover failed NotEnoughResourcesToStartVmEvent (red)
VmFailoverFailed (red)
com.vmware.vc.HA.FailedRestartAfterIsolationEvent (red)
VmPoweredOnEvent
com.vmware.vc.ha.VmRestartedByHAEvent

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:

    TaskMethod or Command
    Install a VIBHostPatchManager.InstallHostPatchV2_Task
    Uninstall a VIBesxcli software vib remove
    Retrieve a list of VIBsesxcli 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.

Name of deprecated type, method, or property As of vSphere API 5.0, use instead...
Managed Object Properties
Profile.descriptionRetrieveDescription
Data Objects
ClusterDasAamHostInfoHostRuntimeInfo.dasHostState
ClusterDasAamNodeStateHostRuntimeInfo.dasHostState
DasAgentFoundEvent In vSphere API 5.0, the event is no longer relevant
DasAgentUnavailableEvent In vSphere API 5.0, the event is no longer relevant.
HostDasDisablingEvent In vSphere API 5.0, the event is no longer relevant.
HostDasErrorEventEventEx
HostDasOkEvent In vSphere API 5.0, the event is no longer relevant.
HostExtraNetworksEvent In vSphere API 5.0, the event is no longer relevant.
HostGetShortNameFailedEvent In vSphere API 5.0, the event is no longer relevant.
HostIpInconsistentEvent In vSphere API 5.0, the event is no longer relevant.
HostIpToShortNameFailedEvent In vSphere API 5.0, the event is no longer relevant.
HostMissingNetworksEvent In vSphere API 5.0, the event is no longer relevant.
HostPrimaryAgentNotShortNameEvent In vSphere API 5.0, the event is no longer relevant.
HostShortNameInconsistentEvent In vSphere API 5.0, the event is no longer relevant.
HostShortNameToIpFailedEvent In vSphere API 5.0, the event is no longer relevant.
HostUserWorldSwapNotEnabledEvent In vSphere API 5.0, the event is no longer relevant.
VmRestartedOnAlternateHostEventEventEx
Data Object Properties
DVSConfigSpec.maxPorts In vSphere API 5.0, the default value of this propoerty is maxint.
DVSFeatureCapability.networkResourceManagementSupportednetworkResourceManagementSupported
DVSFeatureCapability.networkResourcePoolHighShareValuenetworkResourcePoolHighShareValue
HostConfigInfo.sslThumbprintInfosslThumbprintData
VMwareDVSPortSetting.qosTag This property has been deprecated.
VirtualMachineGuestSummary.toolsStatustoolsVersionStatus2
VirtualMachineGuestSummary.toolsVersionStatustoolsVersionStatus2
VmDiskFileInfo.controllerType In vSphere API 5.0, this property is no longer relevant and should not be used.
VmDiskFileQueryFilter.controllerType In vSphere API 5.0, this property is no longer relevant and should not be used.
VmDiskFileQueryFlags.controllerType In vSphere API 5.0, this property is no longer relevant and should not be used.