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

本文介绍如何使用 PowerShellGet 安装 Azure PowerShell Az 和兼容的 Azure Stack Hub 管理员模块。 Az 模块可以在 Windows、macOS 和 Linux 平台上安装。

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

如果要安装适用于 Azure Stack Hub 的 PowerShell 资源模块 (AzureRM) 模块,请参阅安装适用于 Azure Stack Hub 的 PowerShell AzureRM 模块

重要

可能不会有新的 Azure 资源模块模块版本。 “Azure 资源模块”模块仅支持关键修补程序。 今后,Azure Stack Hub 将只有 Az 版本。

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

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

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

1.验证先决条件

安装了 Update 2002 或更高版本以及最新修补程序的 Azure Stack Hub 支持 Az 模块。 有关详细信息,请参阅 Azure Stack Hub 发行说明

Azure PowerShell Az 模块适用于 Windows 上的 PowerShell 5.1 或更高版本,或者所有平台上的 PowerShell Core 6.x 及更高版本。 你应该安装适用于你的操作系统的最新版本的 PowerShell Core。 在 PowerShell Core 上运行时,Azure PowerShell 没有其他要求。

若要检查 PowerShell 版本,请运行以下命令:

$PSVersionTable.PSVersion

Windows 先决条件

若要在 Windows 上的 PowerShell 5.1 中使用 Azure PowerShell,请执行以下操作:

  1. 在必要时更新到 Windows PowerShell 5.1。 如果是在 Windows 10 平台上,则已安装 PowerShell 5.1。
  2. 安装 .NET Framework 4.7.2 或更高版本
  3. 确保你具有最新版本的 PowerShellGet。 运行 Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force

2.Linux 和 Mac 先决条件

需要 PowerShell Core 6.x 或更高版本。 请访问链接获取说明

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

在安装所需版本之前,请确保卸载以前安装的任何 Azure Stack Hub Azure 资源管理器或 Az 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 Az 模块将在 Windows 计算机上与 PowerShell 5.1 或更高版本配合使用,在 Linux 或 macOS 平台上与 PowerShell 6.x 或更高版本配合使用。 使用 PowerShellGet cmdlet 是首选的安装方法。 此方法在受支持平台上的工作原理相同。

  1. 从 PowerShell 会话运行以下命令,以将 PowerShellGet 至少更新到版本 2.2.3

    Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force
    
  2. 关闭 PowerShell 会话,然后打开新的 PowerShell 会话,以使更新生效。

  1. 从 PowerShell 会话运行以下命令:

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    
    Install-Module -Name Az.BootStrapper -Force
    Install-AzProfile -Profile 2020-09-01-hybrid -Force
    Install-Module -Name AzureStack -RequiredVersion 2.1.1 
    
  1. 从 PowerShell 会话运行以下命令:

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    
    Install-Module -Name Az.BootStrapper -Force
    Install-AzProfile -Profile 2019-03-01-hybrid -Force
    Install-Module -Name AzureStack -RequiredVersion 2.0.2-preview -AllowPrerelease
    

备注

Azure Stack Hub 模块版本 2.0.2 是一项中断性变更。 有关详细信息,请参阅在 Azure Stack Hub 中从 AzureRM 迁移到 Azure PowerShell Az

警告

对于适用于 Windows 的 PowerShell 5.1,不能同时安装 Azure 资源管理器 (AzureRM) 和 Az 模块。 如果需要确保 Azure 资源管理器在系统上始终可用,请为 PowerShell Core 6.x 或更高版本安装 Az 模块。 为此,请安装 PowerShell Core 6.x 或更高版本,然后在 PowerShell Core 终端中按照这些说明操作。

5.离线:不通过 Internet 连接安装

在离线场景中,请先将 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 2102 或更高版本。

可以使用 Azure 资源管理器或 Az 模块。 对于 Azure 资源管理器,请参阅安装 PowerShell AzureRM 模块中的说明。 以下代码保存可信联机存储库 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 1.10.0
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.1.1

Azure Stack Hub 2008 或更低版本。

可以使用 Azure 资源管理器或 Az 模块。 对于 Azure 资源管理器,请参阅安装 PowerShell AzureRM 模块中的说明。 以下代码保存可信联机存储库 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 0.10.0-preview
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.0.2-preview

备注

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

Disable-AzDataCollection

将包添加到工作站

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

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

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

  4. 将此位置注册为默认存储库,并从此存储库安装 AzureRMAzureStack 模块:

# 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

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

 Install-Module -Name Az -Repository $RepoName -RequiredVersion 1.10.0 -Scope AllUsers
# 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

Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.0.2-preview -AllowPrerelease -Scope AllUsers

Install-Module -Name Az -Repository $RepoName -RequiredVersion 0.10.0-preview -Scope AllUsers

确认已安装 PowerShell

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

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

7.使用 Az 模块

可以使用基于 Azure 资源管理器的 cmdlet 和代码示例。 但是,你需要更改模块和 cmdlet 的名称。 模块名称已更改,以便 AzureRM 和 Azure 变为 Az,对于 cmdlet 也是如此。 例如,AzureRM.Compute 模块已重命名为 Az.Compute. New-AzureRMVM 已变为 New-AzVM,并且 Get-AzureStorageBlob 现在为 Get-AzStorageBlob

有关将 AzurRM 脚本移到 Az 中和 Azure Stack Hub 的 Az 模块中的中断性变更的更详尽讨论和指导,请参阅从 AzureRM 迁移到 Azure PowerShell Az

已知问题

安装 Az 模块时引发错误

  • 适用于:此问题适用于 2002 及更高版本
  • 原因:安装模块时引发错误。 错误消息的开头为:Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'.,错误消息也可能包含以下文本:PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
  • 补救措施:请在同一会话中运行以下 cmdlet:
    Install-Module PowershellGet -MinimumumVersion 2.3.0 -Force
    关闭会话并启动权限提升的新 PowerShell 会话。
  • 发生次数:通用

安装 Az 模块时,错误地引发“需要管理员权限”错误

  • 适用于:此问题适用于 2002 及更高版本
  • 原因:在提升的提示符下安装模块时,会引发错误。 错误指出“Administrator rights required”。
  • 补救措施:关闭会话并启动权限提升的新 PowerShell 会话。 请确保会话中没有加载现有的 Az. Accounts 模块。
  • 发生次数:通用

使用 2020-09-01-hybrid 配置文件时,Cmdlet New-AzVmss 失败

  • 适用:此问题适用于 2020-09-01-hybrid 配置文件。
  • 原因:cmdlet New-AzVmss 不适用于 020-09-01-hybrid 配置文件。
  • 修正:使用模板创建虚拟机规模集。 可以在 GitHub 存储库 AzureStack-QuickStart-Templates/101-vmss-windows-vm 中找到 Azure Stack Hub 资源管理器模板的示例,还可以找到有关将 Azure Stack Hub 资源管理器和 Visual Studio Code 结合使用的说明。
  • 发生次数:通用

后续步骤