VMware Virtual Infrastructure SDK Release Notes for VMware VirtualCenter 2.0

What's in These Release Notes

These release notes cover the following topics:

Changes Since the Previous Virtual Infrastructure SDK (VirtualCenter 1.2) Release

  • This release includes two new manuals. The Virtual Infrastructure SDK Getting Started Guide introduces you to the new concepts and features in SDK 2.0. The Virtual Infrastructure SDK Porting Guide illustrates how to port legacy SDK 1.x client applications for use with the 2.0 Web service.
  • The Web service is now available on both the VirtualCenter Server and on individual ESX Server hosts. Most of the APIs supported on VirtualCenter are also supported on an ESX Server host (through the host agent), with the exception of a few methods, such as VMotion, which can only be used through VirtualCenter.
  • ESX Server host configuration through the VMware Management Interface can now be accessed programmatically at ESX Server 3.0 or at VirtualCenter 2.0.
  • All of the new features in ESX Server 3.0 and VirtualCenter 2.0 are available through the Web service.
  • Backwards compatibility with VirtualCenter 1.x Web Service is supported. For known issues, see Backwards Compatibility Issues with SDK 1.x.
  • You can create a customized inventory model for hosts and virtual machines, and 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.
  • We now have clusters (aggregations 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. Data can be retrieved either with blocking or non-blocking operations.
  • In the Virtual Infrastructure SDK, virtual machine customization is completely decoupled from the cloning operation.
  • VirtualCenter and SDK 2.0 provide higher speed performance statistics than in previous releases.
  • Through the Web service, it is now possible to define custom roles instead of 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 automatically scheduled and periodically rebalanced on hosts within a group, in order 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. Should a host fail, the HA software detects the failure and all the virtual machines running on the host are automatically 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 & memory snapshot
      • Multiple snapshots

For additional information about the Virtual Infrastructure SDK, refer to the VMware VirtualCenter release notes.

Features Not Fully Implemented

The following features are not fully implemented in this release:
  • Autostart settings
  • Built-in event collectors for virtual machines, hosts and tasks
  • Customization for cloning
  • Snapshot and Revert operations for virtual machines
  • The Consolidate operation
  • ESX Server 2.x compatibility

Managed Object Browser

The Managed Object Browser is a useful tool for working with the API. This tool enables you to browse the inventory of managed objects on either a VirtualCenter or a host server. You can access this tool with the following steps:
  1. Open an Internet Explorer window.
  2. Do one of the following:
    • Enter https://<server-name>/mob or
    • Enter https://<server-name> and click the Managed Object Browser link.

Enabling .NET Code Samples

To use the .NET samples included in the SDK installation, you must install the SSL certificate used by the VirtualCenter Server or ESX Server on the machine where the samples are run. You do this with the following procedure:
  1. Open an Internet Explorer window
  2. Enter https://<server-name>.
    A Security Alert dialog box is displayed.
  3. Click View Certificate.
    A Certificate dialog box is displayed.
  4. Click Install Certificate....
    The Certificate Import Wizard is displayed.
  5. Click Next.
  6. Click Next.
  7. Click Finish.
    A Security Warning dialog box is displayed.
  8. Click Yes to install the certificate.
    A Certificate Import Wizard dialog box is displayed.
  9. Click OK.
  10. Click OK in the Certificate dialog box.
  11. Click Yes in the Security Alert dialog box.
    The server home page is displayed in the browser.
Repeat these steps for each server (VirtualCenter or ESX Server) you want to use.

Long Startup Time for C# Samples
When you use VS.NET 2005 to compile and run the C# samples, program startup time can be long (about 30 seconds).

Enabling the Java Code Samples

In order to use the Java samples included in the Java SDK installation, you must do the following:
  1. Enable the .NET code samples as described in Enabling .NET Code Samples.
  2. Export the certificates as described in Exporting the Certificates.
  3. Install the SSL certificates as described in Installing the Certificates.

Exporting the Certificates
Once you have completed the steps in Enabling .NET Code Samples, perform the following steps:
  1. Create the following directory: C:\VMware-Certs.
  2. Open an Internet Explorer window.
  3. Select Internet Options from the Tools menu.
    The Internet Options dialog box is displayed.
  4. Select the Content tab.
  5. Click Certificates....
    The Certificates dialog box is displayed.
  6. Select the Trusted Root Certification Authorities tab.
  7. For each server you want to use:
    1. Find the server name.
      For ESX Servers this is the DNS name of the server.
    2. Select the certificate.
    3. Click Export.
      The Certificate Export Wizard is displayed.
    4. Click Next.
    5. Click Next.
    6. Enter a file name C:\VMware-Certs\<server-name>.cer.
      For example: C:\VMware-Certs\vc-server1.cer.
    7. Click Next.
    8. Click Finish.
      A Certificate Import Wizard dialog box is displayed.

    Repeat these steps for each server (VirtualCenter or ESX Server) you want to use. For a VirtualCenter Server you should export all certificates issued by VMware.

  8. Click Close to close the Certificates dialog box.
  9. Click Cancel to close the Internet Options dialog box.
Installing the Certificates
Once you have exported the certificates (as described in Exporting the Certificates), you must install them using the procedures in this section:

  1. Open a command prompt.
  2. Make sure the Java SDK tools are in your path.
  3. Change to the C:\VMware-Certs directory.
  4. For each certificate you wish to import:
    1. Enter the following command:
      keytool -import -file <certificate-filename> -alias <server-name> -keystore vmware.keystore.
      For example: keytool -import -file vc-server1.cer -alias vc-server1 -keystore vmware.keystore
    2. Enter a password for the keystore.
    3. Enter yes to import the certificate.
The Java samples will now work. The run.bat script for running the Java samples includes in the command line -Djavax.net.ssl.trustStore=c:\\VMware-Certs\\vmware.keystore. If you use a different file name or location for the keystore you need to update the run.bat file to reflect the location and name of the keystore you are using.

Creating Virtual Machine May Throw Incorrect Exceptions

Incorrect exceptions may be thrown when a virtual machine is created.

Incorrect exceptions thrown when creating a Virtual Machine
Create a virtual machine where the controller key is set to 0. InvalidDeviceSpec MissingController
Create a virtual machine where the device is a virtual disk but the capacity is not set. InvalidDeviceSpec com.vmware.vc.VimFault
Create a virtual machine where the device is an Ethernet card disk but the Mac address is not set. InvalidDeviceSpec No exception thrown. The createVM task succeeds.
Create a virtual machine where the device is a Virtual Controller but the bus number is not set. InvalidDeviceSpec No exception thrown. The createVM task succeeds.
Create a virtual machine where the device is virtual disk and the file operation is set to "replace". InvalidDeviceSpec com.vmware.vc.VimFault

CreateFilter Operation Throws 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.

Miscellaneous Issues

  • plaintext = false is not supported for the plaintext property of the CustomizationPassword data object.
  • When adding a device to a virtual machine, the key property of the VirtualDevice data object should be a negative integer to avoid conflicting with existing device keys. When adding multiple devices to a virtual machine on an ESX Server 2.5 host, the key must be unique. When adding multiple devices to a virtual machine on an ESX Server 3.0 host, the key property need not be unique.
  • The RescanHba and RescanAllHba operations on the HostStorageSystem managed object in the Virtual Infrastructure SDK return a boolean that indicates whether or not a new LUN was detected during the rescan. This boolean does not report properly whether or not a new LUN was detected during the rescan.
  • An error may 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 complete successfully this time.
  • When the findByDatastorePath is used to search for a virtual machine, a datastore name and path must both be provided. For example, providing [MyDatastore] /MyVirtualMachines as a path would return the expected results, whereas simply using [] /vmfs/volumes/MyDatastore/MyVirtualMachines/ would not. This is true even though an empty datastore name can be part of a valid datastore path.
  • CreateSnapshot_Task can only be successfully on a virtual machine associated with a host on an ESX 2.5 server if there is no existing snapshot. Furthermore, the virtual machine must be powered-on, have no spaces in its name, and only have disks in persistent mode. If there is an existing snapshot, RemoveSnapshot must be invoked before CreateSnapshot is used again. Otherwise a MultipleSnapshotsNotSupported fault will occur.
  • Code samples included in the SDK may not reflect the latest API implementations and best practices.
  • VmPerl scripting API and vmware-cmd does not support using symbolic links to refer to virtual machine configuration paths. Using symbolic links with these tools results in an error. To refer to virtual machines with these tools, use their absolute UUID-based path or their datastore style path. For example, a path that employs a UUID might look like /vmfs/volumes/19496567-9ac80b57/testVM/vm1.vmx and a path that employs a datastore style path might look like [mystorage]testVM/vm1.vmx. These configuration file path formats can be used anywhere a configuration path is required. UUID and datastore formats can be used interchangeably with no difference in behavior.
  • Improperly configured virtual machines or non-existent virtual machine configuration file paths may render vmware-cmd and the VmPerl scripting API unusable. This condition can be resolved by unregistering the virtual machine with the non-existant path or improper configuration.
  • Entering values for a managed object may produce unexpected indirectRemove calls. When an object property is not specified, 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 may expect that when an object is being created for the first time, that there is nothing to remove, but the indirectRemove call is being used to ensure the unset optional values have a null value.