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

Azure PowerShell a Resource Manager do Azure (AzureRM) fornece um conjunto de cmdlets que utilizam o modelo de Resource Manager do Azure para gerir os seus recursos do Azure Stack Hub.

Também tem de utilizar perfis de API para especificar os pontos finais compatíveis para os fornecedores de recursos do Azure Stack Hub.

Os perfis de API fornecem uma forma de gerir as diferenças de versões 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 cloud tem um conjunto de perfis de versão de API suportados. Por exemplo, o Azure Stack Hub suporta uma versão de perfil específica, como 2019-03-01-hybrid. Quando instala um perfil, os módulos do Azure Resource Manager PowerShell que correspondem ao perfil especificado são instalados.

Pode instalar módulos do PowerShell compatíveis com o Azure Stack Hub em cenários ligados à Internet, parcialmente ligados ou desligados. Este artigo explica-lhe as instruções detalhadas para estes cenários.

Também pode executar os módulos do Azure Resource Manager para o Azure Stack Hub num contentor do Docker. Para obter instruções, veja Utilizar o Docker para executar o PowerShell para o Azure Stack Hub.

1. Verifique os pré-requisitos

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

• Versão 5.1 do PowerShell
  Para verificar a sua versão, execute $PSVersionTable.PSVersion e compare a versão Principal . Se não tiver o PowerShell 5.1, siga a Windows PowerShell De Instalação.

  Nota

  O PowerShell 5.1 necessita de um computador Windows.

• Execute o PowerShell numa linha de comandos elevada.

• Galeria do PowerShell acesso
  Precisa de acesso ao Galeria do PowerShell. A galeria é o repositório central do conteúdo do PowerShell. O módulo PowerShellGet contém cmdlets para detetar, instalar, atualizar e publicar artefactos do PowerShell. Exemplos destes artefactos são módulos, recursos DSC, capacidades de função e scripts do Galeria do PowerShell e outros repositórios privados. Se estiver a utilizar o PowerShell num cenário desligado, tem de obter recursos de um computador com ligação à Internet e armazená-los numa localização acessível ao computador desligado.

2. Validar a acessibilidade do Galeria do PowerShell

Valide se a PSGallery está registada como um repositório.

Abra uma linha de comandos elevada do PowerShell 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 registado, 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, certifique-se de que desinstala todos os módulos do Azure Stack Hub do Azure Resource Manager PowerShell instalados anteriormente. Desinstale os módulos com um dos dois métodos seguintes:

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 tiver atingido um erro como "O módulo já está a ser utilizado", feche as sessões do PowerShell que estão a utilizar os módulos e execute novamente o script acima.

2. Elimine todas as pastas que começam com Azureou Azs.Az das C:\Program Files\WindowsPowerShell\Modules pastas eC:\Users\{yourusername}\Documents\WindowsPowerShell\Modules. A eliminação destas pastas remove todos os módulos existentes do PowerShell.

4. Ligado: Instalar o PowerShell para o Azure Stack Hub com conectividade à Internet

O perfil da 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 está a executar.

Instalar o PowerShell do Azure Stack Hub

Execute o seguinte script do PowerShell para instalar estes módulos na 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 ao executar 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 apresentados na saída.

5. Desligado: Instalar o PowerShell sem uma ligação à Internet

Num cenário desligado, primeiro transfere os módulos do PowerShell para um computador com conectividade à Internet. Em seguida, transfere-os para o Azure Stack Development Kit (ASDK) para instalação.

Inicie sessão num computador com conectividade à Internet e utilize os seguintes scripts para transferir 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 passos:

1. Instale o PowerShell do Azure Stack Hub num computador ligado.
2. Ative funcionalidades de armazenamento adicionais.
3. Transporte os pacotes do PowerShell para a estação de trabalho desligada.
4. Arranque manualmente o fornecedor NuGet na estação de trabalho desligada.
5. Confirme a instalação do PowerShell.

Instalar o PowerShell do Azure Stack Hub

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

Adicionar os pacotes à estação de trabalho

1. Copie os pacotes transferidos para um dispositivo USB.

2. Inicie sessão na estação de trabalho desligada e copie os pacotes do dispositivo USB para uma localização na estação de trabalho.

3. Arranque manualmente o fornecedor NuGet na estação de trabalho desligada. Para obter instruções, consulte o artigo Iniciar manualmente o programa de arranque do fornecedor NuGet num computador que não esteja ligado à Internet.

4. Registe esta localização como o repositório predefinido e instale os módulos e AzureStack Resource Manager do Azure 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 ao executar o seguinte comando:

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

6. Configurar o PowerShell para utilizar um servidor proxy

Em cenários que requerem um servidor proxy para aceder à Internet, primeiro configura o PowerShell para utilizar 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 do método

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

  O erro seguinte indica que os módulos Resource Manager do Azure e os módulos do 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 em conflito.

  Se quiser utilizar os módulos do Azure Resource Manager, desinstale os módulos do Az. Em alternativa, desinstale o Azure Resource Manager se quiser utilizar os módulos do Az. Feche a sessão do PowerShell e desinstale os módulos do Az ou do Azure Resource Manager.

  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 com Microsoft Entra ID.

• Causa: o Azure Active Directory Graph introduziu uma alteração interruptiva para restringir os IdentifierUri subdomínios de um domínio verificado no diretório para as aplicações do Active Directory. Antes da alteração, esta restrição só era imposta para as aplicações multi-inquilino. Agora, esta restrição também se aplica a aplicações de inquilino ú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: pode contornar esta restrição de duas formas.

  • Terá de utilizar um nome principal de serviço que seja um subdomínio do inquilino do diretório. Por exemplo, se o diretório for contoso.onmicrosoft.com, o nome do principal de serviço tem de ser da forma de <foo>.contoso.onmicrosoft.com. Utilize o seguinte cmdlet:

    NewAzureRMADServicePrincipal -Role Owner -DisplayName <foo>.contoso.onmicrosoft.com
    

    Para obter mais informações sobre a identidade e a utilização de principais de serviço com o Azure Stack Hub, veja Descrição geral dos fornecedores de identidade do Azure Stack Hub.

  • Crie a aplicação Microsoft Entra que fornece um valor válido IdentifierUri e, em seguida, crie o principal de serviço que associa a aplicação com o seguinte cmdlet:

    $app=NewAzureRMAdApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.onmicrosoft.com
    NewAzureRMADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId
    

• Ocorrência: Comum

Passos seguintes

• Transferir ferramentas do Azure Stack Hub a partir do GitHub
• Configurar o ambiente do PowerShell do utilizador do Azure Stack Hub
• Configurar o ambiente do PowerShell do operador Azure Stack Hub
• Gerir os perfis de versões das APIs no Azure Stack Hub