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

Azure PowerShell Azure Resource Manager (AzureRM) fornece um conjunto de cmdlets que usam o modelo de Resource Manager do Azure 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 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 2019-03-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 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 o Azure Stack Hub.

1. Verificar seus pré-requisitos

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

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

  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 ter acesso ao Galeria do PowerShell. A galeria é o repositório central para 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 do Galeria do PowerShell e 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 computador desconectado.

2. Validar a acessibilidade do Galeria do PowerShell

Valide se 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 elevada do PowerShell e execute o seguinte comando:

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

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 PowerShell instalados anteriormente no Azure Stack Hub. 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. Exclua todas as pastas que começam com Azureou AzAzs. das C:\Program Files\WindowsPowerShell\Modules pastas e C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules . Excluir essas pastas remove todos os módulos existentes do PowerShell.

4. Conectado: Instalar o PowerShell para o 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 AzureRm de usuário ou módulos de visualização do Az. O uso dos módulos Az requer o Azure Stack Hub 2002 ou posterior.

Para usar 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: Instalar o PowerShell sem uma 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 2002 ou posterior.

Você pode usar os módulos do Azure Resource Manager ou da versão prévia do Az. Para módulos Az, consulte 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 uma conexão com a Internet, recomendamos 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-AzureRmDataCollection

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 módulos e AzureStack Resource Manager do Azure 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 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
   

Problema conhecido

Erro de get_SerializationSettings de método

• Causa: o módulo Az do PowerShell e os módulos de Resource Manager do Azure 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 de Resource Manager do Azure, 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 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 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:

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

• 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