vSphere Management SDK 8.0 Update 3 | 25 June 2024 | Build on developer.broadcom.com
For VMware Cloud Foundation and vSphere
Check back for additions and updates to these release notes, marked New.

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. In vSphere 8 update releases, applications can communicate in JSON also, which enhances interoperability with vSphere Automation APIs.

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

VI/JSON protocol added to Web Services API. Starting with vSphere 8.0 U1, 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. Further improvements were made for vSphere 8.0 U2 and U3.

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

Java 11 and beyond. The SDK stubs and samples are compatible with JDK 8 and above. Starting with JDK 11, java.xml.ws (JAX-WS) and the related technologies SAAJ, Web Services Metadata, and java.xml.bind (JAXB) are not bundled with the JDK. If you re-build and run sample code with JDK 11 and above, use the JAX-WS and JAXB libraries (version 3.0.2) bundled with the SDK under the lib folder.

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 this Release

Here are additions in 8.0 U3, as described in the vSphere Web Services API reference.

  • New Methods in Managed Objects
    • ProvisionServerPrivateKey added to HostCertificateManager: provisions an SSL private key for use before SSL certificate installation.
    • startDpuFailover added to HostNetworkSystem: launches DPU failover for a given distributed virtual switch.
    • HostQueryVirtualDiskUuid and HostSetVirtualDiskUuid_Task added to HostVStorageObjectManager: get and set the virtual disk UUID on host.
    • QueryVirtualDiskUuidEx and SetVirtualDiskUuidEx_Task added to VcenterVStorageObjectManager: get and set the virtual disk UUID on vCenter.
    • CreateCollectorWithInfoFilterForTasks added to TaskManager: create a specialized HistoryCollector to gather TaskInfo data objects.
  • New Data Objects
    • ClusterComputeResourceCryptoModePolicy: encryption mode policy for a cluster.
    • ClusterComputeResourceHostEvacuationInfo: evacuation actions for the host.
    • ClusterComputeResourceMaintenanceInfo: how hosts will be put into maintenance mode.
    • ClusterFtVmHostRuleInfo: control placement of VMs across two host groups.
    • ComputeResourceHostSeedSpec: seed host specification.
    • DVSFilterSpecConnecteeSpec: base class for Connectee filters, with DVSFilterSpecPnicConnecteeSpec for physical NIC, DVSFilterSpecVmConnecteeSpec for VM, and DVSFilterSpecVmknicConnecteeSpec for vmknic.
    • DVSFilterSpecVlanSpec: base class for VlanSpec filters, with DVSFilterSpecPvlanSpec for private vLAN, DVSFilterSpecTrunkVlanSpec for trunking, and DVSFilterSpecVlanIdSpec for regular Vlan.
    • DistributedVirtualSwitchHostMemberHostUplinkState: runtime state of uplink on host.
    • HostCpuSchedulerInfo: information about CPU scheduler.
    • HostPartialMaintenanceModeRuntimeInfo: status of partial maintenance mode.
    • IoFilterManagerSslTrust: SSL trust policy, either PinnedCertificate or UntrustedCertificate.
    • SnapshotSelectionSpec: specification for removing snapshots from VM.
    • TaskInfoFilterSpec: filter for retrieving task history.
    • TaskInfoFilterSpecFilterTaskResults: further specify task history results.
    • VmwareDistributedVirtualSwitchDpuFailoverPolicy: failover policy for DPU.
    • VmwareDistributedVirtualSwitchNetworkOffloadConfig: network offload config for DVS.
  • New Enumerated Types
    • HostCpuSchedulerInfoCpuSchedulerPolicyInfo: hyperthread security.
    • HostDistributedVirtualSwitchManagerFailoverReason: reasons for DPU failure.
    • HostDistributedVirtualSwitchManagerFailoverStage: stage of DPU failover.
    • HostGraphicsConfigVgpuMode: mixed or same size vGPU time slice.
    • HostGraphicsInfoVgpuMode: multi-instance or time-sliced virtual GPU.
    • HostPartialMaintenanceModeId: mode of quick patch partial maintenance mode.
    • HostPartialMaintenanceModeStatus: status modes of partial maintenance mode.
    • ScsiLunLunReservationStatus: whether SCSI LUN is reserved or not.
  • New Fault Type
    • FtVmHostRuleViolation: if powered on, VM would violate Fault Tolerance.

Finer-grained VM storage policy privileges introduced to benefit VMware Cloud customers. See William Lam's 06.26.2012 blog, Improved VM Storage Policy in vSphere 8.x.

Deprecated Features

  • External identity providers surpass the vSphere Management SDK.

    The vSphere Management SDK interfaces support neither multifactor authentication through OAuth 2.0, nor third-party providers such as Active Directory Federation Services (ADFS), Okta, or Microsoft Entra AD. Programmers can use the vSphere Automation API to support these authorization and authentication services. SAML tokens are valid for both APIs. Applications can obtain a SAML token by using either the Issue service of the vSphere Management API or the Authentication Token service of the vSphere Automation API. The Token service can also be used to convert a JSON Web Token (JWT) to a SAML token suitable for vCenter Server authentication.

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

Resolved Issues

  • Clone properly duplicates virtual machine FCD.

    Previously if a virtual machine contained FCD, CloneVM cloned it as a regular disk. As of 8.0 U2, CloneVM creates a duplicate FCD, as it should.

  • vSphere API returns true vClock for FCD.

    Cloud Native Storage (CNS) requires accurate virtual clock time, so as of 8.0 U2 the FCD API returns true vClock time in object vslmVClockInfo.

  • Linux virtual machines could not detect vNUMA topology.

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

Known Issues

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

  • With Active Directory, vCenter returns only 2500 user groups.

    When vCenter Server is integrated with Active Direcotry, method UserDirectory.RetrieveUserGroups returns only the first 2500 user groups, and no option exists to search for additional users beyond those 2500.

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

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.
check-circle-line exclamation-circle-line close-line
Scroll to top icon