Public/Stop-PrismVM.ps1
|
function Stop-PrismVM { <# .SYNOPSIS Turns off a VM, either by a forced power-off or by an ACPI shutdown. .DESCRIPTION Stops the Virtual Machine with the given external identifier. -Method AcpiShutdown (default) performs a collaborative shutdown through the ACPI support in the guest operating system. This maps to the "Shutdown the VM using ACPI" endpoint. -Method PowerOff forcibly shuts down the VM, equivalent to removing the power cable. This maps to the "Turn off a VM" / "Force power off" endpoint and may cause data loss if operations are in progress. Both are conditional operations: the v4 API requires the current ETag of the VM (supplied as an If-Match header). This function first performs a GET to obtain a fresh ETag for each VM. .NOTES Implements: POST /vmm/v{ApiVersion}/ahv/config/vms/{extId}/$actions/power-off (operationId: powerOffVm) POST /vmm/v{ApiVersion}/ahv/config/vms/{extId}/$actions/shutdown (operationId: shutdownVm) Uses the selected session's ApiVersion for both endpoints. .PARAMETER PrismSession The server/FQDN of the PrismSession to use. May be omitted when only one session exists. .PARAMETER ExtId The globally unique identifier (UUID) of the VM to stop. .PARAMETER Method 'AcpiShutdown' (default) for a graceful ACPI shutdown, or 'PowerOff' for a forced power-off. .PARAMETER VM A PrismVM object, supplied explicitly or through the pipeline. Uses its ExtId and originating session unless -PrismSession is specified. .EXAMPLE Stop-PrismVM -ExtId '40ca3d2a-daf3-4de9-969d-b25e5175c223' .EXAMPLE Stop-PrismVM -ExtId '40ca3d2a-daf3-4de9-969d-b25e5175c223' -Method PowerOff .OUTPUTS A PrismTask reference describing the asynchronous task. #> [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'ByVM')] [OutputType([PrismTask])] param( [Parameter(Mandatory = $false, HelpMessage = 'Prism Session Name')][string]$PrismSession, [Parameter(Mandatory = $true, ParameterSetName = 'ById', ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = 'VM external identifier (UUID)')] [Alias('Id', 'VmExtId')][ValidateNotNullOrEmpty()][string]$ExtId, [Parameter(Mandatory = $true, ParameterSetName = 'ByVM', ValueFromPipeline = $true)] [ValidateNotNull()][PrismVM]$VM, [Parameter(Mandatory = $false)] [ValidateSet('AcpiShutdown', 'PowerOff')] [string]$Method = 'AcpiShutdown' ) process { $vmId = if ($PSCmdlet.ParameterSetName -eq 'ByVM') { $VM.ExtId } else { $ExtId } if ([string]::IsNullOrWhiteSpace($vmId)) { throw 'A VM ExtId is required.' } $sessionName = if ($PSCmdlet.ParameterSetName -eq 'ByVM' -and -not $PSBoundParameters.ContainsKey('PrismSession')) { $VM.PrismSession } else { $PrismSession } $action = $Method -eq 'AcpiShutdown' ? 'shutdown' : 'power-off' if (-not $PSCmdlet.ShouldProcess($vmId, "Stop VM ($Method)")) { return } $PrismSessionConfig = Get-PrismSession $sessionName $vmPath = 'vmm/v{0}/ahv/config/vms/{1}' -f $PrismSessionConfig.ApiVersion, $vmId $requestETag = Get-PrismResourceEtag -PrismSession $PrismSessionConfig.Name -Path $vmPath $headers = @{ 'If-Match' = $requestETag 'NTNX-Request-Id' = (New-Guid).Guid } $RequestSplat = @{ PrismSession = $PrismSessionConfig.Name Method = 'POST' Path = ('{0}/$actions/{1}' -f $vmPath, $action) Header = $headers } $Response = Invoke-PrismRequest @RequestSplat return [PrismTask]::new($Response.data, $PrismSessionConfig.Name) } } |