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

O Azure Resource Manager (AzureRM) do Azure PowerShell fornece um conjunto de cmdlets que usam o modelo do Azure Resource Manager para gerenciar seus recursos do Azure Stack Hub.

Importante

Você está em uma página da Web de uma versão desatualizada do Azure Stack Hub do PowerShell. Todas as versões do módulo do PowerShell do Azure Resource Manager (AzureRM) estão desatualizadas e sem suporte. Os módulos do ARM não serão mais atualizados em builds futuros do Azure Stack Hub. Os módulos Az devem ser usados para builds 2002 e posteriores. Não há suporte para o perfil híbrido 2020-09-01 para módulos do ARM.

Agora, o módulo Az PowerShell é o módulo do PowerShell recomendado para interagir com o Azure e o Azure Stack Hub. Para começar a usar o módulo do Az PowerShell, confira Instalar o módulo de versão prévia do Az do PowerShell para o Azure Stack Hub. Para saber como migrar para o módulo do Az PowerShell, confira Migrar do Azure Resource Manager para o Azure PowerShell Az no Azure Stack Hub. Para obter detalhes sobre o aumento da funcionalidade dos módulos do Az, que foram adotados no Azure global, confira Introdução ao módulo do Azure Az PowerShell.

Você também precisa 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 de 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 2019-03-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 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.

Você também pode executar os módulos do Azure Resource Manager para o 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.

1. Verifique seus pré-requisitos

Antes de começar a usar o Azure Stack Hub e o módulo do Azure Resource Manager do PowerShell, você deve ter os seguintes pré-requisitos:

• PowerShell versão 5.1
  Para verificar sua versão, execute $PSVersionTable.PSVersion e compare a versão principal . Se você não tiver o PowerShell 5.1, siga Instalando o Windows PowerShell.

  Observação

  O PowerShell 5.1 requer um computador Windows.

• Execute o PowerShell em um prompt de comando com privilégios elevados.

• Acesso à Galeria do PowerShell
  Você precisa acessar a Galeria do PowerShell. A galeria é o repositório central do conteúdo do PowerShell. O módulo PowerShellGet contém cmdlets para descobrir, instalar, atualizar e publicar artefatos do PowerShell. Exemplos desses artefatos são módulos, recursos de DSC, recursos de função e scripts da Galeria do PowerShell e de outros repositórios privados. Se você estiver usando o PowerShell em um cenário desconectado, deverá recuperar recursos de um computador com uma conexão com a Internet e armazená-los em um local acessível ao seu computador desconectado.

2. Validar a acessibilidade da Galeria do PowerShell

Valide se o PSGallery está registrado como um repositório.

Observação

Esta etapa requer acesso à Internet.

Abra um prompt do PowerShell com privilégios elevados e execute os seguintes cmdlets:

Install-module -Name PowerShellGet -Force
Import-Module -Name PackageManagement -ErrorAction Stop
Get-PSRepository -Name "PSGallery"

Se o repositório não estiver registrado, abra uma sessão do PowerShell com privilégios elevados e execute o seguinte comando:

Register-PSRepository -Default
Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted

3. Desinstale as 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 PowerShell do Azure Resource Manager do Azure Stack Hub 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 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. Exclua todas as pastas que começam com Azureou Az Azs. das C:\Program Files\WindowsPowerShell\Modules pastas e C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules . A exclusão dessas pastas remove todos os módulos existentes do PowerShell.

4. Conectado: instale o PowerShell para Azure Stack Hub com conectividade com a Internet

O perfil de versão da API e os módulos do PowerShell do Azure Stack Hub necessários dependerão da versão do Azure Stack Hub que você está executando.

Instalar o PowerShell do Azure Stack Hub

Execute o seguinte script do PowerShell para instalar esses módulos em sua estação de trabalho de desenvolvimento:

Para o Azure Stack Hub 2002 ou posterior:

Você pode usar módulos do usuário AzureRm ou módulos de visualização do Az. O uso dos módulos Az requer o Azure Stack Hub 2002 ou posterior.

Para usar os módulos de visualização do Az, siga as instruções em Instalar o módulo Az do PowerShell.

# Install the AzureRM.BootStrapper module. Select Yes when prompted to install NuGet
Install-Module -Name AzureRM.BootStrapper

# Install and import the API Version Profile required by Azure Stack Hub into the current PowerShell session.
Use-AzureRmProfile -Profile 2019-03-01-hybrid -Force
Install-Module -Name AzureStack -RequiredVersion 1.8.3 

Confirmar a instalação do PowerShell

Confirme a instalação executando o seguinte comando:

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

Se a instalação for bem-sucedida, os AzureRm módulos e AzureStack serão exibidos na saída.

5. Desconectado: Instale o PowerShell sem uma conexão com a Internet

Em um cenário desconectado, primeiro baixe os módulos do PowerShell para um computador que tenha 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

Azure Stack Hub 2002 ou posterior.

Você pode usar os módulos de visualização do Azure Resource Manager ou Az. Para módulos Az, consulte as instruções em Instalar o módulo Az do PowerShell.

Install-module -Name PowerShellGet -Force 
Import-Module -Name PackageManagement -ErrorAction Stop

$Path = "<Path that is used to save the packages>"
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureRM -Path $Path -Force -RequiredVersion 2.5.0
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $Path -Force -RequiredVersion 1.8.3

Observação

Em computadores sem 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 do desempenho dos cmdlets sem desabilitar a coleta de dados de telemetria. Isso é aplicável apenas para as máquinas sem conexão com a Internet

Disable-AzureRmDataCollection

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 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 o Azure Resource Manager e AzureStack os 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"
   
   Register-PSRepository -Name $RepoName -SourceLocation $SourceLocation -InstallationPolicy Trusted
   
   Install-Module -Name AzureRM -Repository $RepoName
   
   Install-Module -Name AzureStack -Repository $RepoName
   

Confirmar a instalação do PowerShell

Confirme a instalação executando o seguinte comando:

Get-Module -Name "Azure*" -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 configure 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
   

Problema conhecido

Erro de get_SerializationSettings método

• Causa: o módulo Az do PowerShell e os módulos do Azure Resource Manager do PowerShell não são compatíveis.

  O erro a seguir indica que os módulos do Azure Resource Manager e os módulos Az são carregados na mesma sessão:

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

• Correção: desinstale os módulos conflitantes.

  Se você quiser usar os módulos do Azure Resource Manager, desinstale os módulos Az. Ou desinstale o Azure Resource Manager se quiser usar os módulos Az. Feche a sessão do PowerShell e desinstale os módulos Az ou Azure Resource Manager.

  Você pode encontrar instruções em Desinstalar versões existentes dos módulos do PowerShell do Azure Stack Hub.

Erro gerado com NewAzureRMADServicePrincipal e NewAzureRMAdApplication

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

• Causa: o Azure Active Directory Graph introduziu uma alteração significativa para restringir os IdentifierUri 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 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 deve ter a forma de <foo>.contoso.onmicrosoft.com. Use o seguinte cmdlet:

    NewAzureRMADServicePrincipal -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 do 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=NewAzureRMAdApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.onmicrosoft.com
    NewAzureRMADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId
    

• Ocorrência: Comum

Próximas etapas

• Baixar 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