Instalar o módulo AZ do PowerShell para Azure Stack Hub

este artigo explica como instalar os Azure PowerShell Az e os módulos de administrador de Hub Azure Stack compatíveis usando o PowerShellGet. os módulos Az podem ser instalados em plataformas Windows, macOS e Linux.

Você também pode executar os módulos AZ para Azure Stack Hub em um contêiner do Docker. Para obter instruções, consulte usar o Docker para executar o PowerShell para Azure Stack Hub.

Se você quiser instalar o módulo AzureRM (módulos de recursos do PowerShell) para o Hub Azure Stack, consulte instalar o módulo AzureRM do PowerShell para o hub Azure Stack.

Importante

Provavelmente não haverá novas versões de módulo dos módulos de recursos do Azure. Os módulos de módulos de recursos do Azure estão em suporte apenas para correções críticas. No futuro, só haverá AZ releases para Azure Stack Hub.

Você pode usar perfis de API para especificar os pontos de extremidade compatíveis para os provedores de recursos do Hub de Azure Stack.

Os perfis de API fornecem uma maneira de gerenciar diferenças de versão entre o Azure e o Hub de Azure Stack. Um perfil de versão de API é um conjunto de módulos Azure Resource Manager PowerShell com versões de API específicas. Cada plataforma de nuvem tem um conjunto de perfis de versão de API com suporte. Por exemplo, Azure Stack Hub dá suporte a uma versão de perfil específica, como 2020-09-01-híbrido. Quando você instala um perfil, o Azure Resource Manager módulos do PowerShell que correspondem ao perfil especificado são instalados.

Você pode instalar Azure Stack módulos AZ do PowerShell compatíveis com o Hub em cenários conectados à Internet, parcialmente conectados ou desconectados. Este artigo orienta você pelas instruções detalhadas para esses cenários.

1. verifique seus pré-requisitos

Os módulos AZ têm suporte no Hub Azure Stack com a atualização 2002 ou posterior e com os hotfixes atuais instalados. Consulte as notas de versão do Hub Azure Stack para obter mais informações.

os módulos Az Azure PowerShell funcionam com o powershell 5,1 ou superior no Windows ou no powershell Core 6. x e posterior em todas as plataformas. Você deve instalar a versão mais recente do PowerShell Core disponível para seu sistema operacional. Azure PowerShell não tem outros requisitos quando executado no PowerShell Core.

Para verificar sua versão do PowerShell, execute o comando:

$PSVersionTable.PSVersion

Pré-requisitos para Windows

Para usar o Azure PowerShell no PowerShell 5.1 no Windows:

  1. Atualize para o Windows PowerShell 5.1 se necessário. Se você estiver usando o Windows 10, você já tem o PowerShell 5.1 instalado.
  2. Instale o .NET Framework 4.7.2 ou posterior.
  3. Verifique se tem a versão mais recente do PowerShellGet. Execute os seguintes cmdlets em um prompt com privilégios elevados:
[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. pré-requisitos para Linux e Mac

O PowerShell Core 6. x ou versão posterior é necessário. Siga o link para obter instruções

3. desinstale as versões existentes dos módulos do PowerShell do hub de Azure Stack

Antes de instalar a versão necessária, certifique-se de desinstalar todos os módulos de Azure Stack Hub instalados anteriormente Azure Resource Manager ou AZ PowerShell. Desinstale os módulos usando um dos dois métodos a seguir:

  1. Para desinstalar os módulos existentes de Azure Resource Manager e AZ PowerShell, feche todas as sessões ativas do PowerShell e execute os seguintes 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
    

    Se você encontrar um erro como ' o módulo já está em uso ', feche as sessões do PowerShell que estão usando os módulos e execute novamente o script acima.

  2. Se a Uninstall-Module não tiver sido concluída com sucesso, exclua todas as pastas que começam com Azure , Az , ou Azs. da $env:P smodulepath locais. por Windows PowerShell, os locais podem ser C:\Program Files\WindowsPowerShell\Modules e C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules . Para o PowerShell Core, os locais podem ser C:\Program Files\PowerShell\7\Modules e C:\Users\{yourusername}\Documents\PowerShell\Modules . a exclusão dessas pastas remove os módulos existentes do Azure PowerShell.

4. Connected: instalar com conectividade com a Internet

o módulo Az Azure Stack funcionará com o powershell 5,1 ou superior em uma máquina Windows ou no powershell 6. x ou superior em uma plataforma Linux ou macOS. O uso dos cmdlets do PowerShellGet é o método de instalação preferencial. Esse método funciona da mesma forma nas plataformas com suporte.

  1. Execute o seguinte comando de uma sessão do PowerShell para atualizar o PowerShellGet para um mínimo de 2.2.3 de versão

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    
    Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force
    
  2. Feche a sessão do PowerShell e abra uma nova sessão do PowerShell para que a atualização possa entrar em vigor.

  1. Execute o seguinte comando em uma sessão do 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.2.0 
    
  1. Execute o seguinte comando em uma sessão do 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
    

Aviso

você não pode ter os módulos Azure Resource Manager (AzureRM) e Az instalados para o PowerShell 5,1 para Windows ao mesmo tempo. Se você precisar manter Azure Resource Manager disponíveis no seu sistema, instale o módulo AZ para o PowerShell Core 6. x ou posterior. Para fazer isso, instale o PowerShell Core 6.x ou posterior e, depois, siga estas instruções em um terminal do PowerShell Core.

5. desconectado: instalar sem conexão com a Internet

Em um cenário desconectado, primeiro você baixa os módulos do PowerShell para um computador que tenha conectividade com a Internet. Em seguida, você os transfere para a Kit de Desenvolvimento do Azure Stack (ASDK) para instalação.

Entre em um computador com conectividade com a Internet e use os scripts a seguir para baixar o Azure Resource Manager e Azure Stack pacotes de Hub, dependendo da sua versão do hub de Azure Stack.

A instalação tem cinco etapas:

  1. Instale o PowerShell do Hub Azure Stack em um computador conectado.
  2. Habilite recursos de armazenamento adicionais.
  3. Transporte os pacotes do PowerShell para sua estação de trabalho desconectada.
  4. inicialize manualmente o provedor de NuGet em sua estação de trabalho desconectada.
  5. Confirme a instalação do PowerShell.

Instalar o PowerShell do hub de Azure Stack

Azure Stack Hub 2108 ou posterior.

Você pode usar os módulos Azure Resource Manager ou AZ. Para Azure Resource Manager, consulte as instruções em instalar o módulo AzureRM do PowerShell. O código a seguir salva módulos do repositório online confiável 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
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.2.0

Azure Stack Hub 2102.

Você pode usar os módulos Azure Resource Manager ou AZ. Para Azure Resource Manager, consulte as instruções em instalar o módulo AzureRM do PowerShell. O código a seguir salva módulos do repositório online confiável 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
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.1.1

Observação

Em computadores sem uma conexão com a Internet, é recomendável executar o seguinte cmdlet para desabilitar a coleta de dados de telemetria. Você pode enfrentar uma degradação do desempenho dos cmdlets sem desabilitar a coleta de dados de telemetria. Isso é aplicável somente para computadores sem conexões com a Internet

Disable-AzDataCollection

Adicionar seus pacotes à sua estação de trabalho

  1. Copie os pacotes baixados para um dispositivo USB.

  2. Entre na estação de trabalho desconectada e copie os pacotes do dispositivo USB para um local na estação de trabalho.

  3. inicialize manualmente o provedor de NuGet em sua estação de trabalho desconectada. para obter instruções, consulte inicializar manualmente o provedor de NuGet em um computador que não está conectado à internet.

  4. Registre esse local como o repositório padrão e instale os AzureRM módulos e deste AzureStack repositório:

 # 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.2.0 -Scope AllUsers

 Install-Module -Name Az -Repository $RepoName -RequiredVersion 2.0.1 -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.1.1 -Scope AllUsers

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

Confirmar a instalação do PowerShell

Confirme a instalação executando o seguinte comando:

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

6. configurar o PowerShell para usar um servidor proxy

Em cenários que exigem um servidor proxy para acessar a Internet, primeiro você configura o PowerShell para usar um servidor proxy existente:

  1. Abra um prompt do PowerShell elevado.

  2. Execute os seguintes comandos:

    #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. usar o módulo AZ

Você pode usar os cmdlets e exemplos de código com base em Azure Resource Manager. No entanto, você vai querer alterar o nome dos módulos e cmdlets. Os nomes de módulo foram alterados para que o AzureRM e o Azure se tornem Az e o mesmo para cmdlets. Por exemplo, o módulo AzureRM.Compute foi renomeado para Az.Compute. New-AzureRMVM se tornou New-AzVM, e Get-AzureStorageBlob agora é Get-AzStorageBlob.

Para obter uma discussão mais completa e diretrizes para mover o script AzurRM para AZ e interromper alterações no módulo AZ Azure Stack Hub, consulte migrar de AzureRM para Azure PowerShell AZ.

Problemas conhecidos

Erro gerado ao instalar os módulos AZ

  • Aplicável: esse problema se aplica ao 2002 e posterior
  • Causa: ao instalar o módulo, um erro é gerado. A mensagem de erro é iniciada: Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. ou a mensagem de erro pode incluir o seguinte texto: PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
  • Correção: execute o seguinte cmdlet na mesma sessão:
    Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
    Feche a sessão e inicie uma nova sessão do PowerShell com privilégios elevados.
  • Ocorrência: comum

Ao instalar o módulo AZ, o erro de direitos de administrador é requerido por false

  • Aplicável: esse problema se aplica ao 2002 e posterior
  • Causa: ao instalar o módulo a partir de um prompt com privilégios elevados, um erro é gerado. O erro diz, Administrator rights required .
  • Correção: Feche a sessão e inicie uma nova sessão do PowerShell com privilégios elevados. Verifique se não há um AZ existente. Módulo de contas carregado na sessão.
  • Ocorrência: comum

O cmdlet New-AzVmss falha ao usar o perfil 2020-09-01-híbrido

  • Aplicável: esse problema se aplica ao perfil 2020-09-01-híbrido.
  • Causa: o cmdlet New-AzVmss não funciona com o perfil 2020-09-01-híbrido.
  • Correção: Use um modelo para criar um conjunto de dimensionamento de máquinas virtuais. você pode encontrar um exemplo de modelos do gerenciador de recursos do Hub de Azure Stack no repositório de GitHub AzureStack-QuickStart-templates/101-vmss-windows-vm e encontrar instruções sobre como usar os gerenciadores de recursos de Hub Azure Stack com Visual Studio Code.
  • Ocorrência: comum

Erro gerado ao executar um script do PowerShell

  • Aplicável: esse problema se aplica ao 2002 e posterior.

  • Causa: ao executar scripts ou comandos do PowerShell usando os módulos específicos do Hub Azure Stack, você precisará do seu script ou comando para estar disponível no módulo. Você poderá ver o seguinte erro:

    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.
    

    O módulo atual é o módulo AZ do PowerShell, que substituiu o módulo AzureRM do PowerShell. Se você tentar executar um script que chama comandos AzureRM quando o módulo AZ estiver instalado, o script gerará erros. Ou, se você tentar executar um script que chama comandos AZ quando o módulo AzureRM for instalado, o script gerará erros.

  • Correção: desinstale o módulo AzureRM e instale o módulo AZ. Para obter instruções, consulte instalar o PowerShell AZ Module para Azure Stack Hub. Se você estiver usando as ferramentas de Hub de Azure Stack, use as ferramentas AZ. Clone o repositório de ferramentas do Branch AZ ou baixe o AzureStack-Tools da ramificação AZ . Para obter instruções, consulte baixar ferramentas de Hub de Azure Stack do GitHub

  • Ocorrência: comum

Erro gerado com New-AzADServicePrincipal e New-AzADApplication

  • Aplicável: Azure Stack ambientes usando o Azure Active Directory (AD do Azure).

  • causa: Azure Active Directory Graph introduziu uma alteração significativa para restringir o IdentifierUri para que os aplicativos de Active Directory sejam os subdomínios de um domínio verificado no diretório. Antes da alteração, essa restrição foi imposta somente para os aplicativos multilocatários. Agora, essa restrição também se aplica a aplicativos de locatário único. A alteração resultará no seguinte erro: Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running .

  • Correção: você pode contornar essa restrição de duas maneiras.

    • Você precisará usar um nome de entidade de serviço que seja um subdomínio do locatário do diretório. Por exemplo, se o diretório for contoso.onmicrosoft.com , o nome da entidade de serviço deve estar no formato de <foo>.contoso.onmicrosoft.com . Use o seguinte cmdlet:

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

      Para obter mais informações sobre a identidade e o uso de entidades de serviço com o Hub Azure Stack, consulte visão geral dos provedores de identidade para Azure Stack Hub.

    • Crie o aplicativo do Azure AD fornecendo um válido IdentifierUri e, em seguida, crie a entidade de serviço associando o aplicativo usando o seguinte cmdlet:

      $app=New-AzADApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.onmicrosoft.com
      New-AzADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId
      
  • Ocorrência: comum

Próximas etapas