安装适用于 Azure Stack Hub 的 PowerShell AzureRM 模块

Azure PowerShell Azure 资源管理器 (AzureRM) 提供了一组使用 Azure 资源管理器模型管理 Azure Stack Hub 资源的 cmdlet。

重要

你访问的是已过时的 Azure Stack Hub PowerShell 版本的网页。 Azure 资源管理器 (AzureRM) PowerShell 模块的所有版本均已过时,但并不缺乏支持。 AzureRM 模块将不再在将来的 Azure Stack Hub 内部版本中更新。 Az 模块将用于内部版本 2002 及更高版本。 AzureRM 模块不支持 2020-09-01-hybrid 配置文件。

若要与 Azure 和 Azure Stack Hub 进行交互,现建议使用的 PowerShell 模块是 Az PowerShell 模块。 若要开始使用 Az PowerShell 模块,请参阅为 Azure Stack Hub 安装 PowerShell Az 预览模块。 若要了解如何迁移到 Az PowerShell 模块, 请参阅在 Azure Stack Hub 中从 AzureRM 迁移到 Azure PowerShell Az。 有关已在 Azure 中采用的 Az 模块的增强功能的详细信息,请参阅 Azure Az PowerShell 模块简介

还需要使用 API 配置文件为 Azure Stack Hub 资源提供程序指定兼容的终结点。

API 配置文件提供一种管理 Azure 与 Azure Stack Hub 之间版本差异的方式。 API 版本配置文件是一组具有特定 API 版本的 Azure 资源管理器 PowerShell 模块。 每个云平台都有一组支持的 API 版本配置文件。 例如,Azure Stack Hub 支持特定的配置文件版本,例如 2019-03-01-hybrid。 安装配置文件时,会安装与指定的配置文件对应的 Azure 资源管理器 PowerShell 模块。

可在已连接到 Internet、部分联网或离线场景中安装与 Azure Stack Hub 兼容的 PowerShell 模块。 本文将引导你完成适用于这些场景的详细说明。

还可以在 Docker 容器中运行 Azure Stack Hub 的 Azure 资源管理器模块。 有关说明,请参阅使用 Docker 运行适用于 Azure Stack Hub 的 PowerShell

1.验证先决条件

开始使用 Azure Stack Hub 和 PowerShell Azure 资源管理器模块之前,必须具备以下先决条件:

  • PowerShell 版本 5.1
    若要检查版本,请运行 $PSVersionTable.PSVersion 并比较版本。 如果没有 PowerShell 5.1,请按照安装 Windows PowerShell 中所述进行操作。

    注意

    PowerShell 5.1 需要 Windows 计算机。

  • 在权限提升的命令提示符下运行 PowerShell。

  • PowerShell 库访问权限
    你需要有权访问 PowerShell 库。 该库是 PowerShell 内容的中心存储库。 PowerShellGet 模块包含用于发现、安装、更新和发布 PowerShell 项目的 cmdlet。 这些项目的示例包括来自 PowerShell 库和其他专用存储库的模块、DSC 资源、角色功能和脚本。 如果在离线场景中使用 PowerShell,则必须从已建立 Internet 连接的计算机检索资源,并将其存储在离线计算机可访问的位置。

验证 PSGallery 是否已注册为存储库。

注意

此步骤需要访问 Internet。

打开权限提升的 PowerShell 提示符,并运行以下 cmdlet:

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

如果未注册存储库,请打开权限提升的 PowerShell 会话并运行以下命令:

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

3.卸载 Azure Stack Hub PowerShell 模块的现有版本

在安装所需版本之前,请确保卸载以前安装的任何 Azure Stack Hub Azure 资源管理器 PowerShell 模块。 使用以下两种方法之一卸载模块:

  1. 若要卸载现有的 Azure 资源管理器和 Az PowerShell 模块,请关闭所有活动的 PowerShell 会话,并运行以下 cmdlet:

    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
    

    如果遇到任何错误(例如“模块已在使用中”),请关闭正在使用模块的 PowerShell 会话,然后重新运行上述脚本。

  2. C:\Program Files\WindowsPowerShell\ModulesC:\Users\{yourusername}\Documents\WindowsPowerShell\Modules 文件夹中删除以 AzureAzAzs. 开头的所有文件夹。 删除这些文件夹会删除任何现有的 PowerShell 模块。

4.已联网:在已建立 Internet 连接的情况下安装适用于 Azure Stack Hub 的 PowerShell

需要的 API 版本配置文件和 Azure Stack Hub PowerShell 模块将取决于所运行的 Azure Stack Hub 版本。

安装 Azure Stack Hub PowerShell

运行以下 PowerShell 脚本,在开发工作站上安装这些模块:

对于 Azure Stack Hub 2002 或更高版本:

可以使用 AzureRm 模块或 Az 预览版模块。 使用 Az 模块需要 Azure Stack Hub 2002 或更高版本。

若要使用 Az 预览版模块,请按照安装 PowerShell Az 模块中的说明进行操作。

# 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 

对于 Azure Stack Hub 1910:

# 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

注意

  • Azure Stack Hub 模块版本 1.8.0 是一个包含中断性变更的版本。 有关详细信息,请参阅发行说明

对于 Azure Stack Hub 1908 或更低版本:

# 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

注意

Azure Stack Hub 模块版本 1.7.2 是一个包含中断性变更的版本。 若要从 Azure Stack Hub 1.6.0 迁移,请参阅迁移指南

确认已安装 PowerShell

运行以下命令来确认安装:

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

如果安装成功,输出中会显示 AzureRmAzureStack 模块。

5.离线:在未建立 Internet 连接的情况下安装 PowerShell

在离线场景中,请先将 PowerShell 模块下载到已建立 Internet 连接的计算机。 然后,将它们传输到要安装的 Azure Stack 开发工具包 (ASDK)。

登录到已建立 Internet 连接的计算机,并根据 Azure Stack Hub 的版本,使用以下脚本下载 Azure 资源管理器和 Azure Stack Hub 包。

安装分为五步:

  1. 将 Azure Stack Hub PowerShell 安装到连接的计算机。
  2. 启用其他存储功能。
  3. 将 PowerShell 包传输到已断开连接的工作站。
  4. 在断开连接的工作站上手动启动 NuGet 提供程序。
  5. 确认已安装 PowerShell。

安装 Azure Stack Hub PowerShell

Azure Stack Hub 2002 或更高版本。

可以使用 Azure 资源管理器或 Az 预览版模块。 有关 Az 模块,请参阅安装 PowerShell Az 模块中的说明。


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

Azure Stack Hub 1910。

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

注意

Azure Stack Hub 模块版本 1.8.0 是一个包含中断性变更的版本。 有关详细信息,请参阅发行说明

对于 Azure Stack Hub 1908 或更低版本:

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

注意

Azure Stack Hub 模块版本 1.7.1 是一项中断性变更。 若要从 Azure Stack Hub 1.6.0 迁移,请参阅迁移指南

注意

在没有 Internet 连接的计算机上,建议执行以下 cmdlet 以禁用遥测数据收集功能。 在不禁用遥测数据收集功能的情况下,可能会遇到 cmdlet 性能降级的问题。 这仅适用于没有 Internet 连接的计算机。

Disable-AzureRmDataCollection

将包添加到工作站

  1. 将下载的程序包复制到 USB 设备。

  2. 登录到已断开连接的工作站,将包从 USB 设备复制到工作站中的某个位置。

  3. 在断开连接的工作站上手动启动 NuGet 提供程序。 有关说明,请参阅在未连接到 Internet 的计算机上手动启动 NuGet 提供程序

  4. 将此位置注册为默认存储库,并从此存储库安装 Azure 资源管理器和 AzureStack 模块:

    # 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
    

确认已安装 PowerShell

运行以下命令来确认安装:

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

6.配置 PowerShell 以使用代理服务器

在需要代理服务器访问 Internet 的场景中,请先将 PowerShell 配置为使用现有的代理服务器:

  1. 打开提升的 PowerShell 命令提示符。

  2. 运行以下命令:

    #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
    

已知问题

get_SerializationSettings 方法错误

  • 原因:PowerShell Az 模块与 PowerShell Azure 资源管理器模块不兼容。

    以下错误指示 Azure 资源管理器模块和 Az 模块在同一会话中加载:

    >  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.
    
  • 补救措施:卸载冲突的模块。

    若要使用 Azure 资源管理器模块,请卸载 Az 模块。 或者,若要使用 Az 模块,请卸载 Azure 资源管理器。 关闭 PowerShell 会话并卸载 Az 或 Azure 资源管理器模块。

    可以在卸载 Azure Stack Hub PowerShell 模块的现有版本中找到相关说明。

NewAzureRMADServicePrincipal 和 NewAzureRMAdApplication 引发的错误

  • 适用:使用 Microsoft Entra ID 的 Azure Stack 环境。

  • 原因:Azure Active Directory Graph 引入了中断性变更,将 Active Directory 应用程序的 IdentifierUri 限制为目录中已验证域的子域。 在更改之前,仅对多租户应用强制实施此限制。 现在,此限制也适用于单租户应用。 此更改将导致以下错误:Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running

  • 补救措施:可以通过两种方式解决此限制。

    • 需要使用作为目录租户子域的服务主体名称。 例如,如果目录为 contoso.partner.onmschina.cn,则服务主体名称必须为 <foo>.contoso.partner.onmschina.cn 形式。 使用以下 cmdlet:

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

      有关标识以及在 Azure Stack Hub 中使用服务主体的详细信息,请参阅 Azure Stack Hub 的标识提供者概述

    • 创建提供有效 IdentifierUri 的 Microsoft Entra 应用,然后使用以下 cmdlet 创建与应用关联的服务主体:

      $app=NewAzureRMAdApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.partner.onmschina.cn
      NewAzureRMADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId
      
  • 发生次数:通用

后续步骤