Improved vSAN capacity usage reporting APIs in vSphere 8.0 Update 3

As with any new VMware software release, I always love geeking out and taking a look at the new APIs have been added and/or updated that can benefit our users. Having spent some time automating various aspects of vSAN, I came across a couple of new vSAN capacity usage reporting APIs (vSphere API & vSAN Management API) that were introduced in vSphere 8.0 Update 3 that I thought was worth mentioning.

While vSAN already had an existing capacity API by using the querySpaceUsage() method as part of the VsanSpaceReportSystem, it did not provide granular information about the raw storage capacity that was claimed by vSAN, whether that was for vSAN Original Storage Architecture (OSA) or vSAN Express Storage Architecture (ESA).

As part of the VsanVcClusterConfigSystem, there is now a new vSAN API called getClaimedCapacity() that will return the raw capacity in bytes for all claimed disks for vSAN OSA and/or ESA which is also useful for those looking to understand their tebibyte (TiB) usage, as that is also  unit of licensing for vSAN storage with the new VMware vSphere Foundation (VVF) and VMware Cloud Foundation (VCF) offers.

Per the vSAN API documentation, this new API differs in the following ways compared to the existing capacity API:

• First, it is based on raw capacity reported by the disk vendor, which includes any and all overhead reserved internally by vSAN
• Secondly, it reflects the cluster configuration, which is not affected by the runtime state of the cluster, such as disk health, host health, and network partition

Note: As of publishing this blog post the new vSAN Management API is currently only accessible using the vSAN Management 8.0 Update 3 SDK (Python, Java, .NET, Ruby or Perl) and not PowerCLI, as a newer version of PowerCLI is required to expose the new vSphere 8.0 Update 3 functionality, which has not been released yet.

To demonstrate the new vSAN API using vSAN Management SDK for Python, here is a small sample script vsan-claimed-capacity-sample.py that will provide the

python3 vsan-claimed-capacity-sample.py -s 192.168.30.3 -u 'administrator[at]vsphere.local' -p 'VMware1!' -c Supermicro-Cluster

Note: While creating the vSAN Management SDK for Python example script, I came to learn that by default, the SDK does NOT automatically use the latest API version when constructing the connection and you need to explicitly set the desired version, even if you want the latest. I suspect this might be due to internal testing purposes, but I still think the default behavior should just load the latest SDK version. In any case, there is a simple helper function as part of the vSAN Management SDK called GetLatestVmodlVersion() and this API will return the latest version and so you can simply retrieve the latest version and then pass that into the connection API as shown in the snippet below.

# Retrieve the latest API version
apiVersion = vsanapiutils.GetLatestVmodlVersion(args.host, int(args.port))

vcMos = vsanapiutils.GetVsanVcMos(si._stub, context=context, version=apiVersion)

Another useful vSAN API that was introduced in vSphere 8.0 Update 3 is in an existing ESXi host property called licensableResource as part of the vSphere API, which is stored as an enumeration for various licensable resources like number of CPU sockets, CPU cores, running VMs, etc. A new enum called vsanCapacity will be available for any vSAN-enabled ESXi host and will provide the total raw capacity in bytes for all claimed disks on an individual ESXi host.

Unlike the previous vSAN API, since this property is an enumeration, you can access using latest vSAN Management 8.0 Update 3 SDKs or the current release of PowerCLI.

Here is small PowerCLI snippet that will retrieve this new vsanCapacity property and provide both the raw value and the converted TiBs:

$results = @()
foreach ($vmhost in (Get-Cluster $cluster | Get-VMHost)) {
    $vsanCapacityInBytes = ($vmhost.ExtensionData.LicensableResource.Resource | where {$_.key -eq "vsanCapacity"}).Value
    $vsanCapacityInTibs = [math]::round($vsanCapacityInBytes/1Tb,3)

    $tmp = [pscustomobject]@{
        VMHost = $vmhost.Name
        VSANClaimedCapacityRaw = $vsanCapacityInBytes
        VSANClaimedCapacityTiB = $vsanCapacityInTibs
    }
    $results+=$tmp
}
$results