VMware

VMware Infrastructure SDK Release Notes for VMware VirtualCenter 2.0

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. However, few methods, such as VMotion, can be used only 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.
  • Backward compatibility with VirtualCenter 1.x Web Service is supported. For known issues, see Compatibility Issues with SDK 1.x.
  • 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 has 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. You can retrieve data with blocking or nonblocking 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, you can now 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 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

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.
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 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.
To install the SSL certificate
  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

To use the Java samples included in the Java SDK installation, you must enable the samples.
To enable the samples
  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
After you have completed the steps in Enabling .NET Code Samples, you must export the certificates.
To export the certificates
  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
After you have exported the certificates (as described in Exporting the Certificates), you must install them.

To install the certificates
  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 want 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 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 a Virtual Machine Might Throw Incorrect Exceptions

Incorrect exceptions might be thrown when you create a virtual machine.

ConditionExpectedThrown
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.

New Guest SDK Available

The VMware Guest API allows software running in the guest operating system in a VMware ESX Server 3.0 virtual machine can use to collect certain data about the state and performance of the virtual machine. The Guest SDK package can be downloaded from VMware's API and Developer Materials page.

Miscellaneous Issues

  • plaintext = false is not supported for the plaintext property of the CustomizationPassword data object.
  • 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 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 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 complete successfully this time.
  • 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.
  • 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.
  • Code samples included in the SDK might not reflect the latest API implementations and best practices.
  • VmPerl scripting API and vmware-cmd do 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 paths or their datastore style paths. 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. You can use these configuration file path formats anywhere a configuration path is required. UUID and datastore formats are interchangeable with no difference in behavior.
  • Improperly configured virtual machines or nonexistent virtual machine configuration file paths might render vmware-cmd and the VmPerl scripting API unusable. You can resolve this condition by unregistering the virtual machine with the nonexistent path or improper configuration.
  • 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.