This site will be decommissioned on December 31st 2024. After that date content will be available at techdocs.broadcom.com.

 
Release date: 6 Oct 2020 | SDK build 16816462 on code.vmware.com
For vSphere 7.0 Update 1 | Last document update: 2 Dec 2020
Check again for additions and updates to these release notes.

Existing versions of the vSphere Management SDK were not compatible with Java 11. For procedures to use Java 11, see Compatibility Notices below.

Overview

The vSphere Management SDK contains the following packaged interfaces. All constitute Web services, in the sense that they communicate through a network endpoint in XML as defined by their respective Web Services Description Language (WSDL) definitions.

  • ESX Agent Manager (EAM) SDK
  • Storage Management Service (SMS) SDK
  • Storage Policy Based Management (SPBM) SDK.
  • Single Sign On (SSO) Client SDK
  • vSphere Web Services SDK
  • Virtual Storage Lifecycle Management (VSLM) SDK

The vSphere Web Services SDK is by far the most popular. It supports the development of applications that call the vSphere API to manage virtual machines and virtual infrastructure components such as datacenters, datastores, resource pools, and networks. Refer to the vSphere Web Services API Reference for managed objects, methods, and data structures in this release.

EAM offers support for vSphere solutions such as High Availability, NSX virtual networks, and IO Filters. For details, refer to the vSphere Solutions Manager, vServices, and ESX Agent Manager Release Notes.

SMS provides access to storage capabilities, associations, and space usage. SMS has its own in-memory database manager (the SMS cache) that periodically synchronizes data with the storage information provider database.

SPBM allows administrators to use and define storage profiles that help automate storage provisioning for virtual machines. Client applications can manipulate storage policies with the API, although usually this is done with the vSphere Client.

Since vSphere 5.1 SSO provides a security token service for authentication. Client applications call the API to obtain Security Assertion Markup Language (SAML) tokens for logging into vCenter Server or vCloud Suite. For multifactor authentication, programs must use the vSphere Automation SDK.

As of vSphere 7.0 VSLM is a new set of APIs to manage First Class Disk (FCD), also called Improved Virtual Disk. FCD is storage that exists independently of a virtual machine.

Distribution Kit

All the above SDK subsets are available on the code.vmware.com website as part of the vSphere Management SDK, a collection of related APIs. When you extract the contents of the ZIP archive, SDK subsets appear in these subdirectories:

VMware-vSphere-SDK-7.0.0-buildNumber.zip
    SDK
        eam
        sms-sdk
        spbm
        ssoclient
        vsphere-ws
	vslm

These vSphere Management SDKs provide documentation, libraries, and code examples needed for developers to build solutions integrated with the industry's leading virtualization platform.

Compatibility Notices

The SDK stubs and samples were compiled with JDK 1.7 and are compatible up to JDK 1.9. The latest Java LTS version, JDK 11, discontinued libraries supporting SOAP and JAX-WS. This means that, out of the box, the Web Services SDK is not compatible with JDK 11. To build and run sample code with JDK 11, developers must add missing libraries to the lib folder, as follows.

  1. Download the standalone jaxws-ri libraries from here:
    https://repo1.maven.org/maven2/com/sun/xml/ws/jaxws-ri/2.3.3/jaxws-ri-2.3.3.zip
  2. Extract the ZIP into a jaxws-ri folder and inside the folder, copy all JARs present in the lib directory.
  3. Paste those JARs into the lib folder of whichever module of the SDK you want to run samples from.
    For example, if you want to build and run samples from the vsphere-ws module of the SDK, paste the copied JARs into the vsphere-ws/java/JAXWS/lib/ directory of the SDK.
  4. Download samples-core from the Downloads section of the vSphere Management SDK 7.0 page.
  5. In the lib folder of the module where you want to run samples, overwrite the existing samples-core-1.0.0.jar with the samples-core-1.0.0.jar you just downloaded.
    For example, replace the existing vsphere-ws/java/JAXWS/lib/samples-core-1.0.0 with the downloaded one.
  6. To compile the sample programs, run build.bat -w on Windows or build.sh -w on Linux.
  7. As before, to run the sample programs type run.bat or run.sh with arguments.

New in This Release

New features in vSphere 7.0 Update 1:

  • For adding or moving a host into a cluster, the Host.Inventory.Modify privilege is required. For adding multiple hosts to a cluster, the Host.Inventory.Modify privilege is required on any host. On the parent datacenter, the Host.Inventory.Move and Host.Configuration.Maintenance privileges are also required.

These were new features for vSphere 7.0:

  • Virtual Storage Lifecycle Management SDK

    Virtual Storage Lifecycle Management (VSLM) is a set of APIs, new in vSphere 6.7 Update 3, to manage First Class Disk (FCD). The downloadable vSphere Management SDK includes VSLM WSDL, generated bindings, sample programs, and an API reference manual for VSLM, all in a folder parallel with SMS, SPBM, and vSphere Web Services. (See Distribution Kit)

  • Online vSphere Web Services API Reference

    The vSphere Management SDK contains the 7.0 vSphere Web Services API Reference, also online at code.vmware.com. It includes summaries of types added or changed for this release, and columns for interfaces supported in previous releases. Release 6.8.7 was for VMware Cloud (VMC) release M7. Release 6.9.1 was for VMC release M8. New features, changes, and improvements are summarized below.

  • New Managed Objects

    SiteInfoManager was added to control external site-related capabilities.
    HostAssignableHardwareManager was added to manage assignable hardware state of the ESXi host.

  • Enhanced Capabilities for Managed Objects

    HostStorageSystem can create and remove NVME over RDMA adapters and manage the NVME controller.
    CryptoManagerKmip can handle the KMS cluster and check if an active KMS exists in the cluster.
    CryptoManagerHost can disable encryption on a host, if the host was in crypto safe mode.
    HostDatastoreSystem can enable and disable VMDK support.
    ClusterComputeResource can set the encryption mode of a cluster.
    VcenterVStorageObjectManager can update the crypto state on a virtual storage object (FCD).
    HostSystem can retrieve information on free EPC memory of a host.

  • Namespace support for Kubernetes

    The new “namespace” property was added to Folder and ResourcePool. Namespace is a resource that divides-up cluster resources so that administrators can assign Kubernetes environments to specific development teams.

Deprecated Features

  • vSphere Automation identity providers surpass SSO interfaces

    The SSO interfaces are somewhat outmoded now that identity providers support Active Directory Federation Services, OAuth2, and OpenID Connect. Programmers can now use the vSphere Automation APIs for better support of these new authorization and authentication services.

  • Advice about old versions of Java

    Java programmers should use Oracle JDK 1.8 or OpenJDK 1.8 with this release. JDK 1.7 may be used for development, but it should not be used in a production environment because it does not support TLS 1.2. Stubs in the SDK were compiled with 1.7 but do not need rebuilding as the Developer Setup Guide formerly recommended. JDK 1.8 is backward compatible so the stubs continue to work.

  • See vSphere API Reference for deprecated interfaces

    Several properties and types defined for the API were deprecated in vSphere API 7.0. You can see all the objects and types with indicators showing when they were added or deprecated by clicking “API Versions Reference” in the VMware vSphere API Reference manual.

Known Issues

Currently known issues are as follows. For older issues, see the vSphere 6.7 Release Notes.

  • Client received SOAP fault from server: Signature is invalid.

    When running Web Services sample code with JDK 8 build 232 and later, the Java client receives an exception in the main thread saying “ws.fault.Server SOAPFaultException: Client received SOAP Fault from server: Signature is invalid.” See KB 81799 for workarounds.

  • HBA Rescan might require delay before proceeding.

    As larger storage devices are connected to the host bus adapter (HBA) in recent releases, HBA rescan could take longer to complete. As a workaround in these cases, developers can add a sleep() call before issuing subsequent I/O commands.

  • PropertyCollector notifications more sensitive in 6.7.

    Programs should not expect WaitForUpdatesEx to provide notification of server-side changes. This method is intended as a data synchronization mechanism. In some situations, server-side logic can report change sets that include unchanged properties. Client programs can safely apply values in these change sets, but some items might not represent changes to previous values. Between vSphere 6.5 and 6.7 a change threshold was made more sensitive, which could result in more frequent notifications from WaitForUpdatesEx.

  • Java GetVMFiles code mishandles special characters in VM names.

    Under JAXWS samples, the GetVMFiles.java program does not properly handle special characters of VM names passed in parameters.

  • SMS QueryService exceptions

    You might see SMS QueryService exceptions in the SMS log, such as “com.vmware.vim.sms.fault.QsQueryException” and “com.vmware.vim.query.client.exception.ValidationException: Got status code: 400.” The resolution is to restart vCenter Server's Appliance Management Service from the vSphere Client.

  • VM is created despite an invalid storage policy.

    Using the vSphere API, you can create a VM with a storage policy that is not in compliance with the associated storage capability, even if the subprofile constraint forceProvision is set to false. By contrast, the vSphere Client refuses to create the VM if the storage policy is not compliant.

  • Do not use VirtualMachine.Relocate to change VM storage profile.

    The VirtualMachine.Relocate method specifies a new storage profile for a virtual disk or VM without specifying either a new host or datastore. This is invalid to vCenter Server, which does not change the storage profile. Use VirtualMachine.Reconfigure to assign a new storage profile to a virtual disk /or VM.

  • Description of VASA alarms and system events is "Unknown Event ID".

    The vSphere Client can display VASA system events for the inventory root folder or the datastore associated with a storage device, but vCenter Server uses string "Unknown Event ID" for the event description instead of the message that the VASA provider specified.

Documentation Issues

  • Revised documentation for tracking Task completion.

    The Web Services SDK Programming Guide contains revised sections about PropertyCollector and polling for Task status. Furthermore, although VMware does not officially support Python bindings, the GitHub project for pyvmomi contains the relatively short task.py program that can help developers understand Task tracking algorithms.

  • VirtualMachine.CloneVM_Task method failure.

    The VMware vSphere API Reference does not document a limitation with regard to VirtualMachineCloneSpec:

    When VirtualMachine.CloneVM_Task fails, it produces the following error: “The specified delta disk format 'nativeFormat' is not supported.” The vCenter Server returns the error when you:
    (1) Create a VAAI NAS native linked clone VM that uses nativeFormat for the delta disk format VirtualMachineCloneSpec.location.disk.diskBackingInfo.deltaDiskFormat, or
    (2) Create a second-level clone from the first clone, and the disk for the second-level clone is on a different datastore. If you do not specify seSparseFormat or redoLogFormat for the second-level clone delta disk format, the clone operation fails.

    If you are using a VM clone with a native delta disk format, you must specify either seSparseFormat or redoLogFormat for any clones that you create from the original native clone when the second-level clone is on a different datastore.

  • The fault parameter is required for the SetTaskState method.

    The VMware vSphere API Reference does not document this limitation with regard to the SetTaskState method:

    If you specify an error state when you call the SetTaskState method, you must also specify the fault parameter in the calling sequence.

  • The seSparse virtual disk type is intended for internal use only.

    The documentation does not specify internal use only for VirtualDiskType.seSparse.

Resolved Issues

  • Setup Guide recommended the wrong Java version.

    The 6.7 vSphere Web Services SDK Setup Guide stated that JDK 1.7 was the recommended version of Java. The correct version is JDK 1.9 for production installations. Lacking TLS 1.2 support, JDK 1.7 is suitable only for development installations.

  • Setup Guide gave incorrect advice about rebuilding sample code.

    The 6.7 vSphere Web Services SDK Setup Guide advised users to recompile the sample programs and stub files in the SDK when running a version of Java other than 1.7. That advice was incorrect. The SDK files were compiled with JDK 1.7, but they are fully compatible with Java 1.9. Advice was updated for the 7.0 Setup Guide.

check-circle-line exclamation-circle-line close-line
Scroll to top icon