Public/Set-PrismNgtSetting.ps1
|
function Set-PrismNgtSetting { <# .SYNOPSIS Updates the Nutanix Guest Tools settings of a VM. .DESCRIPTION Sets the VM's enabled NGT capabilities. VSS maps to VSS_SNAPSHOT and SSR maps to SELF_SERVICE_RESTORE. The supplied list replaces the capabilities; include both VSS and SSR to enable both. Retrieves the current NGT payload and preserves its other fields, including guest status, in the PUT body. Uses a PrismVM's originating session unless explicitly overridden. Uses the selected session's ApiVersion and returns an asynchronous PrismTask. .PARAMETER VM A PrismVM, supplied explicitly or through the pipeline. .PARAMETER ExtId The VM external identifier (UUID), instead of a VM object. .PARAMETER Capabilities The desired NGT capabilities: VSS and/or SSR. An empty array clears the list. .PARAMETER PrismSession The server/FQDN of the session. Overrides the VM's originating session. May be omitted for ID lookup when only one session exists. .EXAMPLE $vm | Set-PrismNgtSetting -Capabilities VSS, SSR | Wait-PrismTask .EXAMPLE Set-PrismNgtSetting -ExtId $vmId -Capabilities VSS -PrismSession 'pc.lab.local' .OUTPUTS PrismTask .NOTES PUT /vmm/v{ApiVersion}/ahv/config/vms/{extId}/guest-tools VSS is enabled through the VSS_SNAPSHOT capability. IsVssSnapshotCapable reports guest status; changing that property does not enable VSS. #> [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'ByVM')] [OutputType([PrismTask])] param( [Parameter(Mandatory, ParameterSetName = 'ByVM', Position = 0, ValueFromPipeline)] [ValidateNotNull()][PrismVM]$VM, [Parameter(Mandatory, ParameterSetName = 'ById', Position = 0, ValueFromPipeline, ValueFromPipelineByPropertyName)] [Alias('Id', 'VmExtId')][ValidateNotNullOrEmpty()][string]$ExtId, [Parameter(Mandatory)][AllowEmptyCollection()][ValidateCount(0, 2)] [ValidateSet('VSS', 'SSR')][string[]]$Capabilities, [Parameter()][string]$PrismSession ) process { $vmId = if ($PSCmdlet.ParameterSetName -eq 'ByVM') { $VM.ExtId } else { $ExtId } if ([string]::IsNullOrWhiteSpace($vmId)) { throw 'A VM ExtId is required.' } if (-not $PSCmdlet.ShouldProcess($vmId, 'Update NGT capabilities')) { return } $sessionName = if ($PSCmdlet.ParameterSetName -eq 'ByVM' -and -not $PSBoundParameters.ContainsKey('PrismSession')) { $VM.PrismSession } else { $PrismSession } $sessionConfig = Get-PrismSession $sessionName $path = 'vmm/v{0}/ahv/config/vms/{1}/guest-tools' -f $sessionConfig.ApiVersion, $vmId # Prism validates status fields in the PUT body too. Omitting a true # status such as isReachable can be interpreted as an invalid false value. # Read the body and ETag together so the update uses one current snapshot. $GetSplat = @{ PrismSession = $sessionConfig.Name Method = 'GET' Path = $path PassThruResponse = $true } $current = Invoke-PrismRequest @GetSplat $body = ($current.Content | ConvertFrom-Json -AsHashtable -ErrorAction Stop).data if ($body -isnot [System.Collections.IDictionary]) { throw "No NGT settings were returned for VM '$vmId'." } $requestETag = @($current.Headers.ETag)[0] if (-not $requestETag) { throw "No ETag was returned for VM '$vmId' NGT settings." } $capabilityMap = @{ VSS = 'VSS_SNAPSHOT'; SSR = 'SELF_SERVICE_RESTORE' } $body.capabilities = @($Capabilities | ForEach-Object { $capabilityMap[$_] } | Select-Object -Unique) $headers = @{ 'If-Match' = $requestETag 'NTNX-Request-Id' = (New-Guid).Guid } $RequestSplat = @{ PrismSession = $sessionConfig.Name Method = 'PUT' Path = $path Header = $headers Body = $body } $response = Invoke-PrismRequest @RequestSplat [PrismTask]::new($response.data, $sessionConfig.Name) } } |