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

Versão do Azure Stack Hub	Versão do AzureStack PowerShell
2102	2.1.1
2108	2.2.0
2206	2.3.0
2301+	2.4.0

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

Este artigo explica como instalar o Azure PowerShell módulos de administrador do Azure Stack Hub compatíveis com o PowerShellGet. Os módulos do Az podem ser instalados em plataformas Windows, macOS e Linux.

Também pode executar os módulos do Az 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.

Se quiser instalar o módulo Módulos de Recursos do PowerShell (AzureRM) para o Azure Stack Hub, veja Instalar o módulo AzureRM do PowerShell para o Azure Stack Hub.

Importante

Não haverá novas versões do módulo dos Módulos de Recursos do Azure. Os módulos dos Módulos de Recursos do Azure estão apenas em suporte para correções críticas. Daqui para a frente, haverá apenas lançamentos do Az para o Azure Stack Hub.

Pode 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 2020-09-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 Az compatíveis com o Az do Azure Stack Hub em cenários ligados à Internet, parcialmente ligados ou desligados. Este artigo explica-lhe as instruções detalhadas para estes cenários.

1. Verifique os pré-requisitos

Os módulos do Az são suportados no Azure Stack Hub com a Atualização 2002 ou posterior e com as correções atuais instaladas. Veja as notas de versão do Azure Stack Hub para obter mais informações.

Os módulos do Azure PowerShell Az funcionam com o PowerShell 5.1 ou superior no Windows ou o PowerShell Core 6.x e posterior em todas as plataformas. Deve instalar a versão mais recente do PowerShell Core disponível para o seu sistema operativo. Azure PowerShell não tem outros requisitos quando executado no PowerShell Core.

Para consultar a sua versão do PowerShell, execute o comando:

$PSVersionTable.PSVersion

Pré-requisitos do Windows

Para utilizar o Azure PowerShell no PowerShell 5.1 no Windows:

1. Atualize para o Windows PowerShell 5.1 se for necessário. Se estiver no Windows 10, já tem o PowerShell 5.1 instalado.

2. Instale o .NET Framework 4.7.2 ou posterior.

3. Verifique se tem a versão mais recente do PowerShellGet. Execute os seguintes cmdlets a partir de uma linha de comandos elevada:

   [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
   

2. Pré-requisitos para Linux e Mac

É necessária a versão 6.x ou posterior do PowerShell Core. Siga a ligação para obter instruções

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 ou do Az 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. Se o Uninstall-Module não tiver sido bem-sucedido, elimine todas as pastas que começam com Azure, Azou Azs. das localizações $env:PSModulePath. Para Windows PowerShell, as localizações 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. A eliminação destas pastas remove quaisquer módulos de Azure PowerShell existentes.

4. Ligado: Instalar com conectividade à Internet

O módulo do Azure Stack Az funcionará com o PowerShell 5.1 ou superior num computador Windows ou com o PowerShell 6.x ou superior numa plataforma Linux ou macOS. A utilização dos cmdlets do PowerShellGet é o método de instalação preferido. Este método funciona da mesma forma nas plataformas suportadas.

1. Execute o seguinte comando a partir 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, em seguida, abra uma nova sessão do PowerShell para que essa atualização possa entrar em vigor.

3. Execute o seguinte 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 módulos do AzureStack PowerShell.

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

Aviso

Não pode ter os módulos Azure Resource Manager (AzureRM) e Az instalados para o PowerShell 5.1 para Windows ao mesmo tempo. Se precisar de manter o Azure Resource Manager disponível no seu sistema, instale o módulo Az para o PowerShell Core 6.x ou posterior. Para tal, instale o PowerShell Core 6.x ou posterior e, em seguida, siga estas instruções num terminal do PowerShell Core.

5. Desligado: instalar sem 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

1. Pode utilizar módulos do AzureRM ou do Az . O código seguinte guarda os módulos do Az do repositório online fidedigno https://www.powershellgallery.com/.

   [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. Após a instalação dos módulos do Az, avance para 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
   

Nota

Em computadores sem ligação à Internet, recomendamos que execute o seguinte cmdlet para desativar a recolha de dados telemétricos. Pode deparar-se com uma degradação do desempenho dos cmdlets sem desativar a recolha de dados telemétricos. Isto aplica-se apenas às máquinas sem ligações à Internet

Disable-AzDataCollection

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 fornecedor NuGet num computador que não esteja ligado à Internet.

4. Registe esta localização como o repositório predefinido e instale os AzureRM módulos e AzureStack 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"
    [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
   

Confirmar a instalação do PowerShell

Confirme a instalação ao executar o seguinte comando:

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

7. Utilize o módulo Az

Pode utilizar os cmdlets e exemplos de código com base nos módulos do AzureRM. No entanto, vai querer alterar o nome dos módulos e cmdlets. Os nomes dos módulos foram alterados para que AzureRM o Azure se torne Az, e o mesmo para os cmdlets. Por exemplo, o módulo AzureRM.Compute foi renomeado para Az.Compute. New-AzureRMVM tornou-se New-AzVM, e Get-AzureStorageBlob é agora Get-AzStorageBlob.

Para obter uma discussão e documentação de orientação mais detalhadas para mover o script do AzurRM para o Az e alterar as alterações interruptivas no módulo Az do Azure Stack Hub, veja Migrar do AzureRM para o Azure PowerShell Az.

Problemas conhecidos

Erro ao instalar os módulos do Az

• Aplicável: este problema aplica-se ao 2002 e posterior
• Causa: ao instalar o módulo, é emitido um erro. 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."
• Remediação: execute o seguinte cmdlet na mesma sessão:
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  Feche a sessão e inicie uma nova sessão elevada do PowerShell.
• Ocorrência: Comum

Ao instalar o módulo do Az lança falsamente Administração erro de direitos necessários

• Aplicável: este problema aplica-se ao 2002 e posterior
• Causa: ao instalar o módulo a partir de uma linha de comandos elevada, é emitido um erro. O erro diz: Administrator rights required.
• Remediação: feche a sessão e inicie uma nova sessão elevada do PowerShell. Certifique-se de que não existe um Az existente. Módulo contas carregado na sessão.
• Ocorrência: Comum

O cmdlet New-AzVmss falha ao utilizar o perfil híbrido 2020-09-01

• Aplicável: este problema aplica-se ao perfil híbrido 2020-09-01.
• Causa: o cmdlet New-AzVmss não funciona com o perfil híbrido 2020-09-01.
• Remediação: utilize um modelo para criar um conjunto de dimensionamento de máquinas virtuais. Pode encontrar um exemplo dos modelos de Resource Manager do Azure Stack Hub no Repositório do GitHub AzureStack-QuickStart-Templates/101-vmss-windows-vm e pode encontrar instruções sobre como utilizar os Gestores de Recursos do Azure Stack Hub com o Visual Studio Code.
• Ocorrência: Comum

Erro gerado ao executar um script do PowerShell

• Aplicável: este problema aplica-se ao 2002 e posterior.

• Causa: ao executar scripts ou comandos do PowerShell com os módulos específicos do Azure Stack Hub, precisará do script ou comando para estar disponível no módulo. Poderá 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 do AzureRM do PowerShell. Se tentar executar um script que chame comandos do AzureRM quando o módulo Az estiver instalado, o script irá gerar erros. Em alternativa, se tentar executar um script que chama comandos do Az quando o módulo do AzureRM está instalado, o script irá gerar erros.

• Remediação: desinstale o módulo AzureRM e instale o módulo Az. Para obter instruções, veja Instalar o módulo do PowerShell Az para o Azure Stack Hub. Se estiver a utilizar as Ferramentas do Azure Stack Hub, utilize as ferramentas do Az. Clone o repositório de ferramentas a partir do ramo az ou transfira o AzureStack-Tools a partir do ramo az . Para obter instruções, veja Transferir ferramentas do Azure Stack Hub a partir do GitHub

• Ocorrência: Comum

Erro emitido com New-AzADServicePrincipal e New-AzADApplication

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

• Causa: o Graph do Azure Active Directory introduziu uma alteração interrupcional 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 de princípio 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:

    New-AzADServicePrincipal -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=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: este problema aplica-se a todas as versões suportadas.
• Causa: um erro de autenticação SharedTokenCacheCredential falhou ao ter várias versões do AzAccounts instaladas com a versão 2.1.1 do Módulo PowerShell do Azure Stack Hub.
• Remediação: remova todas as versões do AzAccounts e instale apenas a versão 2.2.8 do AzAccounts suportada.
• 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 do Azure Stack Hub
• Gerir os perfis de versões das APIs no Azure Stack Hub