vSphere Web Services SDK 4.1 Release NotesLast updated: 20-Jan-2011
This document contains the following information: New Features
Known IssuesThe vSphere Web Services SDK release 4.1 has the following known issues:
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 Servers300 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 Group | Counter | Old Level | New Level |
|---|---|---|---|
| CPU | guaranteed | 2 (4) | 4 |
| Memory | heap | 2 (4) | 4 |
| Memory | heapfree | 2 (4) | 4 |
| Memory | swapunreserved | 2 (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
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:
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:
|
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).
|
|
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 |