VMware

VMware vSphere Web Services SDK 4.0 Release Notes

Last updated:   1-June-2009

release notes   |   Known Issues   |   Deprecations   |   Behavior Changes

Behavior Changes in vSphere API 4.0

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

All vSphere 4.0 Servers

Inventory

Inventory organization. The view list for InventoryView and ContainerView managed objects can now include Network and Datastore objects (and associated Folder objects) if created by a client using the vim25/4.0 namespace.

Networking

UpdateNetworkConfig method. The HostNetworkSystem UpdateNetworkConfig method now supports edit operations when changeMode is modify. Although previously documented, edit operations were not supported until vSphere 4.0.

New privilege Network.Assign. The new privilege Network.Assign applies to the previously-existing methods Folder.createVm_Task and VirtualMachine.ReconfigVM_Task. The new role NetworkConsumer contains only this privilege.

Performance Monitoring

QueryPerf results. The QueryPerf method now succeeds even if some of the entity references cannot be resolved. The result contains only metrics for entities that can be resolved and that are capable of generating statistics.

Session Security

SessionManager session list refers to aggregate sessions. Previously, the SessionManager sessionList property was a list of all currently active sessions. Now, the list refers to aggregate sessions. If you use the cloneSession method to create other sessions, all such sessions will belong to the same aggregate session. Only one entry appears in the session list for the aggregate. If you terminate the aggregate session, the server also terminates all associated cloned sessions.

Default limit of concurrent SOAP sessions. The default limit of number of concurrent authenticated SOAP sessions has increased from 100 to 500.

Fault Tolerance (FT) secondary virtual machine permissions. You cannot set permissions on an FT secondary virtual machine. An FT secondary always inherits the permissions of its FT primary.

DistributedVirtualSwitch object permissions. You cannot assign permissions to DistributedVirtualSwitch objects.

VirtualApp object permissions. VirtualApp objects inherit permissions from both Folder and ResourcePool, like VirtualMachine objects. Virtual machines within a virtual application are not associated with a folder, and inherit permission from their parent VirtualApp only, unlike ordinary VirtualMachine objects.

QueryConfigTarget method filtering. The QueryConfigTarget method (EnvironmentBrowser) returns a ConfigTarget object. Starting with vSphere 4.0, the server filters the network and datastore lists in the object according to the visibility you have into the inventory as defined by permissions.

Storage

New privilege Datastore.AllocateSpace. The new privilege Datastore.AllocateSpace applies to the following previously-existing methods:

  • Folder.CreateVM_Task
  • VirtualMachine.CloneVM_Task
  • VirtualMachine.ReconfigVM_Task
  • VirtualMachine.RelocateVM_Task
  • VirtualMachine.CloneVM_Task

There is a new role DatastoreConsumer that contains only that privilege.

CreateNasDataStore method. The CreateNasDatastore method for HostDatastoreSystem objects throws the AlreadyExists exception instead of a DuplicateName exception.

ScsiLun.canonicalName. The format of the canonicalName property has changed. For example:

  • ESX 3.x:  vmhba1:0.1
  • ESX 4.0:  naa.600601601eb71600247c584a9d66da11

VMHBA names were introduced by VMware and are not persistent across host reboots. The canonicalName uses the SCSI standard to obtain an identifier. The SCSI standard supports the following set of the identifiers: "T10", "EUI", "NAA", "RTP1", "TPG", "LUG", "MD5", and "SNS". The first part of the canonicalName determines the SCSI namespace and the rest is the identifier. The canonicalName uses the highest quality identifier to help you correlate across ESX 4.0 hosts. You can also use the ScsiLun.Descriptor property, which is an array of identifiers that represent ScsiLun devices. An example of a descriptor is vml.<>, which represents a VMware specific identifier.

ScsiLun.deviceName and ScsiLun.devicePath. The device path format has changed. These properties indicate device paths on ESX/ESXi systems. For example:
  • ESX 3.x:  /vmfs/devices/disks/vmhba1:0:1
  • ESX 4.0:   /vmfs/devices/disks/naa.600601601eb71600247c584a9d66da11

HostMultipathInfoLogicalUnit.id. Previously, the logical unit identifier was the same as ScsiLun.canonicalName. In ESX/ESXi 4.0, this maps to ScsiLun.Uuid. For example:

  • ESX 3.x:   vmhba32:0:3
  • ESX/ESXi 4.0:  0200010000600601601eb71600247c584a9d66da1152414944203

HostMultipathInfoPath.name. The name format has changed. For example:

  • ESX 3.x:   vmhba1:0:1
  • ESX 4.0:   fc.20000000c9501cfa:10000000c9501cfa
               -fc.50060160b020c917:500601683020c917
               -naa.6006016058b7160002c94e0d30aeda11
In ESX/ESXi 3.5, the path identifier was generated from the adapter, target, and LUN number. In ESX/ESXi 4.0, the path name is generated using the adapter identifier, target identifier and LUN identifier.

 

HostMultipathInfoLogicalUnit.policy. The policy values have changed.

  • ESX 3.x:  String values: mru, fixed
  • ESX/ESXi 4.0:  VMW_PSP_MRU, VMW_PSP_RR, VMW_PSP_FIXED

You can obtain the set of valid strings by using the QueryPathSelectionPolicyOptions method defined for the HostStorageSystem managed object.

HostScsiTopology data object.

  • ESX 3.x:   Describes all the SCSI devices managed by the host.
  • ESX/ESXi 4.0:   Describes the SCSI topology for devices that are managed by Native Multipathing Plugin (NMP) supplied by VMware.

With Pluggable Storage Architecture (PSA), you can use a third-party plugin for path management. The HostScsiTopology object contain only the SCSI topology information for devices that are claimed and managed by NMP. For a third-party plugin, use the HostPlugStoreTopology object.

HostMultipathInfo data object.

  • ESX 3.x:   Describes path states for to all the SCSI devices managed by the host.
  • ESX 4.0:   Describes the path sets of paths that are managed by Native Multipathing Plugin (NMP) supplied by VMware.

With Pluggable Storage Architecture (PSA), you can use a third-party plugin for path management. This object only contains the HostMultipathInfo information for paths that are claimed and managed by NMP. For a third-party plugin, use the HostPlugStoreTopology and HostMultipathStateInfo data objects.

VirtualDiskRawDiskMappingVer1BackingInfo.deviceName property. The device name format has changed. For example:

  • ESX 3.x:   vmhba1.0.1:1
  • ESX 4.0:   vml.02000200006006016058b7160002c94e0d30aeda11524149442035

Use the lunUuid property to match the virtual machine's raw device mapping disk to ScsiLun.uuid. You can also use the ScsiLun.Descriptor array to match one of the descriptors to deviceName.

HostScsiDiskPartition.diskName property. (HostVmfsVolume.extent) The disk name format has changed. For example:

  • ESX 3.x:   vmhba1:0:1
  • ESX 4.0:   naa.600601601eb71600247c584a9d66da11

For a datastore that is local to one host, datastore.info.vmfs contains host-specific information. If a datastore used by both vSphere 4.x and vSphere 3.x systems, datastore.info.vmfs contains diskName from any of its hosts. In that case, host-specific information can be accessed through Vim.Host.ConfigInfo.FileSystemMount data object.

EnvironmentBrowser.QueryConfigTarget method. The QueryConfigTarget output for ScsiDiskDeviceInfo.name has changed.

  • ESX 3.x:    /vmfs/devices/disks/vml.02000200006006016058b7160002c94e0d30aeda11524149442035
  • ESX/ESXi 4.0:    /vmfs/devices/disks/naa.600601601eb71600247c584a9d66da11

When you call QueryConfigTarget for a host, the output is consistent with what the host supports. In an automatic DRS-enabled cluster environment, the vCenter Server system provides one common entry for the disks that are shared by all the hosts in the cluster. vCenter Server system uses /vmfs/devices/disks/naa.xxx names if any shared LUN is visible to the ESX/ESXi 4.0 host.

Method Parameters

The following table lists methods that have a new optional parameter in the 4.0 API. As the new parameters are optional, SOAP compatibility is preserved, and existing VI API 2.5 clients will continue to work correctly.

Method Calling Sequence    (new optional parameter shown in bold font)
AddHost_Task AddHost_Task(_this, spec, asConnected, resourcePool, license)
AddStandaloneHost_Task AddStandaloneHost_Task(_this, spec, compResSpec, addConnected, license)
CreateTask CreateTask(_this, obj, taskTypeId, initiatedBy, cancelable, parentTaskKey)
ExtendVirtualDisk_Task ExtendVirtualDisk_Task(_this, name, datacenter, newCapacityKb,eagerZero)
FindByUuid FindByUuid(_this, datacenter, uuid, vmSearch, instanceUuid)
QueryVmfsDatastoreExtendOptions QueryVmfsDatastoreExtendOptions(_this, datastore, devicePath, suppressExpandCandidates)
RelocateVM_Task RelocateVM_Task(_this, spec, priority)
RevertToCurrentSnapshot_Task RevertToCurrentSnapshot_Task(_this, host, suppressPowerOn)
RevertToSnapshot_Task RevertToSnapshot_Task(_this, host, suppressPowerOn)
UpdateInternetScsiAuthenticationProperties UpdateInternetScsiAuthenticationProperties(_this, iScsiHbaDevice, authenticationProperties, targetSet)

If you have an SDK 2.5 client that uses the Java client stubs for the API, you must modify your client code to recompile it with the client stubs for the 4.0 API. The client stubs are in the vim25.jar file from the VMware Web Services SDK 4.0 package.

  • For each method that has a new optional parameter, add a null argument to the method invocation for compatibility with the 4.0 client stubs. See the vSphere API Reference for descriptions of the methods.
  • Many data objects contain new properties for vSphere 4.0. If your client calls a constructor for any of these objects, add a null argument to the call. See the vSphere API Reference for information about new properties for data objects. See the Programming Guide for more information about modifying VI SDK 2.5-based client applications to use vSphere API 4.0 features.

API Requiring vCenter Server

Events and Tasks

Out-of-range page size generates a fault (EventHistoryCollector and TaskHistoryCollector). If you specify a page size that is out of range when you call SetCollectorPageSize (less than 1 or greater than 1000), the method throws an InvalidArgument fault. In VI 2.5, the method sets the collector page size to 1 or 1000 without corresponding notification.

Timestamp precision with Oracle databases. Event and Task time stamps are now preserved with a 1-millisecond precision when using an Oracle database, but only for new installations (those not upgraded from VC 2.5). Previously, time stamps were truncated to a 1-second precision internally. With SQL Server, time stamps are preserved with a 3-millisecond precision, as before.

Clustering

APIs and Fault Tolerance (FT).A number of the APIs behave differently when processing an FT virtual machine. FT is a new feature, so these changes do not represent a behavior change. However, you should re-evaluate the assumptions on which your applications and scripts are based. The following list provides some examples:

  • Most virtual machine APIs are not supported for a FT secondary virtual machine.
  • You cannot change the DRS behavior of a FT primary or secondary virtual machine.
  • You cannot power on a secondary virtual machine by invoking either power on API.
  • You cannot add a host with FT virtual machines to a non-HA cluster.
  • You cannot set affinity rules on the secondary virtual machine.
  • Any APIs that return a list of virtual machines include the secondary virtual machine in the list.

Improved information about incompatible hosts. In VI 2.5, when the Distributed Resource Scheduler (DRS) is unable to place a virtual machine because there are no compatible hosts for it, the PowerOnMultiVM_Task method returns the fault NoCompatibleHost. The VMware server reports this fact but does not supply any additional information. In 4.0, this fault now includes faults that explain why there was no compatible host. The server returns information only about the registered host.

Improved handling when starting virtual machines. In VI 2.5, if there are no hosts compatible with a virtual machine to be powered on, DRS does not attempt to power on any of the virtual machines that were specified in the call to PowerOnMultiVM_Task. In 4.O, DRS correctly handles this situation by marking the problem virtual machines as not attempted and then attempting to start the remaining virtual machines.

Improved handling of cluster DRS virtual machine configuration. You can specify a DRS behavior override when you use the ReconfigureComputeResource_Task method to add a configuration to a virtual machine. In VI 2.5, the VirtualCenter Server throws the fault InvalidArgument if the virtual machine already has an override. The add operation is defined for the ClusterDrsVmConfigSpec object. A copy of this object is included in the ClusterConfigSpecEx object that you pass to ReconfigureComputeResource_Task. In 4.0, the vCenter Server system allows the reconfiguration operation.

High Availability

Virtual machine health monitoring. DasVmSettings.VmToolsMonitoringSettings is a new field that you can use to define the VM health monitoring settings for a virtual machine. This used to be controlled through advanced options.

  • ESX 3.5: advanced options
  • ESX 4.0: vmToolsMonitoringSettings property in ClusterDasVmSettings data object

Distributed Resource Scheduler

vSphere 4 returns a list of faults for group power on operations, and returns the DrsFault from the last DRS invocation as a Cluster property. These faults represent error conditions that prevent the DRS algorithm from generating optimal recommendations.

Provisioning

Clone creation and power-on. In VI 2.5, the VirtualMachine.CloneVM_Task method creates the clone and powers it on in a single, atomic operation (VirtualMachineCloneSpec.powerOn is true). If power-on fails, the entire operation fails. In vSphere 4.0, the two operations are handled separately. If power-on fails, the clone is still created.

Live clone operation. In vSphere 4.0, you can use the VirtualMachine.CloneVM_Task method on powered on virtual machines (a live clone operation). In VI 2.5, the method throws an InvalidPowerState fault when you attempt to clone powered-on virtual machines.

Migrate, relocate, and clone events. In VI 2.5, the MigrateVM_Task, RelocateVM_Task, and CloneVM_Task methods log events of the following types:

  • MigrationErrorEvent
  • MigrationHostErrorEvent
  • MigrationHostWarningEvent
  • MigrationResourceErrorEvent
  • MigrationResourceWarningEvent
  • MigrationWarningEvent
In vSphere 4.0, these methods log only MigrationResourceErrorEvent and MigrationResourceWarningEvent. These events still encapsulate the full range of possible fault types.

 

Snapshot warning removed. In VI 2.5, VirtualMachine.MigrateVM_Task and VirtualMachine.RelocateVM_Task generate a warning when you migrate a virtual machine that has snapshots. In vSphere 4.0, these methods no longer generate this warning.

VirtualMachine.PowerOnVM_Task method. In VI 2.5, the VirtualMachine.PowerOnVM_Task method logs events of the following types:

  • MigrationErrorEvent
  • MigrationHostErrorEvent
  • MigrationHostWarningEvent
  • MigrationResourceErrorEvent
  • MigrationResourceWarningEvent
  • MigrationWarningEvent
None of these events are logged in vSphere 4.0.

 

Virtual machine operations on hosts in maintenance mode. In VI 2.5, you cannot unregister or power-on a virtual machine on a host in maintenance mode. In vSphere 4.0, you can unregister such a virtual machine. If the host is part of a DRS cluster, and another compatible host for the VM can be found, you can power-on the virtual machine.