Install PowerShell Az and Azure Stack modules for Azure Stack Hub

Azure Stack Hub Version	AzureStack PowerShell version
2102	2.1.1
2108	2.2.0
2206	2.3.0
2301+	2.4.0

For more information about AzureStack modules, see the PSGallery.

This article explains how to install the Azure PowerShell Az and compatible Azure Stack Hub administrator modules using PowerShellGet. The Az modules can be installed on Windows, macOS, and Linux platforms.

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

If you would like to install PowerShell Resource Modules (AzureRM) module for Azure Stack Hub, see Install PowerShell AzureRM module for Azure Stack Hub.

Important

There will not be new Azure Resource Modules module releases. The Azure Resource Modules modules are under support for critical fixes only. Going forward, there will only be Az releases for Azure Stack Hub.

You can 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 2020-09-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 Az modules in Internet-connected, partially connected, or disconnected scenarios. This article walks you through the detailed instructions for these scenarios.

1. Verify your prerequisites

Az modules are supported on Azure Stack Hub with Update 2002 or later and with the current hotfixes installed. See the Azure Stack Hub release notes for more information.

The Azure PowerShell Az modules work with PowerShell 5.1 or higher on Windows, or PowerShell Core 6.x and later on all platforms. You should install the latest version of PowerShell Core available for your operating system. Azure PowerShell has no other requirements when run on PowerShell Core.

To check your PowerShell version, run the command:

$PSVersionTable.PSVersion

Prerequisites for Windows

To use Azure PowerShell in PowerShell 5.1 on Windows:

1. Update to Windows PowerShell 5.1 if needed. If you're on Windows 10, you already have PowerShell 5.1 installed.

2. Install .NET Framework 4.7.2 or later.

3. Make sure you have the latest version of PowerShellGet. Run the following cmdlets from an elevated prompt:

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   
   powershell -noprofile
   $PSVersionTable
   Uninstall-Module PowershellGet -AllVersions -Force -Confirm:$false
   Get-module PowershellGet
   Find-module PowershellGet
   Install-Module PowershellGet -MinimumVersion 2.2.3 -Force
   

2. Prerequisites for Linux and Mac

PowerShell Core 6.x or later version is needed. Follow the link for instructions

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 or Az 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. If the Uninstall-Module did not succeed, delete all the folders that start with Azure, Az, or Azs. from the $env:PSModulePath locations. For Windows PowerShell, the locations might be C:\Program Files\WindowsPowerShell\Modules and C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules. For PowerShell Core, the locations might be C:\Program Files\PowerShell\7\Modules and C:\Users\{yourusername}\Documents\PowerShell\Modules. Deleting these folders removes any existing Azure PowerShell modules.

4. Connected: Install with internet connectivity

The Azure Stack Az module will work with PowerShell 5.1 or greater on a Windows machine, or PowerShell 6.x or greater on a Linux or macOS platform. Using the PowerShellGet cmdlets is the preferred installation method. This method works the same on the supported platforms.

1. Run the following command from a PowerShell session to update PowerShellGet to a minimum of version 2.2.3

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force
   

2. Close your PowerShell session, then open a new PowerShell session so that update can take effect.

3. Run the following to install Az modules.

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module -Name Az.BootStrapper -Force
   Install-AzProfile -Profile 2020-09-01-hybrid -Force
   

4. Install AzureStack PowerShell modules.

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

Warning

You can't have both the Azure Resource Manager (AzureRM) and Az modules installed for PowerShell 5.1 for Windows at the same time. If you need to keep Azure Resource Manager available on your system, install the Az module for PowerShell Core 6.x or later. To do this, install PowerShell Core 6.x or later and then follow these instructions in a PowerShell Core terminal.

5. Disconnected: Install without 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

1. You could either use AzureRM or Az modules. The following code saves Az modules from trustworthy online repository https://www.powershellgallery.com/.

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-module -Name PowerShellGet -MinimumVersion 2.2.3 -Force
   Import-Module -Name PackageManagement -ErrorAction Stop
   $savedModulesPath = "<Path that is used to save the packages>"
   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name Az -Path $savedModulesPath -Force -RequiredVersion 2.0.1
   

2. After the Az modules are installed, proceed with installing the AzureStack modules.

   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.4.0
   

Note

On machines without an internet connection, we recommend executing the following cmdlet for disabling the telemetry data collection. You may experience a performance degradation of the cmdlets without disabling the telemetry data collection. This is applicable only for the machines without internet connections

Disable-AzDataCollection

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 AzureRM 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"
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    Register-PSRepository -Name $RepoName -SourceLocation $SourceLocation -InstallationPolicy Trusted
   

5. Install the Az modules.

    Install-Module -Name Az -Repository $RepoName -RequiredVersion 2.0.1 -Scope AllUsers
   

6. Install the AzureStack modules.

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.4.0 -Scope AllUsers
   

Confirm the installation of PowerShell

Confirm the installation by running the following command:

Get-Module -Name "Az*" -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
   

7. Use the Az module

You can use the cmdlets and code samples based on AzureRM modules. However, you will want to change the name of the modules and cmdlets. The module names have been changed so that AzureRM and Azure become Az, and the same for cmdlets. For example, the AzureRM.Compute module has been renamed to Az.Compute. New-AzureRMVM has become New-AzVM, and Get-AzureStorageBlob is now Get-AzStorageBlob.

For a more thorough discussion and guidance for moving AzurRM script to Az and breaking changes in Azure Stack Hub's Az module, see Migrate from AzureRM to Azure PowerShell Az.

Known issues

Error thrown when installing the Az modules

• Applicable: This issue applies to 2002 and later
• Cause: When installing the module, an error is thrown. The error message begins: Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. Or the error message may include the following text: PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• Remediation: Run the following cmdlet in the same session:
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  Close your session and start a new elevated PowerShell session.
• Occurrence: Common

When installing Az module falsely throws Admin rights required error

• Applicable: This issue applies to 2002 and later
• Cause: When installing the module from an elevated prompt, an error is thrown. The error says, Administrator rights required.
• Remediation: Close your session and start a new elevated PowerShell session. Make sure there isn't an existing Az. Accounts module loaded in the session.
• Occurrence: Common

Cmdlet New-AzVmss fails when using 2020-09-01-hybrid profile

• Applicable: This issue applies to the 2020-09-01-hybrid profile.
• Cause: The cmdlet New-AzVmss does not work with the 2020-09-01-hybrid profile.
• Remediation: Use a template for creating virtual machine scale set. You can find a sample the Azure Stack Hub Resource Manager templates in the GitHub Repository AzureStack-QuickStart-Templates/101-vmss-windows-vm and you can find instruction on using Azure Stack Hub Resource Managers with Visual Studio Code.
• Occurrence: Common

Error thrown when running a PowerShell script

• Applicable: This issue applies to 2002 and later.

• Cause: When running scripts or PowerShell commands using the Azure Stack Hub specific modules, you will need your script or command to be available in the module. You may see the following error:

  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.
  

  The current module is the PowerShell Az module, which has replaced the PowerShell AzureRM module. If you attempt to run a script that calls for AzureRM commands when the Az module is installed, your script will throw errors. Or if you attempt to run a script that calls Az commands when the AzureRM module is installed, your script will throw errors.

• Remediation: Uninstall the AzureRM module and install the Az module. For instructions, see Install PowerShell Az module for Azure Stack Hub. If you're using the Azure Stack Hub Tools, use the Az tools. Clone the tools repository from the az branch, or download the AzureStack-Tools from the az branch. For instructions, see Download Azure Stack Hub tools from GitHub

• Occurrence: Common

Error thrown with New-AzADServicePrincipal and New-AzADApplication

• 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 principle name that is a subdomain of the directory tenant. For example, if the directory is contoso.onmicrosoft.com, the service principal name has to be of the form of <foo>.contoso.onmicrosoft.com. Use the following cmdlet:

    New-AzADServicePrincipal -Role Owner -DisplayName <foo>.contoso.onmicrosoft.com
    

    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=New-AzADApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.onmicrosoft.com
    New-AzADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId
    

• Occurrence: Common

Error: "SharedTokenCacheCredential authentication failed"

• Applicable: This issue applies to all supported releases.
• Cause: A SharedTokenCacheCredential authentication failed error is thrown when having multiple versions of AzAccounts installed with Azure Stack Hub PowerShell Module version 2.1.1.
• Remediation: Remove all versions of AzAccounts and only install the supported AzAccounts version 2.2.8.
• 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