VMware Infrastructure SDK Release Notes for VMware VirtualCenter 2.0

These release notes cover the following topics:

• Changes Since the Previous VMware SDK (VirtualCenter 1.2) Release
• Features Not Fully Implemented
• Managed Object Browser
• Compatibility Issues with SDK 1.x
• Enabling .NET Code Samples
• Enabling the Java Code Samples
• Creating a Virtual Machine Might Throw Incorrect Exceptions
• CreateFilter Operation Throws a SystemError Fault
• New Guest SDK Available
• Miscellaneous Issues

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

• 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

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.

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.
    

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.

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.

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.

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