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)
    }
}