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

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

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

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 PowerShell do Azure Resource Manager 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 PowerShell do Azure Resource Manager que correspondem ao perfil especificado são instalados.

Você pode instalar os 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.

Verificar seus pré-requisitos

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

Os módulos Az do PowerShell funcionam com o PowerShell 5.1 ou superior no Windows, ou com o PowerShell Core 6.x ou 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 seguinte 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 no Windows 10, já terá o PowerShell 5.1 instalado.

2. Instale o .NET Framework 4.7.2 ou posterior.

3. Verifique se você tem a versão mais recente do PowerShellGet. Execute os seguintes cmdlets em 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ário. 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, desinstale todos 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:

• 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 sido bem-sucedido, exclua todas as pastas que começam com o Azure, o Az ou o Azs dos $env:PSModulePath locais. Para o Windows PowerShell, os caminhos podem ser C:\Program Files\WindowsPowerShell\Modules e C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules. Para o PowerShell Core, as localizações podem ser C:\Program Files\PowerShell\7\Modules e C:\Users\{yourusername}\Documents\PowerShell\Modules. Excluir essas pastas remove todos os módulos existentes do Azure PowerShell.

Conectado: instalar com conectividade com a Internet

O módulo Azure Stack Az funciona com o PowerShell 5.1 ou superior em um computador Windows, ou PowerShell 6.x ou superior em uma plataforma Linux ou macOS. Usar os cmdlets do PowerShellGet é o método de instalação preferencial. Esse método funciona da mesma maneira nas plataformas com suporte.

1. Execute o seguinte comando 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 possa entrar em vigor.

3. Execute os seguintes comandos para instalar módulos do 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
   

   Install-Module -Name AzureStack -RequiredVersion 2.3.0
   

   Install-Module -Name AzureStack -RequiredVersion 2.2.0
   

   Install-Module -Name AzureStack -RequiredVersion 2.1.1
   

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. O código a seguir instala módulos Az do repositório 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 do 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
   

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

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

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

Adicione seus pacotes à 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 está conectado à Internet.

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

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

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

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.1.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

Configurar o PowerShell para usar um servidor proxy

Em cenários que exigem que um servidor proxy acesse a Internet, primeiro configure o PowerShell para usar um servidor proxy existente:

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

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
   

Usar o módulo Az

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

Para uma discussão mais completa e diretrizes sobre como mover scripts do AzureRM para o Az, além de informações sobre alterações significativas no módulo Az do Azure Stack Hub, veja Migrar do AzureRM para o Azure PowerShell Az.

Problemas conhecidos

Erro gerado ao instalar os módulos Az

• Aplicável: Este problema se aplica a 2002 e posteriores
• 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 sua sessão e inicie uma nova sessão do PowerShell com privilégios elevados.
• Ocorrência: Comum

Ao instalar o módulo Az, é gerado falsamente o erro de direitos de administrador necessários

• Aplicável: Este problema se aplica a 2002 e posteriores
• 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 sua sessão e inicie uma nova sessão elevada do PowerShell. Certifique-se de que não haja 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: utilize um modelo para criar um conjunto de escalas 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 encontrar instruções sobre como usar os Gerenciador de Recursos do Azure Stack Hub com o Visual Studio Code.
• Ocorrência: Comum

Erro gerado ao executar um script do PowerShell

• Aplicável: esse problema se aplica 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. Você pode 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, seu script gerará erros.

• Correção: desinstale o módulo 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, consulte Baixar as 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 a ID do Microsoft Entra.

• Causa: o Azure Active Directory Graph implementou uma mudança disruptiva para restringir o IdentifierUri dos aplicativos do Active Directory como 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 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 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 IdentifierUri válido e, em seguida, crie a entidade de serviço associando-a ao 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 compatíveis.
• Causa: um erro de falha na autenticação SharedTokenCacheCredential é gerado 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

• Baixar ferramentas do Azure Stack Hub no 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