Adding Remote Support cmdlets for Stack HCI (#16819)

* Adding Remote Support cmdlet to install, remove, enable, disable, get access and get session history.

* Adding logging setup and removing -ListAvailable flag for checking module

* Added cmdlet help, fixed signature issues, made SasCredential optional parameter

* Updating help for cmdlet

* Output type of cmdlet to Boolean

* Updated release notes for Remote Support cmdlet change

* Moving DownloadCacheDirectory and RemoteSupportPAckageUri variables to required function.

Co-authored-by: Yunchi Wang <[email protected]>

Author: swashtek

src/StackHCI/Az.StackHCI.psd1

@@ -73,7 +73,10 @@ FunctionsToExport = 'Register-AzStackHCI', 'Unregister-AzStackHCI',
                'Test-AzStackHCIConnection', 'Set-AzStackHCI', 
                'Enable-AzStackHCIAttestation', 'Disable-AzStackHCIAttestation', 
                'Add-AzStackHCIVMAttestation', 'Remove-AzStackHCIVMAttestation', 
-               'Get-AzStackHCIVMAttestation'
+               'Get-AzStackHCIVMAttestation','Install-AzStackHCIRemoteSupport',
+               'Enable-AzStackHCIRemoteSupport','Disable-AzStackHCIRemoteSupport',
+               'Get-AzStackHCIRemoteSupportAccess','Get-AzStackHCIRemoteSupportSessionHistory',
+               'Remove-AzStackHCIRemoteSupport'
 
 # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
 CmdletsToExport = @()

src/StackHCI/Az.StackHCI.psm1

@@ -4496,6 +4496,300 @@ param(
     }
 }
 
+<#
+.DESCRIPTION
+    New-Directory creates new directory if doesn't exist already.
+
+.PARAMETER Path
+    Mandatory. Directory path.
+
+.EXAMPLE
+    Get all guests on cluster.
+    C:\PS>New-Directory -Path "C:\tool"
+
+.NOTES
+#>
+function New-Directory{
+    param(
+    [Parameter(Mandatory=$true)][ValidateNotNull()][string]$Path
+    )
+
+    if (!(Test-Path -Path $Path -PathType Container))
+    {
+        Write-Progress("Creating directory at $Path")
+        New-Item -ItemType Directory -Path $Path | Out-Null
+    }
+    else
+    {
+        Write-Progress("Directory already exists at $Path")
+    }
+}
+
+<#
+.SYNOPSIS
+    Invokes deployment module download
+
+.Description
+    Invoke-DeploymentModuleDownload downloads Remote Support Deployment module from storage account.
+
+.EXAMPLE
+    Get all guests on cluster.
+    C:\PS>Invoke-DeploymentModuleDownload
+
+.NOTES
+#>
+function Invoke-DeploymentModuleDownload{
+    # Remote Support
+    New-Variable -Name RemoteSupportPackageUri -Value "https://remotesupportpackages.blob.core.windows.net/packages" -Option Constant -Scope Script
+    $DownloadCacheDirectory = Join-Path $env:Temp "RemoteSupportPkgCache"
+
+    $BlobLocation = "$script:RemoteSupportPackageUri/Microsoft.AzureStack.Deployment.RemoteSupport.psm1"
+    $OutFile = (Join-Path $DownloadCacheDirectory "Microsoft.AzureStack.Deployment.RemoteSupport.psm1")
+    New-Directory -Path $DownloadCacheDirectory
+    Write-Progress("Downloading Remote Support Deployment module from the BLOB $BlobLocation")
+    $retryCount = 3
+    Setup-Logging -LogFilePrefix "AzStackHCIRemoteSupport"
+    Retry-Command -Attempts $retryCount -RetryIfNullOutput $false -ScriptBlock { Invoke-WebRequest -Uri $BlobLocation -outfile $OutFile }
+}
+
+<#
+.SYNOPSIS
+    Installs deploy module.
+
+.DESCRIPTION 
+    Install-DeployModule checks if given module is loaded and if not, it downloads, imports and installs remote support deployment module.
+
+.EXAMPLE
+    C:\PS>Install-DeployModule -ModuleName "Microsoft.AzureStack.Deployment.RemoteSupport"
+
+.NOTES
+#>
+function Install-DeployModule {
+    [CmdletBinding()]
+    param (
+        [Parameter(Mandatory=$true)]
+        [string]
+        $ModuleName
+    )
+
+    if(Get-Module | Where-Object { $_.Name -eq $ModuleName }){
+        Write-Host "$ModuleName is loaded already ..."
+    }
+    else{
+        Write-Host "$ModuleName is not loaded, downloading ..."
+
+        # Download Remote Support Deployment module from storage
+        Invoke-DeploymentModuleDownload
+    }
+
+    # Import Remote Support Deployment module
+    $DownloadCacheDirectory = Join-Path $env:Temp "RemoteSupportPkgCache"
+    Import-Module (Join-Path $DownloadCacheDirectory "Microsoft.AzureStack.Deployment.RemoteSupport.psm1") -Force
+}
+
+<#
+.SYNOPSIS
+    Installs Remote Support.
+
+.DESCRIPTION
+    Install-AzStackHCIRemoteSupport installs Remote Support Deployment module.
+
+.EXAMPLE
+    C:\PS>Install-AzStackHCIRemoteSupport
+
+.NOTES
+#>
+function Install-AzStackHCIRemoteSupport{
+    [CmdletBinding(SupportsShouldProcess)]
+    [OutputType([Boolean])]
+    param()
+
+    Install-DeployModule -ModuleName "Microsoft.AzureStack.Deployment.RemoteSupport"
+    Microsoft.AzureStack.Deployment.RemoteSupport\Install-RemoteSupport
+}
+
+<#
+.SYNOPSIS
+    Removes Remote Support.
+
+.DESCRIPTION
+    Remove-AzStackHCIRemoteSupport uninstalls Remote Support Deployment module.
+
+.EXAMPLE
+    C:\PS>Remove-AzStackHCIRemoteSupport
+
+.NOTES
+#>
+function Remove-AzStackHCIRemoteSupport{
+    [CmdletBinding(SupportsShouldProcess)]
+    [OutputType([Boolean])]
+    param()
+
+    Install-DeployModule -ModuleName "Microsoft.AzureStack.Deployment.RemoteSupport"
+    Microsoft.AzureStack.Deployment.RemoteSupport\Remove-RemoteSupport
+}
+
+<#
+.SYNOPSIS
+    Enables Remote Support.
+
+.DESCRIPTION
+    Enables Remote Support allows authorized Microsoft Support users to remotely access the device for diagnostics or repair depending on the access level granted.
+
+.PARAMETER AccessLevel
+    Controls the remote operations that can be performed. This can be either Diagnostics or DiagnosticsAndRepair.
+
+.PARAMETER ExpireInDays
+    Optional. Defaults to 8 hours.
+
+.PARAMETER SasCredential
+    Hybrid Connection SAS Credential.
+
+.PARAMETER AgreeToRemoteSupportConsent
+    Optional. If set to true then records user consent as provided and proceeds without prompt.
+
+.EXAMPLE
+    The example below enables remote support for diagnostics only for 1 day. After expiration no more remote access is allowed.
+    PS C:\> Enable-AzStackHCIRemoteSupport -AccessLevel Diagnostics -ExpireInMinutes 1440 -SasCredential "Sample SAS"
+
+.NOTES
+    Requires Support VM to have stable internet connectivity.
+#>
+function Enable-AzStackHCIRemoteSupport{
+    [CmdletBinding(SupportsShouldProcess)]
+    [OutputType([Boolean])]
+    param (
+        [Parameter(Mandatory=$true)]
+        [ValidateSet("Diagnostics","DiagnosticsRepair")]
+        [string]
+        $AccessLevel,
+
+        [Parameter(Mandatory=$false)]
+        [int]
+        $ExpireInMinutes = 480,
+
+        [Parameter(Mandatory=$false)]
+        [string]
+        $SasCredential,
+
+        [Parameter(Mandatory=$false)]
+        [switch]
+        $AgreeToRemoteSupportConsent
+    )
+
+    Install-DeployModule -ModuleName "Microsoft.AzureStack.Deployment.RemoteSupport"
+
+    Microsoft.AzureStack.Deployment.RemoteSupport\Enable-RemoteSupport -AccessLevel $AccessLevel -ExpireInMinutes $ExpireInMinutes -SasCredential $SasCredential -AgreeToRemoteSupportConsent:$AgreeToRemoteSupportConsent
+}
+
+<#
+.SYNOPSIS
+    Disables Remote Support.
+
+.DESCRIPTION
+    Disable Remote Support revokes all access levels previously granted. Any existing support sessions will be terminated, and new sessions can no longer be established.
+
+.EXAMPLE
+    The example below disables remote support.
+    PS C:\> Disable-AzStackHCIRemoteSupport
+
+.NOTES
+
+#>
+function Disable-AzStackHCIRemoteSupport{
+    [CmdletBinding(SupportsShouldProcess)]
+    [OutputType([Boolean])]
+    param()
+    Install-DeployModule -ModuleName "Microsoft.AzureStack.Deployment.RemoteSupport"
+
+    Microsoft.AzureStack.Deployment.RemoteSupport\Disable-RemoteSupport
+}
+
+<#
+.SYNOPSIS
+    Gets Remote Support Access.
+
+.DESCRIPTION
+    Gets remote support access.
+
+.PARAMETER IncludeExpired
+    Optional. Defaults to false. Indicates whether to include past expired entries.
+
+.PARAMETER Cluster
+    Optional. Defaults to false. Indicates whether to show remote support sessions across cluster.
+
+.EXAMPLE
+    The example below retrieves access level granted for remote support. The result will also include expired consents in the last 30 days.
+    PS C:\> Get-AzStackHCIRemoteSupportAccess -IncludeExpired -Cluster
+
+.NOTES
+
+#>
+function Get-AzStackHCIRemoteSupportAccess{
+    [OutputType([Boolean])]
+    Param(
+        [Parameter(Mandatory=$false)]
+        [switch]
+        $Cluster,
+
+        [Parameter(Mandatory=$false)]
+        [switch]
+        $IncludeExpired
+    )
+
+    Install-DeployModule -ModuleName "Microsoft.AzureStack.Deployment.RemoteSupport"
+
+    Microsoft.AzureStack.Deployment.RemoteSupport\Get-RemoteSupportAccess -Cluster:$Cluster -IncludeExpired:$IncludeExpired
+}
+
+<#
+.SYNOPSIS
+    Gets Remote Support Session History Details.
+
+.DESCRIPTION
+    Session history represents all remote accesses made by Microsoft Support for either Diagnostics or DiagnosticsRepair based on the Access Level granted.
+
+.PARAMETER SessionId
+    Optional. Session Id to get details for a specific session. If omitted then lists all sessions starting from date 'FromDate'.
+
+.PARAMETER IncludeSessionTranscript
+    Optional. Defaults to false. Indicates whether to include complete session transcript. Transcript provides details on all operations performed during the session.
+
+.PARAMETER FromDate
+    Optional. Defaults to last 7 days. Indicates date from where to start listing sessions from until now.
+
+.EXAMPLE
+    The example below retrieves session history with transcript details for the specified session.
+    PS C:\> Get-AzStackHCIRemoteSupportSessionHistory -SessionId 467e3234-13f4-42f2-9422-81db248930fa -IncludeSessionTranscript $true
+
+.EXAMPLE
+    The example below lists session history starting from last 7 days (default) to now.
+    PS C:\> Get-AzStackHCIRemoteSupportSessionHistory
+
+.NOTES
+
+#>
+function Get-AzStackHCIRemoteSupportSessionHistory{
+    [OutputType([Boolean])]
+    Param(
+        [Parameter(Mandatory=$false)]
+        [string]
+        $SessionId,
+
+        [Parameter(Mandatory=$false)]
+        [switch]
+        $IncludeSessionTranscript,
+
+        [Parameter(Mandatory=$false)]
+        [DateTime]
+        $FromDate = (Get-Date).AddDays(-7)
+    )
+
+    Install-DeployModule -ModuleName "Microsoft.AzureStack.Deployment.RemoteSupport"
+
+    Microsoft.AzureStack.Deployment.RemoteSupport\Get-RemoteSupportSessionHistory -SessionId $SessionId -FromDate $FromDate -IncludeSessionTranscript:$IncludeSessionTranscript
+}
+
 Export-ModuleMember -Function Register-AzStackHCI
 Export-ModuleMember -Function Unregister-AzStackHCI
 Export-ModuleMember -Function Test-AzStackHCIConnection
@@ -4504,4 +4798,10 @@ Export-ModuleMember -Function Enable-AzStackHCIAttestation
 Export-ModuleMember -Function Disable-AzStackHCIAttestation
 Export-ModuleMember -Function Add-AzStackHCIVMAttestation
 Export-ModuleMember -Function Remove-AzStackHCIVMAttestation
-Export-ModuleMember -Function Get-AzStackHCIVMAttestation
+Export-ModuleMember -Function Get-AzStackHCIVMAttestation
+Export-ModuleMember -Function Install-AzStackHCIRemoteSupport
+Export-ModuleMember -Function Remove-AzStackHCIRemoteSupport
+Export-ModuleMember -Function Enable-AzStackHCIRemoteSupport
+Export-ModuleMember -Function Disable-AzStackHCIRemoteSupport
+Export-ModuleMember -Function Get-AzStackHCIRemoteSupportAccess
+Export-ModuleMember -Function Get-AzStackHCIRemoteSupportSessionHistory

src/StackHCI/ChangeLog.md

@@ -18,7 +18,9 @@
         - Additional information about change #1
 -->
 ## Upcoming Release
-
+* Adding support cmdlet for Remote Support 
+    - New cmdlets - Install-AzStackHCIRemoteSupport, Remove-AzStackHCIRemoteSupport, Enable-AzStackHCIRemoteSupport, Disable-AzStackHCIRemoteSupport, Get-AzStackHCIRemoteSupportAccess,Get-AzStackHCIRemoteSupportSessionHistory
+    
 ## Version 1.0.0
 * Promoted Az.StackHCI to GA
 

src/StackHCI/help/Az.StackHCI.md

@@ -17,15 +17,33 @@ Add-AzStackHCIVMAttestation configures guests for AzureStack HCI IMDS Attestatio
 ### [Disable-AzStackHCIAttestation](Disable-AzStackHCIAttestation.md)
 Disable-AzStackHCIAttestation disables IMDS Attestation on the host
 
+### [Disable-AzStackHCIRemoteSupport](Disable-AzStackHCIRemoteSupport.md)
+Disables Remote Support.
+
 ### [Enable-AzStackHCIAttestation](Enable-AzStackHCIAttestation.md)
 Enable-AzStackHCIAttestation configures the host and enables specified guests for IMDS attestation.
 
+### [Enable-AzStackHCIRemoteSupport](Enable-AzStackHCIRemoteSupport.md)
+Enables Remote Support.
+
+### [Get-AzStackHCIRemoteSupportAccess](Get-AzStackHCIRemoteSupportAccess.md)
+Gets Remote Support Access.
+
+### [Get-AzStackHCIRemoteSupportSessionHistory](Get-AzStackHCIRemoteSupportSessionHistory.md)
+Gets Remote Support Session History Details.
+
 ### [Get-AzStackHCIVMAttestation](Get-AzStackHCIVMAttestation.md)
 Get-AzStackHCIVMAttestation shows a list of guests added to IMDS Attestation on a node.
 
+### [Install-AzStackHCIRemoteSupport](Install-AzStackHCIRemoteSupport.md)
+Installs Remote Support.
+
 ### [Register-AzStackHCI](Register-AzStackHCI.md)
 Register-AzStackHCI creates a Microsoft.AzureStackHCI cloud resource representing the on-premise cluster and registers the on-premise cluster with Azure.
 
+### [Remove-AzStackHCIRemoteSupport](Remove-AzStackHCIRemoteSupport.md)
+Removes Remote Support.
+
 ### [Remove-AzStackHCIVMAttestation](Remove-AzStackHCIVMAttestation.md)
 Remove-AzStackHCIVMAttestation removes guests from AzureStack HCI IMDS Attestation.