WilliamLam.com

  • About
    • About
    • Privacy
  • VMware Cloud Foundation
  • VKS
  • Homelab
    • Resources
    • Nested Virtualization
  • VMware Nostalgia
  • Apple
You are here: Home / Automation / Exploring the new vSAN Data Protection API in vSphere 8.0 Update 3

Exploring the new vSAN Data Protection API in vSphere 8.0 Update 3

07.08.2024 by William Lam // Leave a Comment

I have been spending some time with the new vSAN Data Protection (DP) capability that was just introduced with the latest vSphere 8.0 Update 3 release and if you are interested in what you can do with this new functionality, Duncan Epping has recently published a blog post on this exact topic that you should check out!

While the new vSAN DP capability can easily be consumed using the new vSphere UI plugin, it can be even more powerful with automation and I was interested in learning more about the vSAN DP API and how administrators can consume it.

Today, the vSAN DP (REST) API endpoint is part of the vSAN DP Virtual Appliance, which must be deployed access both the vSAN DP vSphere UI plugin and vSAN DP API. Since the vSAN DP API is available as a separate API endpoint, to authenticate you will need to request a SAML token from the vCenter Single Sign-On (SSO) service. There are currently some issues with the vSAN DP API documentation and once that is available, which I will linked, you will find more information about requesting a token along with all the available methods.

There are currently two vSAN DP SDKs (Software Development Kits) that are available for users to access the vSAN DP API:

  • vSAN DP SDK for Python
  • vSAN DP SDK for Java

Most administrators prefer PowerCLI, so I was surprised there was not vSAN DP SDK for PowerShell and I figured as part of my exploration of the new vSAN DP API, I would create a new Community PowerShell Module for some of the vSAN DP API functionality called VMware.Community.VSANDP, which contains the following functions:

  • Connect-VSANDataProtection
  • Get-VSANDataProtectionVersion
  • Get-VSANDataProtectionGroup
  • New-VSANDataProtectionGroup
  • Remove-VSANDataProtectionGroup
  • Get-VSANDataProtectionGroupSnapshot
  • New-VSANDataProtectionGroupSnapshot
  • Remove-VSANDataProtectionGroupSnapshot

To get started, follow the directions to install the vSAN DP PowerShell Module and take a look at the examples below on the use cases currently covered by the module:

Step 1 - Install the vSAN DP PowerShell Module from PS Gallery by running the following command:

Install-Module VMware.Community.VSANDP

Step 2 - Next, we need to import the vSAN DP PowerShell Module to be able to use the functions by running the following command:

Import-Module VMware.Community.VSANDP

Using the Get-Command cmdlet, we can see the five different functions that are available in the module:

Get-Command -Module VMware.Community.VSANDP

Connect to vSAN DP API:

Before we can run the vSAN DP functions, we need to establish a connection to the vSAN DP API which includes requesting a SAML token that can be used to authenticate into the vSAN DP API. I will not bore you with the details but if you want to see how that is done, you can take a look at the source code. In addition,

$plainTextPassword = "VMware1!"
$secureString = ConvertTo-SecureString -String $plainTextPassword -AsPlainText

Connect-VIServer -Server vcsa.primp-industries.local -User administrator[at]vsphere.local -Password $plainTextPassword

Connect-VSANDataProtection -Server "snap.primp-industries.local" -VCenter "vcsa.primp-industries.local" -SSOUser administrator[at]vsphere.local -SSOPassword $secureString

After a successful connection to the vSAN DP API, a global variable called $global:vsanDPConnection is created that contains the vSAN API endpoint along with the requested vCenter SSO SAML Token that we can use to authenticate into the vSAN DP API.

To confirm everything is working as expected, we can use the Get-VSANDataProtectionVersion function to return the version of the vSAN API by running the following:

Get-VSANDataProtectionVersion

Create Protection Group:

There are several different ways to create a vSAN DP Group depending on your requirements.

In this example, we are creating a vSAN DP Group that contains specific VMs and a single protection policy using the New-VSANDataProtectionGroup function:

New-VSANDataProtectionGroup -ClusterName "vSAN-ESA-Cluster" -Name "VSAN-DP-1" -VMNames @("photon-01") -PolicyName "Daily" -PolicyScheduleInterval 30 -PolicyScheduleUnit MINUTE -PolicyRetentionInterval 1 -PolicyRetentionUnit HOUR

In this example, we are creating a vSAN DP Group that uses a VM name pattern rather than specific VMs and a single protection policy using the New-VSANDataProtectionGroup function:

New-VSANDataProtectionGroup -ClusterName "vSAN-ESA-Cluster" -Name "VSAN-DP-2" -VMPatterns @("photon-02*","photon-03*") -PolicyName "Weekly" -PolicyScheduleInterval 1 -PolicyScheduleUnit WEEK -PolicyRetentionInterval 1 -PolicyRetentionUnit MONTH -Troubleshoot

Note: You will notice the output above is more verbose than the prior and that is because of the -Troubleshoot parameter which includes the specific vSAN API endpoint, method and associated body request which can be useful not only from a troubleshooting standpoint but also useful for anyone interested in the specific vSAN DP API used, which can easily be consumed using other scripting and/or programming languages.

In this last example, we are creating a vSAN DP Group that is configured with multiple protection policies and unlike the prior examples, we are using the -PolicySpec parameter rather than -PolicySchedule* and -PolicyRetention* options which are designed for single protection policy only.

$policySpec = @(
    @{
        "Name" = "Daily"
        "Schedule" = @{
            "Interval" = 30
            "Unit" = "MINUTE"
        }
        "Retention" = @{
            "Interval" = 1
            "Unit" = "DAY"
        }
    }
    @{
        "Name" = "Weekly"
        "Schedule" = @{
            "Interval" = 1
            "Unit" = "WEEK"
        }
        "Retention" = @{
            "Interval" = 1
            "Unit" = "MONTH"
        }
    }
    @{
        "Name" = "Monthly"
        "Schedule" = @{
            "Interval" = 1
            "Unit" = "MONTH"
        }
        "Retention" = @{
            "Interval" = 6
            "Unit" = "MONTH"
        }
    }
)

New-VSANDataProtectionGroup -ClusterName "vSAN-ESA-Cluster" -Name "VSAN-DP-3" -VMPatterns @("photon-04*") -PolicySpec $policySpec

As expected, you can mix-match the different options when creating a new vSAN DP Group and get the same flexibility as the vSphere UI plugin for vSAN DP.

If we look at your specific vSAN ESA Cluster in the vSphere UI by navigating to Configure->vSAN->Data Protection->Protection Groups, we now should see the new vSAN DP Groups that we had just created.

List Protection Group

We can view all vSAN DP Groups that were created using either the vSphere UI and/or vSAN DP API by using the Get-VSANDataProtectionGroup function and the name of the vSAN ESA Cluster as shown in the example below:

Get-VSANDataProtectionGroup -ClusterName "vSAN-ESA-Cluster"

Note: By default, the vSAN DP API only returns the Managed Object Reference (MoRef) ID of a VM (e.g. vm-1234), which is not very user friendly and the primary reason I need a connection to the vSphere API using (Connect-VIServer) is that in my function, I automatically convert the MoRef ID into friendly VM name as you can see in the screenshot above.

Delete Protection Group

To delete a vSAN DP Group, we simply use the Remove-VSANDataProtectionGroup function along with the name of the vSAN ESA Cluster and the vSAN DP Group:

Remove-VSANDataProtectionGroup -ClusterName "vSAN-ESA-Cluster" -Name "VSAN-DP-2"

When you delete vSAN DP Group using the vSphere UI plugin, you are prompted with two options for the deletion, preserve snapshots OR delete all snapshots. The Remove-VSANDataProtectionGroup also defaults to the same vSphere UI behavior by preserving the snapshots, but if you wish to delete all snapshots, simply add the -DeleteAllSnapshots parameter as shown in example below:

Remove-VSANDataProtectionGroup -ClusterName "vSAN-ESA-Cluster" -Name "VSAN-DP-2" -DeleteAllSnapshots $true

List Protection Group Snapshot

We can view all snapshots for a vSAN DP Group by using the Get-VSANDataProtectionGroupSnapshot function and the name of the vSAN ESA Cluster and vSAN DP Group as shown in the example below:

Get-VSANDataProtectionGroupSnapshot -ClusterName "vSAN-ESA-Cluster" -ProtectionGroupName "VSAN-DP-1"

Create Protection Group Snapshot

To create a manual snapshot for vSAN DP Group by using the New-VSANDataProtectionGroupSnapshot function and the name of the snapshot, retention policy and the name of the vSAN ESA Cluster and vSAN DP Group as shown in the example below:

New-VSANDataProtectionGroupSnapshot -ClusterName "vSAN-ESA-Cluster" -ProtectionGroupName "VSAN-DP-1" -Name "My-Snapshot" -RetentionInterval 10 -RetentionUnit DAY

Delete Protection Group Snapshot

To create a manual snapshot for vSAN DP Group by using the Remove-VSANDataProtectionGroupSnapshot function and the name of the snapshot and the name of the vSAN ESA Cluster and vSAN DP Group as shown in the example below:

Remove-VSANDataProtectionGroupSnapshot -ClusterName "vSAN-ESA-Cluster" -ProtectionGroupName "VSAN-DP-1" -Name "My-Snapshot"

More from my site

  • Improved vSAN capacity usage reporting APIs in vSphere 8.0 Update 3
  • Automating deployment of vSAN Data Protection OVA with PowerCLI
  • Programmatically accessing the Broadcom Compatibility Guide (BCG)
  • Enable TRIM/UNMAP from Nested vSAN OSA/ESA to physical vSAN OSA
  • Enhancements to VMware Cloud Foundation (VCF) & vSphere Automated Lab Deployment Scripts

Categories // Automation, PowerCLI, VSAN Tags // VSAN, vSphere 8.0 Update 3

Thanks for the comment!Cancel reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Search

Thank Author

Author

William is Distinguished Platform Engineering Architect in the VMware Cloud Foundation (VCF) Division at Broadcom. His primary focus is helping customers and partners build, run and operate a modern Private Cloud using the VMware Cloud Foundation (VCF) platform.

Connect

  • Bluesky
  • Email
  • GitHub
  • LinkedIn
  • Mastodon
  • Reddit
  • RSS
  • Twitter
  • Vimeo

Recent

  • VMUG Connect 2025 - Minimal VMware Cloud Foundation (VCF) 5.x in a Box  05/15/2025
  • Programmatically accessing the Broadcom Compatibility Guide (BCG) 05/06/2025
  • Quick Tip - Validating Broadcom Download Token  05/01/2025
  • Supported chipsets for the USB Network Native Driver for ESXi Fling 04/23/2025
  • vCenter Identity Federation with Authelia 04/16/2025

Advertisment

Privacy & Cookies: This site uses cookies. By continuing to use this website, you agree to their use.
To find out more, including how to control cookies, see here: Cookie Policy

Copyright WilliamLam.com © 2025

 

Loading Comments...