Release date: 12 July 2022 | SDK build on developer.vmware.com For vSphere 7.0 Update 3f | Last document update: 16 Sept 2022 Check again for additions and updates to these release notes.

Older versions of the vSphere Management SDK were not compatible with Java 11. For advice on 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 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.

SSO provides a security token service for single sign-on 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.5-buildNumber.zip
    SDK
        eam
        sms-sdk
        spbm
        ssoclient
        vsphere-ws
	vslm

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

Compatibility Notices

As announced in the August 2020 deprecation notice (see KB 80144) the Web Services SDK for .NET will be discontinued in vSphere 8.0, and the distribution will not include C# sample programs.

Java 11. As of the 7.0 release, SDK stubs and samples are compiled with JDK 11 and compatible back to JDK 1.8. JDK 11 recently discontinued libraries supporting SOAP and JAX-WS. Consequently VMware provides the necessary JAX-WS libraries to run with JDK 11. To build and run sample code with JDK 11, JAX-WS and JAXB libraries are provided in the SDK lib folder.

New: Null pointer exception. Running vSphere Management SDK with Java 11 can result in NullPointerException when com.vmware.vim25#VimService() calls the javax.xml.ws.Service constructor. This is due to a known bug in < 3.0.1 versions of jaxws-ri. See KB 89346 for the resolution.

As previously documented, to compile the sample programs, run build.bat -w on Windows or build.sh -w on Linux. To run the sample programs type run.bat or run.sh with appropriate arguments.

New in Which Release

New features in vSphere 7.0 Update 3f:

• The updateHostCustomizations method is again public. The 7.0 U3 SDK release unfortunately did not include the vim.ProfileManager.updateHostCustomizations_Task method. Applications that used this API did not compile or work with the 7.0 U3 SDK. This method is restored in the vSphere Management SDK 7.0 Update 3f.
• Better compatibility of vim25 with SMS SDK. Historically, vim25 Java class files were copied in the SMS SDK jar. This introduced incompatibility issues with the existing vim25.jar and sms.jar files. To avoid this, build scripts are changed not to include vim25 Java class files in sms.jar. Applications using the SMS SDK must ensure vim25.jar is available in the classpath. This is demonstrated by the provided samples in the SMS SDK.

New features in vSphere 7.0 Update 3:

• In the ClusterComputeResource managed oject, new method GetSystemVMsRestrictedDatastores was introduced. In the DiagnosticManager managed oject, new method FetchAuditRecords was introduced. In the HostDataTimeSystem managed oject, new method TestTimeService was introduced. In the HostGraphicsManager managed object, new methods RetrieveVgpuDeviceInfo and RetrieveVgpuProfileInfo were introduced. In the HostStorageSystem managed object, new methods ConnectNvmeControllerEx_Task, DisconnectNvmeControllerEx_Task, CreateSoftwareAdapter, and RemoveSoftwareAdapter were introduced. See the 7.0U3 vSphere Web Services API reference for new data objects and enumerations.
• The Web Services SDK includes JAX-WS and JAXB libraries so you don't need to download them separately.
• HTTP PUT access to host files has been discontinued for security reasons. GET access is still allowed.
• Sticky bit for ESXi configuration files was deprecated in a previous release. Its functionality is replaced by esxcli configuration settings.

New features in vSphere 7.0 Update 2:

• In the HostVStorageObjectManager managed oject, new methods HostDeleteVStorageObjectEx_Task and HostUpdateVStorageObjectMetadataEx_Task were introduced. In the HttpNfcLease managed object, new method HttpNfcLeaseProbeUrls was introduced. In the VcenterVStorageObjectManager managed object, new methods DeleteVStorageObjectEx_Task and VCenterUpdateVStorageObjectMetadataEx_Task were introduced. See the 7.0U2 vSphere Web Services API reference for new data objects and enumerations.
• The 7.0 U2 SDK included the samples-core JAR file, which had to be separately downloaded for the previous release.
• A list of known VSLM (FCD) issues has been formulated for VMware Tanzu. See Known VSLM Issues below. FCD is the base technology for Cloud Native Storage (CNS) on Tanzu.

New features in vSphere 7.0 Update 1:

• In the VirtualMachine managed oject, new methods DropConnections and QueryConnections were introduced. See the 7.0U1 vSphere Web Services API reference for new data objects and enumerations.
• 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.

New SDK features in 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 instead 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 recent versions of Oracle JDK or OpenJDK. JDK 1.7 should not be used in a production environment because it does not support TLS 1.2. Stubs in the SDK were compiled with JDK 11 and do not need rebuilding. JDK 11 is backward compatible so the stubs should work back to JDK 1.8.

• 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 1.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 JAX-WS 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.

Known Issues in VSLM

VSLM interfaces control First Class Disk (FCD) and perform lifecycle operations for persistent volumes outside the lifecycle of a VM or Tanzu pod. Cloud Native Storage (CNS)is an important use case for FCD. These are some limitations of the current product:

• FCD supports NFS 3, but not NFS 4.x protocols.
• vCenter Server does not serialize operations on an FCD, so applications cannot perform simultaneous operations on the same FCD. Multithreading of long running operations such as clone, relocate, delete, retrieve, and so on can have unpredictable results. To avoid problems, perform complete operations in sequential order on a single FCD.
• FCD is not a managed object and has no global lock mechanism protecting multiple writes to one FCD. As a result, VSLM does not support multiple vCenter instances managing one FCD. If you require multiple vCenter instances with FCDs, you have two options: (1) multiple vCenter Server instances managing different datastores, or (2) multiple vCenter Server instances not operating on the same FCD.
• With FCD attached to a VM, the vCenter inventory is not cache consistent with the FCD global catalog. In other words, if your application connects to the API endpoint for VSLM, and also to another API endpoint such as vpxd or hostd, timing issues can result in database consistency issues. After writes, VMware recommends including a 30 second delay for synchronization of databases.
• When a system error causes a long queue into the FCD global catalog, FCD and Cloud Native Storage (CNS) become unresponsive. This (FCD scalability) will be fixed in the next update release.

Known Issues in Documentation

• 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 Developer's 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 Developer's 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.