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

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

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 PowerShell do Azure Resource Manager com versões específicas da API. Cada plataforma de nuvem tem um conjunto de perfis de versão de API suportados. 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 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. Verifique seus pré-requisitos

Antes de começar a usar o Azure Stack Hub e o módulo PowerShell Azure Resource Manager, 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 Major . Se você não tiver o PowerShell 5.1, siga a seção Instalando o Windows PowerShell.

  Nota

  O PowerShell 5.1 requer uma máquina Windows.

• Execute o PowerShell em um prompt de comando elevado.

• Acesso à Galeria do PowerShell
  Você precisa acessar a Galeria do PowerShell. A galeria é o repositório central para o 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 DSC, recursos de função e scripts da Galeria do PowerShell e outros repositórios privados. Se você estiver usando o PowerShell em um cenário desconectado, deverá recuperar recursos de uma máquina com conexão à Internet e armazená-los em um local acessível à sua máquina desconectada.

2. Validar a acessibilidade da Galeria do PowerShell

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

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. Desinstale 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 PowerShell do Azure Stack Hub do Azure Resource Manager 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ê clicar em 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 Azure, Az ou 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 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 Azure Stack Hub PowerShell

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

# 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 

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

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

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, você primeiro baixa os módulos do PowerShell para uma máquina que tenha conectividade com a Internet. Em seguida, transfira-os para o Azure Stack Development Kit (ASDK) 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 Azure Stack Hub PowerShell em uma máquina conectada.
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 Azure Stack Hub 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

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

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

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 Inicializando manualmente o provedor NuGet em uma máquina que não está conectada à Internet.

4. Registe esta localização como o repositório predefinido e instale o Azure Resource Manager e AzureStack os módulos a partir 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, você primeiro configura o PowerShell para usar um servidor proxy existente:

1. Abra uma linha de comandos elevada do PowerShell.

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
   

Problema conhecido

Erro de get_SerializationSettings de método

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

• Remediaçã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 sua 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 o Microsoft Entra ID.

• Causa: o Azure Ative Directory Graph introduziu uma alteração de quebra para restringir os IdentifierUri aplicativos do Ative Directory a serem os subdomínios de um domínio verificado no diretório. Antes da alteração, essa restrição só era aplicada para os aplicativos multilocatário. 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.

• Remediaçã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 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óximos passos

• Baixar ferramentas do Azure Stack Hub do GitHub
• Configurar o ambiente PowerShell do usuário do Azure Stack Hub
• Configurar o ambiente PowerShell do operador do Azure Stack Hub
• Gerir os perfis de versões das APIs no Azure Stack Hub