VMware Infrastructure SDK 2.0

Changes Since the Previous VMware SDK (VirtualCenter 1.x) Release

If you have been using SDK 1.x, there are several compatibility issues you must take into account.

PutUpdates Limitations
PutUpdates operations have the following limitations:

  • The VirtualNetworkAdapter.network attribute refers to a HostNetworkInfo data object defined on the host object. The VirtualNetworkAdapter.mode and VirtualNetworkAdapter.deviceName attributes are no longer used, and any values set with them are ignored. Create and modify host network references for VirtualNetworkAdapters for virtual machines using the VirtualNetworkAdapter.network attribute.

  • Certain PutUpdates were incorrectly documented in the SDK 1.x. PutUpdates on datalocator still does not work in the compatability layer. Virtual CD-ROMs and virtual floppies must refer to an ISO or floppy image file that is either in a datastore or has an absolute path.
    For example: [datastorename] cdrom.iso
    OR
    []/myisos/cdrom.iso

    Note:The cdrom.iso file need not be present when the CD is created.

  • Configuration of VMotion on ESX Servers using SDK 1.x requires two special considerations:

    • Do not use the gateway property of the migrationInfo structure to enable migrationInfo settings. This property is comparable to the defaultGateway property of the HostIpRouteConfig data object, and the default gateway for the HostSystem cannot be modified when enabling VMotion. You must modify it through the VirtualCenter Client or an SDK 2.0 API client application.

    • Specify the subnet property of the migrationInfo structure to enable migration in ESX Server 3.0.

  • A setting of "auto detect" for cd["key"]/hostdev of CD-ROM is converted to /dev/cdrom. This might change in the final release.

  • ESX Server 3.0 hosts do not yet support hard disk writethru.

  • ESX Server 3.0 hosts do not yet support setting memory/controls/max.

  • ESX Server 2.5 and 3.0 hosts do not support Creating virtual machines with SCSI CD-ROMs.

  • ESX Server hosts do not support IDE hard disks.

  • Only ESX Server 2.5 hosts support PutUpdates on hardware/net/controls (that is, NetworkControls) attributes. ESX Server 3.0 does not support PutUpdates on these attributes.

Limitations on Performance Collection Interval and Duration
Performance collection intervals must be multiples of 60 seconds. If you try to create a performance collector that is not a multiple of 60 seconds, an error is thrown.

In addition, the number of samples that can be collected is limited. The duration (defined as the number-of-samples multiplied by the interval) must be less than the duration of the next performance collector and greater than the duration of the previous performance collector. If you try to create a performance collector with a number of samples that exceeds these limitations, the create operation does not fail. Instead, the perf collector that is created has the closest possible number of samples to what you specified, but not necessarily the same number.

For example, suppose you have a 1-minute and a 5-minute performance collector. If you try to create a 2-minute performance collector, the duration for the new 2-minute collector must be greater than the duration of the 1-minute collector and less than the duration of the 5-minute performance collector.

Performance Collectors Do Not Persist
Performance collectors do not persist. Restarting the VirtualCenter Server erases the performance collectors.

Statistics Filter Level
In VirtualCenter, for performance reasons, not all statistics are gathered at the default setting. VirtualCenter 2.0 defines several levels of statistics gathering through the filterLevel. The lowest level is 1 and the highest is 4. The lower the level, the fewer statistics are gathered. To achieve full compatibility with 1.x servers with respect to statistics gathering, manually configure vpxd to use level 4 statistics. You must do this in addition to turning on 1.x compatibility.

To resolve this issue, edit the vpxd.cfg file, which is typically found at:

C:/Documents and Settings/All Users/Application Data/VMware/VMware VirtualCenter/vpxd.cfg

Add the following to the vpxd.cfg file:

<vpxd>
   <stats>
      <filterLevel>4</filterLevel>
   </stats>
</vpxd>

Note that if the "vpxd" or "stats" tags are already present in vpxd.cfg you do not need to add them. However, you must insert any part of the above expression that is missing between the already existing tags.

You can also change the filterLevel settings can also be changed using the VI Client. For more information, see the documentation for that product.

Limit on Number of Event Collectors
You can create no more than 10 custom event collectors per session when using the 1.x compatibility feature of the SDK.

2.0 Event Argument Objects Are Not Visible in 1.x
None of the event argument objects (VmEventArgument, HostEventArgument, and so on) from the corresponding 2.0 Event object are visible in the 1.x EventArgInfo datatype. Additional arguments are not yet implemented.

Event Messages Differ Between 1.x and 2.0
Events in the SDK 2.0 API are represented as classes defined for each event. For more information about 1.x Event messages and their corresponding 2.0 Event class names, refer to the Messages pdf. This document also includes the additional events contained in SDK 2.0 for virtual machines and hosts. The SDK 2.0 API contains additional events not shown in this list, but which are documented in the VMware Infrastructure SDK Reference Guide.

Setting Autostart Configuration on Virtual Machines on ESX 2.5.x Hosts not Supported in Some Cases
VirtualCenter 1.x allowed autostart configuration through the 1.x Webservice API, but this is no longer supported in vma1-compatibility. This is because the vma1-compatibility layer depends on VirtualCenter Server, and VirtualCenter Server does not support this capability on ESX 2.5.x hosts. Furthermore, the VIM API does not support this capability, on ESX 2.5.x hosts either.

Applications Using 1.x Cannot Utilize All 3.0 Event Parameters
The 1.x compatibility layer assumes that events are composed exclusively of data objects, despite the fact that this is not always the case. For example, Event objects may include faults, booleans, or string parameters, which are not exposed. Consequently, applications that use the 1.x compatibility layer may not see all Event parameters that are available through the VMware Infrastructure 3.0 API.

Using the 1.x ChangePermissions Operation Produces Misleading Results
Using the 1.x ChangePermissions operation may not succeed in changing the requested permissions. In some cases, even though the operation failed, no fault is thrown, incorrectly implying the operation was successful.

GetUpdates on PerfCollectors in the 1.x Compatability Layer Does Not Return Updates
GetUpdates on PerfCollectors does not return updates on performance statistics for PerfCollectors in the 1.x SDK compatability layer.

1.x Clients Do Not Find VMotion Networks in the Expected Location
When a VMotion network is added to VirtualCenter 2.0, the VMotion network is not found in the list of networks for the host. The network can be found in the portgroup property of the HostVirtualNic data object.

CloneVM 1.x API Fails When Optional Parameters Are not Specified
If the CloneVM 1.x API operation is called against a compatibility feature in VirtualCenter 2.0, the call fails. This occurs when the optional parameters in the Sysprep or Adapter objects are not specified. To avoid this issue, specify all the optional parameters in the Sysprep and Adapter objects for the customization parameter of CloneVM.

1.x Clients Using the GetContents Operation Are Unable to See VMotion Networks
Clients created using the GetContents from the SDK 1.x do not see VMotion networks that were added to an ESX 3.0 Server. To find the VMotion networks, 1.x clients must get information from the Host Config NetworkInfo VirtualNic array, which contains the network that is based in a VMKernel VNic.

Miscellaneous Compatibility Issues

  • ESX Server 3.0 no longer supports 1.x disk modes.

  • If you attempt to add a host without valid credentials (user name and password), the host is not added.

  • The results from 1.x GetUpdate operations might include things for which no change has occurred.

  • The compatibility layer does not yet support RawDiskMappings.