Migrar do AzureRM para Azure PowerShell Az no Azure Stack Hub

  • Artigo

O módulo Az tem paridade de recursos com o AzureRM, mas usa nomes de cmdlets menores e mais consistentes. Os scripts gravados para os cmdlets do AzureRM não funcionarão automaticamente com o novo módulo. Para facilitar a transição, o Az oferece ferramentas para permitir a execução de seus scripts existentes usando o AzureRM. A migração para um novo conjunto de comandos nem sempre é conveniente, mas este artigo ajudará você a começar a realizar a transição para o novo módulo.

Para ver a lista completa de alterações recentes entre o AzureRM e o Az, confira o Guia de migração para o Az 1.0.0

Verificar se há versões instaladas do AzureRM

Antes de executar qualquer etapa de migração, verifique quais versões do AzureRM estão instaladas em seu sistema. Isso permite que você verifique se os scripts já estão sendo executados na versão mais recente e se você pode ativar os aliases de comando sem desinstalar o AzureRM.

Para verificar qual versão do AzureRM você instalou, execute o comando:

Get-InstalledModule -Name AzureRM -AllVersions

Verificar se os scripts atuais funcionam com o AzureRM

Essa é a etapa mais importante! Execute os scripts existentes e verifique se eles funcionam com a versão mais recente do AzureRM (2.5.0). Se os scripts não funcionarem, certifique-se de ler o Guia de migração do AzureRM.

Instalar o módulo Az do Azure PowerShell

A primeira etapa é instalar o módulo Az em sua plataforma. Quando você instala o Az, é recomendável desinstalar o AzureRM. Nas etapas a seguir, você aprenderá como continuar executando seus scripts existentes e habilitar a compatibilidade para os nomes de cmdlet antigos.

Para instalar o módulo Az do Azure PowerShell, siga estas etapas:

Habilitar aliases de compatibilidade do AzureRM

Importante

Habilite o modo de compatibilidade somente se você tiver desinstalado todas as versões do AzureRM. A ativação do modo de compatibilidade com os cmdlets do AzureRM ainda disponíveis poderá resultar em um comportamento imprevisível. Ignore esta etapa se tiver decidido manter o AzureRM instalado, mas esteja ciente de que os cmdlets do AzureRM usarão os módulos mais antigos e não chamarão cmdlets do Az.

Com o AzureRM desinstalado e seus scripts funcionando com a versão mais recente do AzureRM, a próxima etapa é habilitar o modo de compatibilidade para o módulo Az. A compatibilidade é habilitada com o comando:

Enable-AzureRmAlias -Scope CurrentUser

Os aliases permitem a capacidade de usar nomes de cmdlets antigos com o módulo Az instalado. Esses aliases são gravados no perfil do usuário para o escopo escolhido. Se não existir perfis de usuário, um perfil será criado.

Aviso

Você pode usar outro -Scope para este comando, mas isso não é recomendado. Os aliases são gravados no perfil do usuário do escopo escolhido, portanto, mantenha-os habilitados para um escopo o mais limitado possível. Habilitar os aliases em todo o sistema também pode causar problemas para outros usuários que têm o AzureRM instalado em seu escopo local.

Após habilitar o modo de alias, execute seus scripts novamente para confirmar que eles ainda funcionam conforme o esperado.

Alterar nomes de módulo e cmdlet

Em geral, os nomes de módulos foram alterados para que AzureRM e Azure tornem-se Az, e o mesmo ocorreu com os cmdlets. Por exemplo, o módulo AzureRM.Compute foi renomeado para Az.Compute. New-AzureRMVM se tornou New-AzVM, e Get-AzureStorageBlob agora é Get-AzStorageBlob.

Há exceções para essa alteração de nomenclatura e você deve estar atento. Alguns módulos foram renomeados ou mesclados em módulos existentes sem que isso afetasse o sufixo de seus cmdlets, além de alterar AzureRM ou Azure para Az. Caso contrário, o sufixo completo do cmdlet foi alterado para refletir o novo nome do módulo.

Módulo AzureRM Módulo Az O sufixo do cmdlet foi alterado?
AzureRM.profile Az.Accounts Sim
AzureRM.Insights Az.Monitor Sim
AzureRM.Tags Az.Resources Não
AzureRM.UsageAggregates Az.Billing Não
AzureRM.Consumption Az.Billing Não

Resumo

Seguindo essas etapas, é possível atualizar todos os scripts existentes para usar o novo módulo. Se você tiver dúvidas ou problemas com estas etapas que dificultaram a migração, deixe seu comentário sobre este artigo para que possamos melhorar as instruções.

Alterações da falha para Az 1.0.0

Este documento fornece informações detalhadas sobre as alterações entre o AzureRM 6.x e o novo módulo Az, versão 1.x e posterior. O sumário ajudará a orientá-lo por um caminho de migração completa, incluindo alterações específicas do módulo que possam afetar seus scripts.

Alterações da falha gerais

Esta seção fornece detalhes sobre as alterações gerais da falha que fazem parte do novo design do módulo Az.

Alterações no prefixo do substantivo do cmdlet

No módulo AzureRM, os cmdlets usavam AzureRM ou Azure como prefixo de substantivo. O Az simplifica e normaliza os nomes dos cmdlets, de modo que todos os cmdlets usem 'Az' como seu prefixo de substantivo do cmdlet. Por exemplo:

Get-AzureRMVM
Get-AzureKeyVaultSecret

Foi alterado para:

Get-AzVM
Get-AzKeyVaultSecret

Para simplificar a transição para esses novos nomes de cmdlets, o Az introduz dois novos cmdlets, Enable-AzureRmAlias e Disable-AzureRmAlias. Enable-AzureRmAlias cria aliases para os nomes de cmdlets mais antigos no AzureRM que são mapeados para os nomes de cmdlets mais recentes do Az. O uso do argumento -Scope com Enable-AzureRmAlias permite que você escolha em que local os aliases serão habilitados.

Por exemplo, o script a seguir no AzureRM:

#Requires -Modules AzureRM.Storage
Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

Pode ser executado com alterações mínimas usando Enable-AzureRmAlias:

#Requires -Modules Az.Storage
Enable-AzureRmAlias -Scope Process
Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

A execução de Enable-AzureRmAlias -Scope CurrentUser habilitará os aliases para todas as sessões do PowerShell, para que, após a execução desse cmdlet, um script como este não precise ser alterado:

Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

Para obter detalhes completos sobre o uso dos cmdlets de alias, confira a referência de Enable-AzureRmAlias.

Quando você estiver pronto para desabilitar os aliases, Disable-AzureRmAlias removerá os aliases criados. Para obter detalhes completos, confira a referência de Disable-AzureRmAlias.

Importante

Ao desabilitar os aliases, verifique se eles estão desabilitados para todos os escopos que tinham aliases habilitados.

Alterações no nome do módulo

Os nomes do módulo foram alterados de AzureRM.* para Az.*, exceto para os seguintes módulos:

Módulo AzureRM Módulo Az
Azure.Storage Az.Storage
Azure.AnalysisServices Az.AnalysisServices
AzureRM.profile Az.Accounts
AzureRM.Insights Az.Monitor
AzureRM.RecoveryServices.Backup Az.RecoveryServices
AzureRM.RecoveryServices.SiteRecovery Az.RecoveryServices
AzureRM.Tags Az.Resources
AzureRM.MachineLearningCompute Az.MachineLearning
AzureRM.UsageAggregates Az.Billing
AzureRM.Consumption Az.Billing

As alterações nos nomes dos módulos significam que qualquer script que usa #Requires ou Import-Module para carregar módulos específicos precisarão ser alterados para usar o novo módulo. Para os módulos em que o sufixo do cmdlet não foi alterado, isso significa que, embora o nome do módulo tenha sido alterado, isso não ocorreu com o sufixo que indica o espaço da operação.

Migrar requer e importar instruções de módulo

Os scripts que usam #Requires ou Import-Module para declarar uma dependência de módulos AzureRM precisam ser atualizados para usar os novos nomes de módulos. Por exemplo:

#Requires -Module AzureRM.Compute

Deve ser alterado para:

#Requires -Module Az.Compute

Para Import-Module:

Import-Module -Name AzureRM.Compute

Deve ser alterado para:

Import-Module -Name Az.Compute

Migrando invocações de cmdlet totalmente qualificadas

Os scripts que usam as invocações de cmdlet qualificadas por módulo, como:

AzureRM.Compute\Get-AzureRmVM

Precisam ser alterados para usar os novos nomes de módulos e cmdlets:

Az.Compute\Get-AzVM

Como migrar dependências de manifesto de módulo

Os módulos que expressam dependências de módulos AzureRM por meio de um arquivo de manifesto (.psd1) de módulo precisarão atualizar os nomes de módulos em sua seção RequiredModules:

RequiredModules = @(@{ModuleName="AzureRM.Profile"; ModuleVersion="5.8.2"})

Precisa ser alterado para:

RequiredModules = @(@{ModuleName="Az.Accounts"; ModuleVersion="1.0.0"})

Módulos removidos

Os seguintes módulos foram removidos:

  • AzureRM.Backup
  • AzureRM.Compute.ManagedService
  • AzureRM.Scheduler

Não há mais suporte ativo para as ferramentas desses serviços. Os clientes são incentivados a mudar para serviços alternativos, assim que for conveniente.

Windows PowerShell 5.1 e .NET 4.7.2

O uso do Az com o PowerShell 5.1 para Windows exige a instalação do .NET Framework 4.7.2. O uso do PowerShell Core 6.x ou posterior não exige o .NET Framework.

Remoção temporária do logon do usuário usando PSCredential

Devido a alterações no fluxo de autenticação para o .NET Standard, estamos temporariamente removendo o logon de usuário por meio do PSCredential. Essa funcionalidade será introduzida novamente na versão de 15/1/2019 do PowerShell 5.1 para Windows. Isso é abordado detalhadamente neste problema do GitHub.

Logon de código de dispositivo padrão em vez de prompt do navegador da Web

Devido a alterações no fluxo de autenticação para o .NET Standard, estamos usando o logon do dispositivo como o fluxo de logon padrão durante o logon interativo. O logon baseado em navegador da Web será reintroduzido no PowerShell 5.1 para Windows como o padrão na versão de 15/1/2019. Nesse momento, os usuários poderão escolher logon de dispositivo usando um parâmetro Switch.

Alterações de falhas para módulos

Esta seção fornece detalhes sobre alterações específicas da falha para cmdlets e módulos individuais.

Az.ApiManagement (anteriormente AzureRM.ApiManagement)

  • Remoção dos seguintes cmdlets:
    • New-AzureRmApiManagementHostnameConfiguration
    • Set-AzureRmApiManagementHostnames
    • Update-AzureRmApiManagementDeployment
    • Import-AzureRmApiManagementHostnameCertificate
    • Use o cmdlet Set-AzApiManagement para definir essas propriedades
  • Remoção das seguintes propriedades:
    • Removidas as propriedades PortalHostnameConfiguration, ProxyHostnameConfiguration, ManagementHostnameConfiguration e ScmHostnameConfiguration do tipo PsApiManagementHostnameConfiguration de PsApiManagementContext. Em vez disso, use PortalCustomHostnameConfiguration, ProxyCustomHostnameConfiguration, ManagementCustomHostnameConfiguration e ScmCustomHostnameConfiguration do tipo PsApiManagementCustomHostNameConfiguration.
    • Removida a propriedade StaticIPs de PsApiManagementContext. A propriedade foi dividida em PublicIPAddresses e PrivateIPAddresses.
    • Removida a propriedade necessária Location do cmdlet New-AzureApiManagementVirtualNetwork.

Az.Billing (anteriormente AzureRM.Billing, AzureRM.Consumption e AzureRM.UsageAggregates)

  • O parâmetro InvoiceName foi removido em favor do cmdlet Get-AzConsumptionUsageDetail. Os scripts precisarão usar outros parâmetros de identidade para a fatura.

Az.Compute (anteriormente AzureRM.Compute)

  • IdentityIds foram removidos da propriedade Identity nos Scripts dos objetos PSVirtualMachine e PSVirtualMachineScaleSet, que não devem mais usar o valor desse campo para tomar decisões de processamento.
  • O tipo de propriedade InstanceView do objeto PSVirtualMachineScaleSetVM foi alterado de VirtualMachineInstanceView para VirtualMachineScaleSetVMInstanceView
  • As propriedades AutoOSUpgradePolicy e AutomaticOSUpgrade foram removidas da propriedade UpgradePolicy
  • O tipo de propriedade Sku do objeto PSSnapshotUpdate foi alterado de DiskSku para SnapshotSku
  • VmScaleSetVMParameterSet foi removido do cmdlet Add-AzVMDataDisk. Não é mais possível adicionar um disco de dados individualmente em uma VM ScaleSet.

Az.KeyVault (anteriormente AzureRM.KeyVault)

  • A propriedade PurgeDisabled foi removida dos objetos PSKeyVaultKeyAttributes, PSKeyVaultKeyIdentityItem e PSKeyVaultSecretAttributes e os Scripts não devem fazer referência à propriedade PurgeDisabled para tomar decisões de processamento.

Az.Monitor (anteriormente AzureRM.Insights)

  • Removidos os nomes no plural dos parâmetros Categories e Timegrains em favor de nomes de parâmetro no singular dos Scripts cmdlet Set-AzDiagnosticSetting sendo usados

    Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2

    Deve ser alterado para

    Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2

Az.Network (anteriormente AzureRM.Network)

  • Removido o parâmetro preterido ResourceId do cmdlet Get-AzServiceEndpointPolicyDefinition
  • Removida a propriedade preterida EnableVmProtection do objeto PSVirtualNetwork
  • Removido o cmdlet preteridos Set-AzVirtualNetworkGatewayVpnClientConfig

Os scripts não devem mais tomar decisões de processamento com base nos valores desses campos.

Az.Resources (anteriormente AzureRM.Resources)

  • Removido o parâmetro Sku do cmdlet New/Set-AzPolicyAssignment

  • Removido o parâmetro de Password das Senhas cmdlets New-AzADServicePrincipal e New-AzADSpCredential automaticamente geradas, nos scripts que forneciam a senha:

    New-AzAdSpCredential -ObjectId 1f99cf81-0146-4f4e-beae-2007d0668476 -Password $secPassword

    Devem ser alterados para recuperar a senha da saída:

    $credential = New-AzAdSpCredential -ObjectId 1f99cf81-0146-4f4e-beae-2007d0668476
$secPassword = $credential.Secret

Az.Storage (anteriormente Azure.Storage e AzureRM.Storage)

  • Para dar suporte à criação de um contexto de armazenamento Oauth com apenas o nome da conta de armazenamento, o conjunto de parâmetros padrão foi alterado para OAuthParameterSet
    • Exemplo: $ctx = New-AzureStorageContext -StorageAccountName $accountName
  • O parâmetro Location agora é obrigatório no cmdlet Get-AzStorageUsage
  • Os métodos da API de armazenamento agora usam o padrão assíncrono baseado em tarefas (TAP), em vez de chamadas à API síncronas. Os seguintes exemplos demonstram os novos comandos assíncronos:

Instantâneo de blobs

AzureRM:

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$b.ICloudBlob.Snapshot()

Az:

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$task = $b.ICloudBlob.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

Compartilhar instantâneo

AzureRM:

$Share = Get-AzureStorageShare -Name $containerName -Context $ctx
$snapshot = $Share.Snapshot()

Az:

$Share = Get-AzStorageShare -Name $containerName -Context $ctx
$task = $Share.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

Cancelar a exclusão de blob com exclusão reversível

AzureRM:

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$b.ICloudBlob.Undelete()

Az:

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$task = $b.ICloudBlob.UndeleteAsync()
$task.Wait()

Definir camada do blob

AzureRM:

$blockBlob = Get-AzureStorageBlob -Container $containerName -Blob $blockBlobName -Context $ctx
$blockBlob.ICloudBlob.SetStandardBlobTier("hot")

$pageBlob = Get-AzureStorageBlob -Container $containerName -Blob $pageBlobName -Context $ctx
$pageBlob.ICloudBlob.SetPremiumBlobTier("P4")

Az:

$blockBlob = Get-AzStorageBlob -Container $containerName -Blob $blockBlobName -Context $ctx
$task = $blockBlob.ICloudBlob.SetStandardBlobTierAsync("hot")
$task.Wait()

$pageBlob = Get-AzStorageBlob -Container $containerName -Blob $pageBlobName -Context $ctx
$task = $pageBlob.ICloudBlob.SetPremiumBlobTierAsync("P4")
$task.Wait()

Az.Websites (anteriormente AzureRM.Websites)

  • Removidas as propriedades preteridas PSAppServicePlan, PSCertificate, PSCloningInfo e PSSite dos objetos

Próximas etapas