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

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

Para obter mais informações sobre os módulos do AzureStack, confira PSGallery.

Este artigo explica como instalar o Azure PowerShell Az e os módulos de administrador compatíveis do Azure Stack Hub 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 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.

Se você quiser instalar o módulo AzureRM (Módulos de Recursos do PowerShell) para o Azure Stack Hub, confira Instalar o módulo AzureRM do PowerShell para o Azure Stack Hub.

Importante

Não haverá novas versões de módulo dos Módulos de Recursos do Azure. Os módulos dos Módulos de Recursos do Azure têm suporte apenas para correções críticas. No futuro, haverá apenas versões Az para o Azure Stack Hub.

Você pode usar 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 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, 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 Azure Resource Manager PowerShell 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 têm suporte no Azure Stack Hub com a Atualização 2002 ou posterior e com os hotfixes atuais instalados. Confira as notas sobre a versão do Azure Stack Hub para obter mais informações.

Os módulos Azure PowerShell Az funcionam com o PowerShell 5.1 ou superior no Windows ou o 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. Desinstalar versões existentes dos módulos do PowerShell do Azure Stack Hub

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

1. 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ê ocorrer 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 o Uninstall-Module não tiver sido bem-sucedido, exclua todas as pastas que começam com Azure, Azou Azs. dos locais $env:PSModulePath. Para 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. Excluir essas pastas remove todos os módulos Azure PowerShell existentes.

4. Conectado: Instalar com conectividade com a Internet

O módulo do Azure Stack Az funcionará com o PowerShell 5.1 ou superior em um computador Windows ou 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 comando a seguir 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 a sessão do PowerShell e abra uma nova sessão do PowerShell para que a atualização entre em vigor.

3. Execute o seguinte 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
   

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 o Azure Resource Manager disponível em 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 tem conectividade com a Internet. Em seguida, você os transfere para o ASDK (Azure Stack Development Kit) 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 PowerShell do Azure Stack Hub 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 NuGet em sua estação de trabalho desconectada.
5. Confirme a instalação do PowerShell.

Instalar o PowerShell do Azure Stack Hub

1. Você pode usar módulos AzureRM ou Az . O código a seguir salva módulos Az do repositório https://www.powershellgallery.com/online confiável .

   [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 do AzureStack.

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

Observação

Em computadores sem uma conexão com a Internet, é recomendável executar o cmdlet a seguir para desabilitar a coleta de dados de telemetria. Você pode enfrentar uma degradação de desempenho dos cmdlets sem desabilitar a coleta de dados de telemetria. Isso é aplicável somente para os 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 NuGet em sua estação de trabalho desconectada. Para obter instruções, consulte Inicializando manualmente o provedor 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 AzureStack 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. Instale os módulos do AzureStack.

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.4.0 -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 que um servidor proxy acesse a Internet, primeiro você configura o PowerShell para usar um servidor proxy existente:

1. Abra um prompt do PowerShell elevado.

2. Execute os comandos a seguir:

   #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 nos módulos do AzureRM. No entanto, você desejará alterar o nome dos módulos e cmdlets. Os nomes dos módulos foram alterados para que 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 do AzurRM para o Az e alterações interruptivas no módulo Az do Azure Stack Hub, consulte Migrar do AzureRM para Azure PowerShell Az.

Problemas conhecidos

Erro gerado ao instalar os módulos Az

• Aplicável: esse problema se aplica a 2002 e posterior
• 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."
• 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 gerará falsamente Administração direitos necessários

• Aplicável: esse problema se aplica a 2002 e posterior
• Causa: ao instalar o módulo 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 New-AzVmss de cmdlet falha ao usar o perfil 2020-09-01-hybrid

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

Erro gerado ao executar um script do PowerShell

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

• 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. 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 chame comandos do 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 estiver instalado, o script gerará erros.

• Correção: desinstale o módulo AzureRM e instale o módulo Az. Para obter instruções, confira Instalar o módulo Az do PowerShell para o Azure Stack Hub. Se você estiver usando as Ferramentas do Azure Stack Hub, use as ferramentas do Az. Clone o repositório de ferramentas do branch az ou baixe o AzureStack-Tools do branch az . Para obter instruções, confira Baixar ferramentas do Azure Stack Hub do GitHub

• Ocorrência: comum

Erro gerado com New-AzADServicePrincipal e New-AzADApplication

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

• Causa: o Azure Active Directory Graph introduziu uma alteração interruptiva para restringir o para que os IdentifierUri aplicativos do Active Directory sejam os subdomínios de um domínio verificado no diretório. Antes da alteração, essa restrição só era imposta 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 princípio 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 deverá ser da forma de <foo>.contoso.onmicrosoft.com. Use o seguinte cmdlet:

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

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

  • Crie o aplicativo Microsoft Entra 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

Erro: "Falha na autenticação SharedTokenCacheCredential"

• Aplicável: esse problema se aplica a todas as versões com suporte.
• Causa: um erro de falha na autenticação SharedTokenCacheCredential é gerado ao ter várias versões do AzAccounts instaladas com o Módulo do PowerShell do Azure Stack Hub versão 2.1.1.
• Correção: remova todas as versões do AzAccounts e instale apenas o AzAccounts versão 2.2.8 com suporte.
• Ocorrência: comum

Próximas etapas

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