VMware Infrastructure SDK 2.0.1–SDK 1.x Compatibility NotesThe 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 ModeThe 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:
Enabling Compatibility ModeThe 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:
New FeaturesThe following features have been added to the compatibility layer since the previous release:
LimitationsThere 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 Server1.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 PutUpdatesPutUpdates Limitations PutUpdates operations have the following limitations:
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 StatisticsLimitations 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 EventsLimit 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. SecurityUsing 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. VMotionVMotion Configuration Requirements
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 MachinesCloneVM 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 SupportESX 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. AutostartSetting 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 IssuesDatastoreInfo 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 |