Install PowerShell AzureRM module for Azure Stack Hub

Azure PowerShell Azure Resource Manager (AzureRM) provides a set of cmdlets that use the Azure Resource Manager model for managing your Azure Stack Hub resources.

You also need to use API profiles to specify the compatible endpoints for the Azure Stack Hub resource providers.

API profiles provide a way to manage version differences between Azure and Azure Stack Hub. An API version profile is a set of Azure Resource Manager PowerShell modules with specific API versions. Each cloud platform has a set of supported API version profiles. For example, Azure Stack Hub supports a specific profile version such as 2019-03-01-hybrid. When you install a profile, the Azure Resource Manager PowerShell modules that correspond to the specified profile are installed.

You can install Azure Stack Hub compatible PowerShell modules in internet-connected, partially connected, or disconnected scenarios. This article walks you through the detailed instructions for these scenarios.

You can also run the Azure Resource Manager modules for Azure Stack Hub in a Docker container. For instructions, see Use Docker to run PowerShell for Azure Stack Hub.

1. Verify your prerequisites

Before you get started with Azure Stack Hub and the PowerShell Azure Resource Manager module, you must have the following prerequisites:

• PowerShell Version 5.1
  To check your version, run $PSVersionTable.PSVersion and compare the Major version. If you don't have PowerShell 5.1, follow the Installing Windows PowerShell.

  Note

  PowerShell 5.1 requires a Windows machine.

• Run PowerShell in an elevated command prompt.

• PowerShell Gallery access
  You need access to the PowerShell Gallery. The gallery is the central repository for PowerShell content. The PowerShellGet module contains cmdlets for discovering, installing, updating, and publishing PowerShell artifacts. Examples of these artifacts are modules, DSC resources, role capabilities, and scripts from the PowerShell Gallery and other private repositories. If you're using PowerShell in a disconnected scenario, you must retrieve resources from a machine with a connection to the internet and store them in a location accessible to your disconnected machine.

2. Validate the PowerShell Gallery accessibility

Validate if PSGallery is registered as a repository.

Open an elevated PowerShell prompt, and run the following cmdlets:

Install-module -Name PowerShellGet -Force
Import-Module -Name PackageManagement -ErrorAction Stop
Get-PSRepository -Name "PSGallery"

If the repository isn't registered, open an elevated PowerShell session and run the following command:

Register-PSRepository -Default
Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted

3. Uninstall existing versions of the Azure Stack Hub PowerShell modules

Before installing the required version, make sure that you uninstall any previously installed Azure Stack Hub Azure Resource Manager PowerShell modules. Uninstall the modules by using one of the following two methods:

1. To uninstall the existing Azure Resource Manager and Az PowerShell modules, close all the active PowerShell sessions, and run the following cmdlets:

   Get-Module -Name Azure* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
   Get-Module -Name Azs.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
   Get-Module -Name Az.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
   

   If you hit an error such as 'The module is already in use', close the PowerShell sessions that are using the modules and rerun the above script.

2. Delete all the folders that start with Azure, Az or Azs. from the C:\Program Files\WindowsPowerShell\Modules and C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules folders. Deleting these folders removes any existing PowerShell modules.

4. Connected: Install PowerShell for Azure Stack Hub with internet connectivity

The API version profile and Azure Stack Hub PowerShell modules you require will depend on the version of Azure Stack Hub you're running.

Install Azure Stack Hub PowerShell

Run the following PowerShell script to install these modules on your development workstation:

# Install the AzureRM.BootStrapper module. Select Yes when prompted to install NuGet
Install-Module -Name AzureRM.BootStrapper

# Install and import the API Version Profile required by Azure Stack Hub into the current PowerShell session.
Use-AzureRmProfile -Profile 2019-03-01-hybrid -Force
Install-Module -Name AzureStack -RequiredVersion 1.8.3 

# Install the AzureRM.BootStrapper module. Select Yes when prompted to install NuGet
Install-Module -Name AzureRM.BootStrapper

# Install and import the API Version Profile required by Azure Stack Hub into the current PowerShell session.
Use-AzureRmProfile -Profile 2019-03-01-hybrid -Force
Install-Module -Name AzureStack -RequiredVersion 1.8.0

# Install the AzureRM.BootStrapper module. Select Yes when prompted to install NuGet
Install-Module -Name AzureRM.BootStrapper

# Install and import the API Version Profile required by Azure Stack Hub into the current PowerShell session.
Use-AzureRmProfile -Profile 2019-03-01-hybrid -Force
Install-Module -Name AzureStack -RequiredVersion 1.7.2

Confirm the installation of PowerShell

Confirm the installation by running the following command:

Get-Module -Name "Azure*" -ListAvailable
Get-Module -Name "Azs*" -ListAvailable

If the installation is successful, the AzureRm and AzureStack modules are displayed in the output.

5. Disconnected: Install PowerShell without an internet connection

In a disconnected scenario, you first download the PowerShell modules to a machine that has internet connectivity. Then, you transfer them to the Azure Stack Development Kit (ASDK) for installation.

Sign in to a computer with internet connectivity and use the following scripts to download the Azure Resource Manager and Azure Stack Hub packages, depending on your version of Azure Stack Hub.

Installation has five steps:

1. Install Azure Stack Hub PowerShell to a connected machine.
2. Enable additional storage features.
3. Transport the PowerShell packages to your disconnected workstation.
4. Manually bootstrap the NuGet provider on your disconnected workstation.
5. Confirm the installation of PowerShell.

Install Azure Stack Hub PowerShell

Install-module -Name PowerShellGet -Force 
Import-Module -Name PackageManagement -ErrorAction Stop

$Path = "<Path that is used to save the packages>"
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureRM -Path $Path -Force -RequiredVersion 2.5.0
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $Path -Force -RequiredVersion 1.8.3

Install-module -Name PowerShellGet -Force 
Import-Module -Name PackageManagement -ErrorAction Stop

$Path = "<Path that is used to save the packages>"
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureRM -Path $Path -Force -RequiredVersion 2.5.0
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $Path -Force -RequiredVersion 1.8.0

Install-module -Name PowerShellGet -Force 
Import-Module -Name PackageManagement -ErrorAction Stop

$Path = "<Path that is used to save the packages>"
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureRM -Path $Path -Force -RequiredVersion 2.5.0
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $Path -Force -RequiredVersion 1.7.2

Disable-AzureRmDataCollection

Add your packages to your workstation

1. Copy the downloaded packages to a USB device.

2. Sign in to the disconnected workstation and copy the packages from the USB device to a location on the workstation.

3. Manually bootstrap the NuGet provider on your disconnected workstation. For instructions, see Manually bootstrapping the NuGet provider on a machine that isn't connected to the internet.

4. Register this location as the default repository and install the Azure Resource Manager and AzureStack modules from this repository:

   # requires -Version 5
   # requires -RunAsAdministrator
   # requires -Module PowerShellGet
   # requires -Module PackageManagement
   
   $SourceLocation = "<Location on the development kit that contains the PowerShell packages>"
   $RepoName = "MyNuGetSource"
   
   Register-PSRepository -Name $RepoName -SourceLocation $SourceLocation -InstallationPolicy Trusted
   
   Install-Module -Name AzureRM -Repository $RepoName
   
   Install-Module -Name AzureStack -Repository $RepoName
   

Confirm the installation of PowerShell

Confirm the installation by running the following command:

Get-Module -Name "Azure*" -ListAvailable
Get-Module -Name "Azs*" -ListAvailable

6. Configure PowerShell to use a proxy server

In scenarios that require a proxy server to access the internet, you first configure PowerShell to use an existing proxy server:

1. Open an elevated PowerShell prompt.

2. Run the following commands:

   #To use Windows credentials for proxy authentication
   [System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials
   
   #Alternatively, to prompt for separate credentials that can be used for #proxy authentication
   [System.Net.WebRequest]::DefaultWebProxy.Credentials = Get-Credential
   

Known issue

Method get_SerializationSettings error

• Cause: The PowerShell Az module and PowerShell Azure Resource Manager modules are not compatible.

  The following error indicates that the Azure Resource Manager modules and Az modules are loaded in the same session:

  >  Method 'get_SerializationSettings' in type 'Microsoft.Azure.Management.Internal.Resources.ResourceManagementClient' from assembly 'Microsoft.Azure.Commands.ResourceManager.Common, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' does 
  not have an implementation.
  

• Remediation: Uninstall the conflicting modules.

  If you would like to use the Azure Resource Manager modules, uninstall the Az modules. Or uninstall the Azure Resource Manager if you would like to use the Az modules. Close your PowerShell session and uninstall either the Az or Azure Resource Manager modules.

  You can find instructions at Uninstall existing versions of the Azure Stack Hub PowerShell modules.

Error thrown with NewAzureRMADServicePrincipal and NewAzureRMAdApplication

• Applicable: Azure Stack environments using Microsoft Entra ID.

• Cause: Azure Active Directory Graph introduced a breaking change to restrict the IdentifierUri for Active Directory applications to be the subdomains of a verified domain in the directory. Before the change, this restriction was only enforced for the multi-tenant apps. Now this restriction applies to single tenant apps as well. The change will result in the following error: Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running.

• Remediation: You can work around this restriction in two ways.

  • You'll need to use a service principal name that is a subdomain of the directory tenant. For example, if the directory is contoso.partner.onmschina.cn, the service principal name has to be of the form of <foo>.contoso.partner.onmschina.cn. Use the following cmdlet:

    NewAzureRMADServicePrincipal -Role Owner -DisplayName <foo>.contoso.partner.onmschina.cn
    

    For more information about identity and using service principals with Azure Stack Hub, see Overview of identity providers for Azure Stack Hub.

  • Create the Microsoft Entra app providing a valid IdentifierUri and then create the service principal associating the app using the following cmdlet:

    $app=NewAzureRMAdApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.partner.onmschina.cn
    NewAzureRMADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId
    

• Occurrence: Common

Next steps

• Download Azure Stack Hub tools from GitHub
• Configure the Azure Stack Hub user's PowerShell environment
• Configure the Azure Stack Hub operator's PowerShell environment
• Manage API version profiles in Azure Stack Hub