VMware

VMware Infrastructure SDK 2.0.1–SDK 1.x Compatibility Notes

The SDK has been redesigned from the ground up for the 2.0 release. The new API is greatly expanded from the earlier version, including design improvements and a completely new set of function calls.

The VMware Infrastructure 1.x compatibility mode enables a client application developed for VirtualCenter 1.x and ESX Server 2.x to work, unchanged, with VirtualCenter 2 and ESX Server 3. By setting the compatibility mode to 1.x, a Web service supporting the 2.x version of the API can emulate the 1.x Web service: SOAP requests from a 1.x client are transparently mapped by the SDK 2 Web Service into corresponding SDK 2 operations. The 1.x client application continues to work as before.

Note: An SDK 1.x client using compatibility mode cannot use any new features available through SDK 2.

This document includes these topics:

Overview of Compatibility Mode

The VMware Infrastructure SDK 2.x is compatible with VMware SDK 1.x clients. In most cases, client applications that have been developed using the VMware Infrastructure API 1.x can work successfully with VirtualCenter 2.x.

For example, an API 1.x client application can perform these operations against a VirtualCenter 2 server:

  • Create and customize virtual machines
  • Discover virtual machines, host machines, and host storage resources
  • Migrate virtual machines using VMotion
  • Collect performance metrics

Enabling Compatibility Mode

The Web service implements the compatibility layer. VMware recommends enabling compatibility mode during the VirtualCenter installation process. You can enable 1.x compatibility mode on the specific port during the VirtualCenter installation, as follows:

  • During the VirtualCenter Server installation, a “VMware VirtualCenter Web Service” dialog displays, enabling you to configure the ports monitored by the Web service.
    • Select the checkbox to maintain backward compatibility with the 1.x Web service to use your 1.x clients with VirtualCenter 2.
  • Enabling compatibility mode after the VirtualCenter installation requires modifying the Windows registry. In general, modifying the Windows registry is not recommended, and VMware accepts no responsibility for issues that may arise as a result of modifying the Windows registry.
    To enable 1.x compatibility mode in the Windows registry on the VirtualCenter server:
    1. Backup the registry. See support.microsoft.com/default.aspx?scid=kb;EN-US;322756 for details.
    2. Run the registry editor. From the Windows Start menu, select Run and enter regedit to launch the Registry Editor.
    3. In the registry editor, open this key:
      HKLM\SOFTWARE\VMware, Inc.\VMware VirtualCenter
    4. Add the following string value (choose Edit > New > String Value):
      CompatibleWith1xWebService
    5. Set the string value to 1 (choose Edit > Modify).
    6. Exit the registry editor (by choosing Registry > Exit).

New Features

The following features have been added to the compatibility layer since the previous release:

  • A new flag has been added to the vpxd.cfg file to enable or disable collection of real time statistics on Performance Intervals. This is present in the ws1x section and is named perfRefreshEnabled. Stats collection is expensive, and performance stats refresh in 1.x backwards compatibility mode should be enabled only if you want to use real time statistics with GetContents or GetUpdates.
  • Creating virtual machines with client devices for CDROM/Floppy and E1000 NICs is now supported by the 1.x backwards compatibility layer.
  • PutUpdates operations to change CDROM/Floppy to use client devices and create E1000 network adapters is also supported. This works as it did in the 1.4 release of the SDK. This is supported on ESX Server 3 hosts only. ESX Server 2.5.x hosts do not support client devices or E1000 network adapters.

Limitations

There are a few compatibility limitations due to architectural differences in SDK 2 or ESX Server 3. These limitations are explained in this document. They are:

  • Connecting to ESX Server  Compatibility mode does not support direct connections to ESX Server 3.
  • GetUpdates and PutUpdates  Certain properties cannot be modified with PutUpdates. GetUpdates may return unnecessary update information.
  • Performance Statistics  Limits on performance intervals are different for ESX Server 3. Also, VirtualCenter 2 has extra statistics filtering options to configure.
  • Events  There are different limits on event collectors, and the event messages differ as well.
  • Security  ChangePermissions may fail in some cases. Credentials are required to add a host.
  • VMotion  VMotion configuration differs from SDK 1.x.
  • Cloning Virtual Machines  Some optional parameters must be supplied in compatibility mode.
  • Disk Support  ESX Server 3.0 supports different disk devices.
  • Autostart  Some restrictions Autostart configuration in compatibility mode has some restrictions.

Connecting to ESX Server

1.x clients using compatibility mode cannot connect directly to ESX Server 3. Compatibility mode is supported by VirtualCenter 2 only. Clients using compatibility mode can manage ESX Server 3 hosts through the VirtualCenter connection.

GetUpdates and PutUpdates

PutUpdates Limitations

PutUpdates operations have the following limitations:

  • PutUpdates operations for NetworkAdapter mode and devicename are not yet supported. If you create a virtual machine with a devicename and mode specified, these attributes are ignored.
  • 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.
  • Some PutUpdates operations were incorrectly documented in the SDK 1.x. The PutUpdates operation on datalocator does not work in the compatibility 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
    []/myisos/cdrom.iso
    Note: The cdrom.iso file need not be present when the CD is created.
  • A setting of "auto detect" for cd["key"]/hostdev of CD-ROM is converted to /dev/cdrom.

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

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

The results from 1.x GetUpdates operations might include things for which no change has occurred.
The client should be modified to compare the returned values with the previous known values before proceeding on the assumption that the properties have changed.

Performance Statistics

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. If your client creates performance intervals, you should check your code for odd intervals and round them to the nearest multiple of 60 seconds.

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 a more complete explanation of the performance interval restrictions in SDK 2, consult the VMware Infrastructure Programming Guide.

Filtered performance collectors do not persist.  Restarting the VirtualCenter Server erases the performance collectors. New performance intervals, however, do persist in compatibility mode, just as in SDK 1.x.

Statistics Filter Level.  In VirtualCenter, for performance reasons, not all statistics are gathered at the default setting. VirtualCenter 2 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.

Statistics reported in compatibility mode are reported only at level 4. To view performance statistics, you must configure vpxd manually to report level 4 statistics. You must do this in addition to turning on 1.x compatibility.

It is not necessary to change your client code. Once you have configured vpxd to report statistics at level 4, your application will perform the same in 1.x compatibility mode as it does when connected to a 1.x Web Service.

To configure the statistics level manually, 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 filter level settings using the VI Client.

For more information about the VI Client, see the VMware Infrastructure 3 Documentation page at:

http://www.vmware.com/support/pubs/vi_pubs.html

Events

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. By way of contrast, when you connect to the 1.x Web Service, the number of event collectors is limited only by server resources.

Event Translation.  In compatibility mode, events returned by SDK 2 Web Services are translated into 1.x events. The translation only covers parameters present in the 1.x events. New parameters in Events in the SDK 2 API are not available to clients using 1.x compatibility mode. However, there is no loss of information compared to 1.x servers.

Security

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. To deal with this, your client code should use GetUpdates to verify that the ChangePermissions operation succeeded.

Credentials Required To Add Hosts.  The SDK 1.x allowed host machines to be added to VirtualCenter management server without valid credentials. (Hosts were added in a disconnected state.)

The SDK 2 requires valid credentials to add a host machine. If your 1.x client relies on the old behavior, it will encounter a fault when attempting to add a host without valid credentials.

VMotion

VMotion Configuration Requirements

  • 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 API client application.
  • Specify the subnet property of the migrationInfo structure to enable migration in ESX Server 3.

Accessing VMotion Networks.  With ESX Server 2.5.x hosts, it was possible to create a virtual network adapter in a virtual machine and connect it to a VMotion network. This is not possible with ESX Server 3 because VMotion networks are implemented differently. When using compatibility mode with ESX Server 3 hosts, you can view a VMotion network on the host, but it is not accessible to virtual machine objects. Use the VI Client to configure VMotion networks with ESX Server 3.

Cloning Virtual Machines

CloneVM Optional Parameters Are Required in Compatibility Mode.  If you use the CloneVM 1.x operation with VirtualCenter 2, you must supply all parameters in the Sysprep and Adapter objects for the customization specification. Some parameters were optional in the 1.x SDK, but omitting the parameters in compatibility mode causes the operation to fail.

Disk Support

ESX Server 3 no longer supports 1.x disk modes. Consequently, 1.x compatibility mode cannot manage virtual machines using ESX Server 1.x disk modes. Virtual machines using old disk modes must be upgraded before they can be used with ESX Server 3.

The compatibility layer does not support ESX Server 2.0.1 raw disks.

ESX Server 2.5 and ESX Server 3 hosts do not support creating virtual machines with SCSI CD-ROMs.

ESX Server hosts do not support IDE hard disks.

Autostart

Setting Autostart Configuration on Virtual Machines on ESX Server 2.5.x Hosts Is Not Supported. VirtualCenter 1.x allowed autostart configuration through the 1.x Webservice API, but this is no longer supported in compatibility mode. If you need to configure autostart capability for ESX Server 2.5.x hosts using the VI SDK, you can upgrade those hosts to ESX Server 3. The SDK is able to configure autostart capability in 1.x compatibility mode for ESX Server 3 hosts.

Known Issues

DatastoreInfo Host Handle Array May Be Incomplete. The DatastoreInfo object contains the handles of hosts that use a particular datastore. Some of the hosts using the datastore may not be represented in the array.

Workaround: The information is available elsewhere in the API. If your client needs to maintain a list of all hosts using a datastore, you can get the host-to-datastore mapping information from the Host object. The Host object has a list of all the datastores names it uses in the HostInfo.datastore array. Using the HostInfo.datastore array for all hosts managed by VirtualCenter, populate a list in the client that maps datastores to hosts.

 

Last updated 29-Nov-2007 5:45 pm