PowerCLI 13.3, Scheduled Snapshot Removal, and Privilege Report

PowerCLI 13.3 was recently released (https://blogs.vmware.com/PowerCLI/2024/07/introducing-powercli-13-3.html). This release has a handful of really good features that we’ll explore below.

vSphere modules updated to vSphere 8.0U3

The vSphere modules in PowerCLI 13.3 have been updated to support vSphere 8.0U3 features. One of the 8.0U3 features I was interested in automating was the scheduled deletion of a virtual machine snapshot. In the vCenter Server UI > Developer Tools > Code capture could show us the code needed to schedule this new feature, for example:

$entity = New-Object VMware.Vim.ManagedObjectReference
$entity.Type = 'VirtualMachine'
$entity.Value = 'vm-39'
$spec = New-Object VMware.Vim.ScheduledTaskSpec
$spec.Scheduler = New-Object VMware.Vim.HourlyTaskScheduler
$spec.Scheduler.ActiveTime = [System.DateTime]::Parse('08/07/2024 17:02:00')
$spec.Scheduler.Interval = 1
$spec.Scheduler.Minute = 2
$spec.Notification = 'bwuchner@example.com'
$spec.Name = 'test-tc-09 - Hourly delete snapshot schedule'
$spec.Action = New-Object VMware.Vim.MethodAction
$spec.Action.Argument = New-Object VMware.Vim.MethodActionArgument[] (2)
$spec.Action.Argument[0] = New-Object VMware.Vim.MethodActionArgument
$spec.Action.Argument[1] = New-Object VMware.Vim.MethodActionArgument
$spec.Action.Argument[1].Value = New-Object VMware.Vim.SnapshotSelectionSpec
$spec.Action.Argument[1].Value.RetentionDays = 3
$spec.Action.Name = 'RemoveAllSnapshots_Task'
$spec.Description = ''
$spec.Enabled = $true
$_this = Get-View -Id 'ScheduledTaskManager-ScheduledTaskManager'
$_this.CreateScheduledTask($entity, $spec)

However, running the above with prior versions of PowerCLI (ie 13.2 or earlier) resulted in the following errors:

New-Object : Cannot find type [VMware.Vim.SnapshotSelectionSpec]: verify that the assembly containing this type is
loaded.
At line:1 char:34
+ ... ction.Argument[1].Value = New-Object VMware.Vim.SnapshotSelectionSpec
+                               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidType: (:) [New-Object], PSArgumentException
    + FullyQualifiedErrorId : TypeNotFound,Microsoft.PowerShell.Commands.NewObjectCommand


The property 'RetentionDays' cannot be found on this object. Verify that the property exists and can be set.
At line:1 char:1
+ $spec.Action.Argument[1].Value.RetentionDays = 3
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [], RuntimeException
    + FullyQualifiedErrorId : PropertyNotFound

However, with PowerCLI 13.3 this code works as expected and returns the managed object reference ID of the created schedule:

Type          Value
----          -----
ScheduledTask schedule-203

Looking in the vSphere Server UI we can also confirm that the scheduled task exists.

Get-VIPrivilegeReport

William Lam had previously posted about using the List Privilege Check API introduced in vSphere 8.0U1. This API would show the minimum required permissions to do specific actions, which is especially helpful if we want to use a service account with least privilege to run an automated task. PowerCLI 13.3 introduces the ability to easily call this API for a specific code block.

As an example, I used the following:

$pr = Get-VIPrivilegeReport {
# above code for scheduled deletion of a virtual machine snapshot
}

This created a $pr variable with a privilege report for all the privileges that would be required to schedule such a task. If we look at the $pr variable we’ll see:

EntityId                 Principal    Privilege                           Server
--------                 ---------    ---------                           ------
vim.Folder-group-d1      bwuchner@lab System.Read                         vc3
vim.Folder-group-d1      bwuchner@lab System.View                         vc3
vim.VirtualMachine-vm-39 bwuchner@lab ScheduledTask.Create                vc3
vim.VirtualMachine-vm-39 bwuchner@lab System.Read                         vc3
vim.VirtualMachine-vm-39 bwuchner@lab VirtualMachine.State.RemoveSnapshot vc3

Using this list, we can see that in addition to the default Read/View access, our service account will need ScheduledTask.Create and VirtualMachine.State.RemoveSnapshot privileges in our custom role.

Combining code capture, PowerCLI 13.3, and Get-VIPrivilegeReport can provide an experience that is much easier than the trial and error approach from the past.