vSphere Management SDK 8.0 U1 Release Notes

Contents

• Overview
• Distribution Kit
• Compatibility Notices
• New in this Release
• Deprecated Features
• Known Issues
• Documentation Issues
• Resolved Issues

Overview

The vSphere Management SDK contains the following packaged interfaces. All are Web services, in the sense that they communicate through a network endpoint in XML as defined by their standard 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 data centers, 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, as well as 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.

Introduced in vSphere 7.0, VSLM is a set of APIs to manage First Class Disk (FCD), infrequently 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 developer.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-8.0.1-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

New JSON RPC protocol added to Web Services API. Starting with vSphere 8.0 Update 1, VMware adds support for a new HTTP and JSON-based wire protocol as an alternative to SOAP with XML. The new protocol is described using the industry-standard OpenAPI specification version 3.0, (see SwaggerIO website) and can access the popular VIM APIs, described in the Web Services API Reference. See Chapter 4 of the Web Services SDK Programming Guide for more details.

.NET SDK was discontinued. As announced in August 2020 (KB 80144) vSphere Automation SDK for .NET was deprecated. The vSphere Management SDK for .NET was also deprecated in vSphere 7.0 U3d (P04) as outlined in KB 87965. C# sample programs in the SDK were deleted. Programmers can still write Java programs for vSphere Web Services, or generate .NET bindings using WSDLs published in the SDK and using .NET libraries.

JDK 11. The SDK stubs and samples are compatible with JDK 8 and above. Starting with JDK 11, SOAP and JAX-WS libraries are no longer supported. Therefore, to build and run sample code, you can make use of the JAXWS-RI libraries bundled in the SDK libs folder

New in this Release

New 8.0 U1 features, further described in the Web Services API reference:

• New Methods in Managed Objects
  • GetCryptoKeyStatus in CryptoManagerHost
  • SetKeyCustomAttributes in CryptoManagerKmip
  • IncreaseDirectorySize and QueryDirectoryInfo in DatastoreNamespaceManager
  • RetrieveCertificateInfoList in HostCertificateManager
  • property complianceCheckTime in managed object HostProfile
• New Data Objects
  • CryptoManagerHostKeyStatus
  • CryptoManagerKmipCertSignRequest
  • CryptoManagerKmipCustomAttributeSpec
  • DatastoreNamespaceManagerDirectoryInfo
  • HostCertificateManagerCertificateSpec
  • HostTpmBootCompleteEventDetails
  • VimVasaProviderVirtualHostConfig
• New Enumerated Types
  • CryptoManagerHostKeyManagementType
  • DeviceProtocol
  • HostCertificateManagerCertificateKind

Important features in previous releases:

• Namespace support for Kubernetes. In vSphere 7.0 U3, the “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 developers or development teams.
• The Web Services SDK includes new JAX-WS and JAXB libraries so you don't need to download them separately.
• Sticky bit for ESXi configuration files has been replaced by use of esxcli configuration settings.
• HTTP PUT access to host files was discontinued for security reasons. GET access is still allowed.

Deprecated Features

• vSphere Automation identity providers surpass SSO interfaces

  SSO interfaces support neither multifactor authentication, nor third party providers such as Active Directory Federation Services (ADFS), OAuth2, Okta, or OpenID Connect. Programmers can use the vSphere Automation APIs to support these authorization and authentication services. SAML tokens are valid for both APIs. Applications can either use LoginByToken with SOAP-based SSO, or use the vSphere Automation API token service to exchange a JSON Web Token (JWT) for a SAML token.

• Use of TLS in old versions of Java

  Java programmers should use Java 11 or possibly later versions. 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.

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

• Vulnerablity in the SDK.

  The vSphere Management SDK ships woodstox-core as a transitive dependency from jaxws-ri. Woodstox-core has CVE-2022-40152 vulnerability making the SDK vulnerable. See KB 93638 for workarounds.

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:

• 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) may become unresponsive.

Known Issues in Documentation

• Revised documentation for tracking Task completion.

  The 7.0 Web Services SDK Programming Guide contained 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

• Linux virtual machines could not detect vNUMA topology.

  The vSphere API was extended to configure and query vNUMA enablement for HotAdd.

• Various USB issues fixed.

  USB 3.2 Gen 2x2 devices work and report the corrected speed when connected to USB 3.2 Gen 2x2 root or external hub. USB 3.2 device passthrough to virtual machines also works.

• Guest customization custom script enhancements.

  Increased the size limit to 64KB in software, which also applies to vCD and the API.