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. .PARAMETER ETag The current NGT settings ETag. Retrieved automatically when omitted. .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, [Parameter()][ValidateNotNullOrEmpty()][string]$ETag ) 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 = if ($ETag) { $ETag } else { @($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) } } |