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:
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"
Thanks for the comment!