Instalar os módulos PowerShell Az e Azure Stack para o Azure Stack Hub

Importante

Todas as versões do módulo PowerShell do Azure Resource Manager (AzureRM) estão desatualizadas e sem suporte. O módulo Az PowerShell agora é o módulo PowerShell recomendado para interagir com o Azure e o Azure Stack Hub. Este artigo descreve como começar a usar o módulo Az PowerShell. Para obter informações sobre como migrar para o módulo Az PowerShell, consulte migrar do AzureRM para o Azure PowerShell Az no Azure Stack Hub. Para obter detalhes sobre o aumento da funcionalidade dos módulos Az, que foram adotados no Azure global, consulte Introdução ao módulo Azure Az PowerShell.

Versão do Azure Stack Hub	Versão do AzureStack PowerShell
2102	2.1.1
2108	2.2.0
2206	2.3.0
2301+	2.4.0

Para obter mais informações sobre módulos AzureStack, consulte o PSGallery.

Este artigo explica como instalar o Azure PowerShell Az e os módulos de administrador compatíveis do Azure Stack Hub usando PowerShellGet. Você pode instalar os módulos Az nas plataformas Windows, macOS e Linux.

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

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

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

Você pode instalar módulos do PowerShell Az compatíveis com o Azure Stack 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 são suportados no Azure Stack Hub com a atualização 2002 ou posterior e com todos os hotfixes atuais instalados. Consulte as notas de versão do Azure Stack Hub para obter mais informações.

Os módulos Az do Azure PowerShell funcionam com o PowerShell 5.1 ou superior no Windows ou 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. O 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 Windows PowerShell 5.1 se necessário. Se você estiver no Windows 10, já tem o PowerShell 5.1 instalado.

2. Instale .NET Framework 4.7.2 ou posterior.

3. Verifique se você tem a versão mais recente do PowerShellGet. Execute os seguintes cmdlets a partir de um prompt elevado:

   [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
   

Pré-requisitos para Linux e Mac

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

Desinstalar versões existentes dos módulos do PowerShell do Azure Stack Hub

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

• Para desinstalar os módulos existentes do Azure Resource Manager e do 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 usam os módulos e execute novamente esses cmdlets.

• Se Uninstall-Module não tiver êxito, exclua todas as pastas que começam com Azure, Azou Azs dos locais $env:PSModulePath. Para o 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 todos os módulos existentes do Azure PowerShell.

Conectado: Instale com conectividade à Internet

O módulo Azure Stack Az funciona com o PowerShell 5.1 ou superior em uma máquina Windows ou PowerShell 6.x ou superior em uma plataforma Linux ou macOS. Usar os cmdlets PowerShellGet é o método de instalação preferencial. Este método funciona da mesma forma nas plataformas suportadas.

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

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

2. Feche sua sessão do PowerShell e abra uma nova sessão do PowerShell para que a atualização possa entrar em vigor.

3. Execute os seguintes comandos para instalar os módulos Az:

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

4. Instale os módulos do PowerShell do AzureStack:

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

Desconectado: Instalar sem conexão com a Internet

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

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

A instalação tem cinco etapas:

1. Instale o Azure Stack Hub PowerShell em uma máquina conectada.
2. Habilite recursos de armazenamento adicionais.
3. Transporte os pacotes do PowerShell para sua estação de trabalho desconectada.
4. Inicialize manualmente o provedor NuGet em sua estação de trabalho desconectada.
5. Confirme a instalação do PowerShell.

Instalar o Azure Stack Hub PowerShell

1. O código a seguir instala módulos Az a partir do confiável repositório on-line :

   [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. Depois que os módulos Az forem instalados, prossiga com a instalação dos módulos AzureStack:

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

Observação

Em máquinas sem conexão com a Internet, recomendamos que você execute o cmdlet Disable-AzDataCollection para desabilitar a coleta de dados de telemetria. Caso contrário, você pode experimentar uma degradação do desempenho dos cmdlets. Isto aplica-se apenas a máquinas sem ligação à Internet.

Adicione 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 NuGet em sua estação de trabalho desconectada. Para obter instruções, consulte inicializando manualmente o provedor NuGet em uma máquina que não está conectada à Internet.

4. Registre esse local como o repositório padrão e instale os módulos AzureRM e AzureStack a partir deste 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
   

5. Instale os módulos Az.

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

6. Instalar os módulos AzureStackL

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

Confirme a instalação do PowerShell

Confirme a instalação executando o seguinte comando:

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

Configurar o PowerShell para usar um servidor proxy

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

1. Abra um prompt do PowerShell com privilégios elevados.

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
   

Use o módulo Az

Você ainda pode usar os cmdlets e exemplos de código com base nos módulos do AzureRM. No entanto, é necessário alterar o nome dos módulos e dos cmdlets. Os nomes dos módulos foram alterados de modo que AzureRM e Azure se tornem Aze o mesmo para cmdlets. Por exemplo, o módulo AzureRM.Compute foi renomeado para Az.Compute. New-AzureRMVM é New-AzVM, e Get-AzureStorageBlob agora é Get-AzStorageBlob.

Para obter uma discussão mais aprofundada e orientações para mover scripts do AzureRM para Az e informações sobre alterações significativas no módulo Az do Azure Stack Hub, consulte Migrar do AzureRM para o Azure PowerShell Az.

Problemas conhecidos

Erro gerado ao instalar os módulos Az

• Aplicável: Esta questão aplica-se a 2002 e seguintes
• Causa: Ao instalar o módulo, um erro é gerado. A mensagem de erro começa: 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."
• Remediaçã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 elevada do PowerShell.
• Ocorrência: Comum

Ao instalar o módulo Az, incorretamente surge o erro "Direitos de administrador necessários".

• Aplicável: Esta questão aplica-se a 2002 e seguintes
• Causa: Ao instalar o módulo a partir de um prompt elevado, um erro é gerado. O erro diz: Administrator rights required.
• Remediação: feche sua sessão e inicie uma nova sessão elevada do PowerShell. Certifique-se de que não existe um Az. Módulo de contas carregado na sessão.
• Ocorrência: Comum

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

• Aplicável: Este problema aplica-se ao perfil híbrido 2020-09-01.
• Causa: O cmdlet New-AzVmss não funciona com o perfil híbrido 2020-09-01.
• Remediação: use um modelo para criar um conjunto de escalonamento de máquinas virtuais. Você pode encontrar um exemplo dos modelos do Azure Stack Hub Resource Manager no repositório GitHub AzureStack-QuickStart-Templates/101-vmss-windows-vm e pode encontrar instruções sobre como usar os Gerenciadores de Recursos do Hub do Azure Stack com Visual Studio Code.
• Ocorrência: Comum

Erro gerado ao executar um script do PowerShell

• Aplicável: Este problema aplica-se a 2002 e posteriores.

• Causa: ao executar scripts ou comandos do PowerShell usando os módulos específicos do Azure Stack Hub, você precisará que seu script ou comando esteja disponível no módulo. 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, seu script gerará erros. Ou se você tentar executar um script que chama comandos Az quando o módulo AzureRM estiver instalado, seu script gerará erros.

• Remediação: desinstale o módulo AzureRM e instale o módulo Az. Para obter instruções, consulte Instalar o módulo PowerShell Az para o Azure Stack Hub. Se estiveres a usar as Ferramentas do Azure Stack Hub, utiliza as Ferramentas Az. Clone o repositório de ferramentas da ramificação az ou baixe o AzureStack-Tools da ramificação az. Para obter instruções, consulte Baixar ferramentas do Azure Stack Hub do GitHub

• Ocorrência: Comum

Erro lançado com New-AzADServicePrincipal e New-AzADApplication

• Aplicável: ambientes do Azure Stack usando o Microsoft Entra ID.

• Causa: o Azure Active Directory Graph introduziu uma alteração significativa para restringir o IdentifierUri dos aplicativos do Active Directory a serem os subdomínios de um domínio verificado no diretório. Antes da alteração, essa restrição só era aplicada para os aplicativos multilocatário. 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.

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

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

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

    Para mais informações sobre identidade e uso de principais de serviço com o Azure Stack Hub, consulte Visão geral de provedores de identidade para o Azure Stack Hub.

  • Crie a aplicação Microsoft Entra fornecendo um IdentifierUri válido e, em seguida, crie o principal de serviço associando a aplicação 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

Erro: "Falha na autenticação SharedTokenCacheCredential"

• Aplicável: este problema aplica-se a todas as versões suportadas.
• Causa: um erro de autenticação SharedTokenCacheCredential é lançado ao existirem múltiplas versões do AzAccounts instaladas com o Módulo PowerShell do Azure Stack Hub versão 2.1.1.
• Remediação: Remova todas as versões do AzAccounts e instale apenas o AzAccounts suportado versão 2.2.8.
• Ocorrência: Comum

Próximos passos

• Baixe as ferramentas do Azure Stack Hub do GitHub
• Configurar o ambiente PowerShell do usuário do Azure Stack Hub
• Configurar o ambiente PowerShell do operador do Azure Stack Hub
• Gerenciar perfis de versão da API no Azure Stack Hub