Public/Install-PrismNgt.ps1
|
function Install-PrismNgt { <# .SYNOPSIS Installs Nutanix Guest Tools in a VM. .DESCRIPTION Accepts a PrismVM and uses its originating session unless overridden. Installs NGT with the selected reboot policy and returns an asynchronous PrismTask. Immediate reboot requires confirmation unless -Force is used. Uses the session's ApiVersion and the current VM ETag. .PARAMETER VM The PrismVM to install NGT on, supplied explicitly or through the pipeline. .PARAMETER RebootPreference Skip (default) does not schedule a reboot. Immediate reboots after installation. Later schedules a reboot at RebootTime. .PARAMETER RebootTime The reboot timestamp, including a time zone offset. Required with Later and not accepted with Skip or Immediate. Must be in the future. .PARAMETER Credential Optional guest OS credentials for installation, rather than Prism credentials. .PARAMETER Capabilities Optional NGT capabilities to enable: VSS_SNAPSHOT and SELF_SERVICE_RESTORE. .PARAMETER PrismSession Overrides the originating Prism session with the specified server/FQDN. .PARAMETER Force Skips the Immediate reboot confirmation. Still honors -WhatIf and -Confirm. .EXAMPLE $vm | Install-PrismNgt -Credential (Get-Credential) -RebootPreference Skip .EXAMPLE $InstallSplat = @{ VM = $vm RebootPreference = 'Later' RebootTime = [datetimeoffset]'2026-11-01T23:00:00-04:00' Credential = Get-Credential Capabilities = 'VSS_SNAPSHOT' } Install-PrismNgt @InstallSplat | Wait-PrismTask .EXAMPLE $vm | Install-PrismNgt -RebootPreference Immediate -Force .OUTPUTS PrismTask .NOTES POST /vmm/v{ApiVersion}/ahv/config/vms/{extId}/guest-tools/$actions/install Schema: swagger-vmm-v4.2-all.yaml, GuestToolsInstallConfig. #> [CmdletBinding(SupportsShouldProcess = $true)] [OutputType([PrismTask])] param( [Parameter(Mandatory, Position = 0, ValueFromPipeline)] [ValidateNotNull()][PrismVM]$VM, [Parameter()][ValidateSet('Skip', 'Immediate', 'Later')] [string]$RebootPreference = 'Skip', [Parameter()][datetimeoffset]$RebootTime, [Parameter()][ValidateNotNull()][pscredential]$Credential, [Parameter()][ValidateCount(0, 2)] [ValidateSet('VSS_SNAPSHOT', 'SELF_SERVICE_RESTORE')][string[]]$Capabilities, [Parameter()][string]$PrismSession, [Parameter()][switch]$Force ) process { if ([string]::IsNullOrWhiteSpace($VM.ExtId)) { throw 'A VM ExtId is required.' } if ($RebootPreference -eq 'Later') { if (-not $PSBoundParameters.ContainsKey('RebootTime')) { throw 'RebootTime is required when RebootPreference is Later.' } if ($RebootTime -le [datetimeoffset]::UtcNow) { throw 'RebootTime must be in the future.' } } elseif ($PSBoundParameters.ContainsKey('RebootTime')) { throw 'RebootTime can only be used when RebootPreference is Later.' } $action = "Install NGT (reboot preference: $RebootPreference)" if (-not $PSCmdlet.ShouldProcess($VM.ExtId, $action)) { return } if ($RebootPreference -eq 'Immediate' -and -not $Force) { $target = if ($VM.Name) { '{0} ({1})' -f $VM.Name, $VM.ExtId } else { $VM.ExtId } if (-not $PSCmdlet.ShouldContinue( "VM '$target' will reboot immediately after NGT installation. Continue?", 'Confirm immediate VM reboot' )) { return } } $sessionName = if ($PSBoundParameters.ContainsKey('PrismSession')) { $PrismSession } else { $VM.PrismSession } $sessionConfig = Get-PrismSession $sessionName $vmPath = 'vmm/v{0}/ahv/config/vms/{1}' -f $sessionConfig.ApiVersion, $VM.ExtId $EtagSplat = @{ PrismSession = $sessionConfig.Name Path = $vmPath } $requestETag = Get-PrismResourceEtag @EtagSplat if (-not $requestETag) { throw "No ETag was returned for VM '$($VM.ExtId)'." } $body = @{ rebootPreference = @{ scheduleType = $RebootPreference.ToUpperInvariant() } } if ($RebootPreference -eq 'Later') { $body.rebootPreference.schedule = @{ startTime = $RebootTime.ToString('o') } } if ($PSBoundParameters.ContainsKey('Capabilities')) { $body.capabilities = @($Capabilities | ForEach-Object { $_.ToUpperInvariant() } | Select-Object -Unique) } if ($Credential) { $body.credential = @{ username = $Credential.UserName password = $Credential.GetNetworkCredential().Password } } $RequestSplat = @{ PrismSession = $sessionConfig.Name Method = 'POST' Path = ('{0}/guest-tools/$actions/install' -f $vmPath) Header = @{ 'If-Match' = $requestETag 'NTNX-Request-Id' = (New-Guid).Guid } Body = $body } try { $response = Invoke-PrismRequest @RequestSplat } finally { # Do not retain the plaintext guest password in the request body. if ($body.credential) { $body.credential.Clear() } } [PrismTask]::new($response.data, $sessionConfig.Name) } } |