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

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

Você também pode executar os módulos do 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 (PowerShell Resource Modules) para o Azure Stack Hub, consulte Instalar o módulo AzureRM do PowerShell para o Azure Stack Hub.

Importante

Provavelmente 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. Daqui para frente, haverá apenas versões do 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 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 Azure Stack Hub compatíveis com o PowerShell Az em cenários conectados à Internet, parcialmente conectados ou desconectados. Este artigo orienta você pelas instruções detalhadas para esses cenários.

1. Verificar 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. Consulte as notas de 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 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

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, certifique-se de desinstalar os módulos do Azure Stack Hub do Azure Resource Manager 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ê acertar 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 êxito, 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 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.

  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 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. Habilitar 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

Azure Stack Hub 2108 ou posterior.

Você pode usar módulos do Azure Resource Manager ou do Az. Para Resource Manager do Azure, consulte as instruções no módulo Instalar o AzureRM do PowerShell. O código a seguir salva módulos 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
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 módulos do Azure Resource Manager ou do Az. Para Resource Manager do Azure, consulte as instruções no módulo Instalar o AzureRM do PowerShell. O código a seguir salva módulos 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
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, recomendamos executar o cmdlet a seguir para desabilitar a coleta de dados de telemetria. Você pode experimentar 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 Inicializar manualmente o provedor NuGet em um computador que não esteja conectado à Internet.

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

 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 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 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 os exemplos de código com base no Resource Manager do Azure. 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 torne Aze 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 e diretrizes mais detalhadas para mover o script do AzurRM para o Az e alterações significativas 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 do 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 elevada do PowerShell.
  • Ocorrência: Comum

Ao instalar o módulo Az, gera falsamente Administração direitos necessários de erro

  • Aplicável: esse problema se aplica a 2002 e posterior
  • Causa: ao instalar o módulo de um prompt elevado, um erro é gerado. O erro diz: Administrator rights required
  • Correção: feche a sessão e inicie uma nova sessão elevada do PowerShell. 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 híbrido 2020-09-01

  • Aplicável: esse problema se aplica ao perfil híbrido 2020-09-01.
  • Causa: o cmdlet New-AzVmss não funciona com o perfil híbrido 2020-09-01.
  • 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 Gerenciador de Recursos 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 chama comandos do AzureRM quando o módulo Az estiver instalado, o script gerará erros. Ou se você tentar executar um script que chama comandos do Az quando o módulo AzureRM estiver instalado, o script gerará erros.

  • Correção: desinstale o módulo do AzureRM e instale o módulo Az. Para obter instruções, consulte 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 o Azure Active Directory (Azure AD).

  • Causa: o Azure Active Directory Graph introduziu uma alteração significativa para restringir 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 a visão geral dos provedores de identidade para o Azure Stack Hub.

    • Crie o aplicativo Azure AD fornecendo um válido IdentifierUri e 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: erro de falha na autenticação SharedTokenCacheCredential ao ter várias versões do AzAccounts instaladas com o Módulo 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