VMware Infrastructure (VI) SDK 2.0.1 Release Notes

These release notes support VirtualCenter 2.x and ESX Server 3.x. The release notes cover the following topics:

Changes Since the Previous SDK (VirtualCenter 2.0) Release

  • The performance counters include several new counters. In addition, the information for some counters has changed. For details, see New and Changed Performance Counters.
  • You can invoke operations from the Managed Object Browser. For details, see Managed Object Browser.
  • The VMware Infrastructure API Reference Guide has been updated and clarified.
  • The sample library that accompanies the product contains additional samples. Some of these samples have performance, style, and other issues. In particular, the Microsoft .NET sample (that uses the VimWrap library) is best avoided.

For more information about VirtualCenter and VMware Infrastructure, see the VMware VirtualCenter release notes.

Changes Since the VirtualCenter 1.2 Release

  • This release includes two new manuals: The VMware Infrastructure SDK Getting Started Guide, which introduces some basic concepts and features in SDK 2.0; and the VMware Infrastructure SDK Porting Guide, which tells you how to port legacy SDK 1.x client applications for use with the 2.0 Web service.
  • The Web service is available on VirtualCenter Server, as well as on individual ESX Server 3.x hosts. Most of the APIs supported on VirtualCenter are also supported on an ESX Server host. However, some APIs—for example, migrating virtual machines via VMotion—are available only to hosts managed by VirtualCenter Server.
  • The Web service supports a “compatibility mode,&3148; for backward-compatibility with client applications developed for VirtualCenter 1.x Web Service. For known issues, see Compatibility Issues with SDK 1.x.
  • ESX Server host configuration through the VMware Management Interface can now be accessed programmatically at ESX Server 3.0 or at VirtualCenter 2.0. However, not all properties of ESX Server 3.x hosts are available on ESX Server 2.x hosts. Attempting to obtain information about unsupported properties or methods result in “not supported” message. See Known Issues, below.
  • All of the new features in ESX Server 3.0 and VirtualCenter 2.0 are available through the Web service.
  • You can create a customized inventory model for hosts and virtual machines, and you can create multiple nested folders in the inventory hierarchy. Clients can now view hosts, virtual machines, clusters, resource pools, datacenters, networks, and datastores in the same inventory.
  • VMware now supports clustering (aggregation of compute resources from multiple hosts) and resource pools (logical containers of resources).
  • The PropertyCollector interface supports a powerful filtering mechanism that enables you to find and monitor specific data without retrieving all the available updates. You can retrieve data using blocking or nonblocking operations.
  • The VMware Infrastructure API, virtual machine customization is completely decoupled from the cloning operation.
  • VirtualCenter and SDK 2.0 returns performance statistics faster than in previous releases.
  • Through the Web service, you can now define custom roles in addition to using predefined, fixed roles.
  • Through VMware DRS, clients can now specify groups of virtual machines and their resource entitlements (minimum, maximum, and shares). These virtual machines are then scheduled and periodically rebalanced on hosts within a group, to honor the resource entitlements. DRS responds to changes in the number of virtual machines and hosts and continues to enforce the resource entitlements across the group.
  • Through VMware HA, clients can automatically improve the availability of virtual machines on hosts participating in the cluster. If a host fails, the HA software detects the failure. All the virtual machines running on the host are restarted on other hosts in a group, provided that they have available capacity for the additional virtual machines.
  • Snapshot behavior has changed significantly since the last release:
    • For ESX Server 2.x on SDK Server 1.x:
      • Disk snapshot only
      • Single snapshot
    • For ESX Server 3.0 on SDK 2.0:
      • Disk and memory snapshot
      • Multiple snapshots

New or Changed Performance Counters

The performance counters include four new counters:

GroupCounter NameUnitDescriptionStatistic TypeRollup TypeEntity
disk commands number The number of disk commands issued in the performance interval. delta summation host, virtual machine (per disk instance only)
disk commandsAborted number The number of disk commands aborted in the performance interval. delta summation host, virtual machine (per disk instance only)
disk busResets number The number of bus resets in the performance interval. delta summation host, virtual machine (per disk instance only)
mem sysUsage KB Amount of memory used by the vmKernel. absolute average, maximum, minimum host
cpu idle millisecond CPU time that is idle. delta summation host (per CPU instance only)

In addition to these new counters, the host entity is added to the list of entities for the swapin and swapout counters in the mem group. The entities for these counters now include hosts, virtual machines, and resource pools.

Managed Object Browser

The Managed Object Browser is a web-based tool for working with the API. This tool enables you to browse managed objects on VirtualCenter Server and ESX Server systems.

To use the Managed Object Browser:

  1. Open an Internet Explorer window.
  2. Do one of the following:
    • Enter https://<server-name>/mob
    • Enter https://<server-name>, and click the Browse objects managed by VirtualCenter link.

See KB 568529 for more information about using the Managed Object Browser to invoke operations.

New Guest SDK Available

The VMware Guest API enables software running in the guest operating system (on a VMware ESX Server 3.0 virtual machine) to collect data about the state and performance of the virtual machine. For more information, and to download the VMware Guest SDK, visit the VMware Guest SDK page.

Known Issues

This release of the VI SDK has the following issues.

Sample Code, Performance Issues

  • Sample Code May Have Limited Scope and Purpose. The sample applications included in the SDK do not always use the most recent APIs. Furthermore, some of the samples do not follow best practices.

  • C# “Wrapper” Samples Perform Poorly. The C# wrapper samples (located in the \samples_2_0\DotNet\wrapper sub-directory of the SDK 2.0.1 package) make a round trip to the server for every method invocation, which can result in unacceptably poor performance. For best results, do not use these samples, and be careful when using this particular design pattern. For applications that require frequent access to a large number of objects or properties, use the PropertyCollector managed object type, which retrieves in batch mode, thus reducing round trips to the server. See Appendix A in the Getting Started Guide for a PropertyCollector tutorial.

  • The C# (.NET) Samples Have Performance Issues Related to .NET Serialization. Generating the serialization code for the C# samples can take a long time. See KB 87402 for more information, and to obtain a patch for the Microsoft Visual Studio 2005 environment.

  • Performance Issue (for VI SDK 2.0) with JDK Versions Prior to JDK 1.5.0_08. Using JDKs older than JDK 1.5.0_08 results in a significant performance degradation, when obtaining a Managed Object Reference to a virtual machine. See KB 2983901 for more information.

Errors or Exceptions Issues

  • Creating a Virtual Machine May Throw Incorrect Exceptions. Incorrect exceptions might be thrown when you create a virtual machine, as shown in this table. The table lists error condition category, the exception that is expected to be thrown, and the exception actually thrown.

    Create a virtual machine with the controller key is set to 0. InvalidDeviceSpec MissingController
    Create a virtual machine with a device that is a virtual disk but the capacity is not set. InvalidDeviceSpec com.vmware.vc.VimFault
    Create a virtual machine with a device that is an Ethernet card disk but the Mac address is not set. InvalidDeviceSpec No exception thrown. The createVM task succeeds.
    Create a virtual machine with a device that is a Virtual Controller but the bus number is not set. InvalidDeviceSpec No exception thrown. The createVM task succeeds.
    Create a virtual machine with a device that is a virtual disk and the file operation is set to “replace.” InvalidDeviceSpec com.vmware.vc.VimFault

  • CreateFilter Operation Throws a SystemError Exception  The CreateFilter operation throws a SystemError fault if its PropertyFilterSpec contains a PropertySpec with an incorrect property path in the pathSet property. An incorrect path is one that is not defined for the managed object type specified by the PropertySpec’s type property. You can correct the problem by fixing the incorrect PropertySpec.

API or Object Model Issues

  • Client applications must access an ESX Server 2.x host system through a VirtualCenter Server 2.x system. In addition, ESX Server 3 introduces new API and object types that are not fully supported on ESX Server 2.x systems. Any non-supported features return “not supported.” For example, host configuration (HostSystem.ConfigManager.ConfigInfo) and related properties, such as multipathInfo, is not supported on ESX Server 2.x systems.
  • CustomizationPassword data object does not support “false” as the value for the plaintext property. Do not set plaintext = false.
  • When you add a device to a virtual machine, use a negative integer for the key property of the VirtualDevice data object to avoid conflicts with existing device keys. When adding multiple devices to a virtual machine, requirements for uniqueness vary by version number, as follows:
    • ESX Server 2.5 hosts require a unique key for each device.
    • ESX Server 3.0 hosts do not require a unique key.
  • The RescanHba and RescanAllHba operations on the HostStorageSystem managed object in the VMware Infrastructure SDK return a Boolean value that indicates whether a new LUN was detected during the rescan. This Boolean does not report properly whether a new LUN was detected during the rescan.
  • An error might result if you add a host to a VMware HA cluster from which the host had been removed previously. As a workaround:
    1. Disable HA on the cluster using ReconfigureCluster().
    2. Let all the "Config/Unconfigure HA on host" tasks complete.
    3. Re-enable HA on the cluster using ReconfigureCluster().
    4. Let all the "Config/Unconfigure HA on host" tasks complete.
    The tasks should now complete successfully.
  • When using findByDatastorePath to search for a virtual machine, you must provide both a datastore name and path. For example, providing [MyDatastore]/MyVirtualMachines as a path returns the expected results, but simply using []/vmfs/volumes/MyDatastore/MyVirtualMachines/ does not. This is true even though an empty datastore name can be part of a valid datastore path. An empty datastore name can be part of a valid datastore path only if its host context is known, since an empty datastore name indicates the local path on a particular host.
  • A CreateSnapshot_task works on a virtual machine associated with a host on an ESX 2.5 server only if there is no existing snapshot. Furthermore, the virtual machine must be powered-on, have no spaces in its name, and have only disks in persistent mode. If there is an existing snapshot, RemoveSnapshot must be invoked before CreateSnapshot is used again. Otherwise a MultipleSnapshotsNotSupported fault occurs.
  • Entering values for a managed object might produce unexpected indirectRemove calls. When you do not specify an object property, the value for that property in the object is set to null. For example, this happens when a new managed object is created and optional values are left unspecified. Users might expect that when creating an object for the first time, there is nothing to remove, but the indirectRemove call is used to ensure that the unset optional values have a null value.


Last updated 18-December-2007 4:00 pm