Converter e migrar seus recursos para um arquivo Bicep

Concluído

Ao iniciar o processo de migração para o Bicep, é importante seguir um processo estruturado para garantir que o arquivo Bicep descreva os recursos do Azure corretamente. Você precisa garantir que o código Bicep siga as práticas recomendadas, seja totalmente testado e esteja seguro para ser usado nas próximas implantações. Nesta unidade, você conhecerá as duas primeiras fases da migração para o Bicep: a fase de conversão e a fase de migração.

O foco principal dessas duas fases é preparar um novo arquivo Bicep antes de você refatorá-lo e testá-lo posteriormente.

Fase de conversão

O objetivo da fase de conversão da migração dos recursos para o Bicep é capturar uma representação inicial dos recursos do Azure. O arquivo Bicep criado nessa fase não está completo e não está pronto para ser usado. No entanto, o arquivo fornece um ponto de partida para sua migração.

A fase de conversão consiste em duas etapas possíveis, que você concluíra na sequência:

1. Capturar uma representação dos recursos do Azure.
2. Se necessário, converta a representação JSON em Bicep usando o comando decompile.

Se você tem um modelo JSON existente que está sendo convertido em Bicep, a primeira etapa é fácil porque você já tem o modelo de origem. Você aprenderá a descompilá-lo em Bicep nesta unidade.

Se você estiver convertendo os recursos do Azure implantados por meio do portal do Azure ou de outra ferramenta, precisará capturar as definições do recurso. Você pode exportar as definições do recurso e convertê-las em Bicep ou pode usar o comando Insert Resource no Visual Studio Code para inserir uma representação do Bicep do recurso do Azure.

Como o Azure representa os recursos

O Azure Resource Manager é o serviço usado para implantar e gerenciar recursos no Azure. Todos os recursos implantados no Azure são acompanhados pelo Resource Manager, independentemente do método usado para implantação do recurso. Use o portal do Azure, a CLI do Azure, o Azure PowerShell, a API REST do Resource Manager e os SDKs do Azure para interagir com o Resource Manager.

Há dois tipos de operações no Azure: operações do painel de controle e operações do plano de dados. As operações do painel de controle são usadas para gerenciar os recursos na sua assinatura. As operações do plano de dados são usadas para acessar as funcionalidades que são expostas por um recurso. Por exemplo, você usa uma operação de plano de controle para criar uma máquina virtual, mas usa uma operação de plano de dados para se conectar à máquina virtual usando o protocolo RDP.

Exportar os recursos existentes para um modelo JSON

Seja qual for o método de criação dos recursos do Azure, as informações sobre cada um deles são disponibilizadas no formato JSON pelo Resource Manager. Quando você solicita uma cópia da representação JSON de um recurso, você está exportando o recurso. O arquivo JSON exportado pode ser descompilado em Bicep.

O Resource Manager fornece várias maneiras de exportar os recursos do Azure para um modelo. Use o portal do Azure, a CLI do Azure e os cmdlets do Azure PowerShell para exportar recursos individuais, vários recursos e grupos de recursos inteiros.

O processo de exportação é uma operação do painel de controle, o que significa que apenas a configuração dos recursos do Azure é exportada. Por exemplo, quando você exporta uma máquina virtual, os dados no disco rígido da máquina virtual não são exportados. E quando você exporta uma conta de armazenamento, os blobs e outros conteúdos da conta de armazenamento não são incluídos no processo de exportação.

Você precisa considerar algumas coisas ao exportar recursos existentes:

• A definição de recurso exportado é um instantâneo do estado atual desse recurso. Ela inclui todas as alterações feitas no recurso desde a implantação inicial.
• O modelo exportado pode incluir algumas propriedades de recurso padrão que normalmente são omitidas de uma definição de Bicep. Por exemplo, o processo de exportação pode adicionar propriedades somente leitura que o Azure configura automaticamente. Não faz sentido incluir essas propriedades porque elas são somente leitura. Considere remover essas propriedades das definições de recurso ao fazer a migração para o Bicep, deixando os arquivos Bicep sem códigos desnecessários que possam causar confusão.
• Provavelmente, o modelo exportado não incluirá todos os parâmetros necessários para que ele seja reutilizável. Quando você exportar um modelo, muitas das propriedades serão embutidas em código no modelo. Você verá como adicionar parâmetros mais adiante neste módulo.
• Alguns recursos não podem ser exportados com essa abordagem e precisam ser definidos manualmente no arquivo Bicep. Você aprenderá a recriar esses recursos mais adiante nesta unidade.

Salvar as implantações em um modelo JSON

Se você já implantou um recurso manualmente pelo portal do Azure, talvez tenha notado a opção Baixar um modelo para automação na guia Examinar + criar. Essa opção salva um modelo do ARM em JSON baseado nos nomes e nas propriedades que você definiu ao criar o recurso no portal.

O Resource Manager também acompanha as implantações de recursos. As operações de implantação incluem as alterações enviadas pela experiência de criação de recursos do portal do Azure e pelas implantações de modelo do ARM. Em geral, as alterações nos recursos existentes feitas por meio do portal do Azure, dos cmdlets do Azure PowerShell, da CLI do Azure ou de outras ferramentas não criam implantações.

Se as implantações forem criadas com uma ferramenta compatível, você poderá acessar o modelo de implantação por meio do histórico de implantações do grupo de recursos. Use o portal do Azure, a CLI do Azure ou o Azure PowerShell para salvar as implantações.

Você precisa considerar algumas coisas ao salvar os modelos usando esse método:

• O modelo salvo mostra o estado dos recursos no momento da implantação. Ele não inclui nenhuma alteração feita após a implantação.
• Se a implantação contiver vários recursos, você não poderá selecionar recursos específicos para inclusão e exclusão. Essa operação baixa a definição de todos os recursos que faziam parte da implantação inicial. No entanto, ao passar para a fase de migração do processo, você pode ignorar manualmente os recursos desnecessários.
• O modelo inclui apenas as propriedades de recurso necessárias para a implantação.
• Ele pode incluir parâmetros que você pode usar para reimplantar o modelo em vários ambientes. No entanto, você precisa confirmar se esses parâmetros atendem às suas necessidades.
• Provavelmente, o modelo não inclui propriedades incorretas, mas você ainda deve verificar se o modelo inclui tudo o que você espera e remover todas as propriedades desnecessárias.

Observação

No entanto, você exporta os recursos exportando os recursos existentes ou salvando as implantações, trata o arquivo exportado como um ponto de partida e não o usa diretamente. Em vez disso, use-o como ponto de partida para o modelo final.

Inserir recursos existentes no Bicep

A extensão do Bicep para o Visual Studio Code inclui o comando Insert Resource, que captura uma representação do Bicep de um recurso do Azure. Esse comando lê a definição JSON do recurso do Azure, remove as propriedades reconhecidas como somente leitura e descompila o JSON para Bicep. Assim como acontece com a função de exportação, o código Bicep resultante pode ser usado como um ponto de partida para o arquivo Bicep final.

Você pode inserir um recurso abrindo a paleta de comandos do Visual Studio Code. Use Ctrl+Shift+P no Windows e Linux e ⌘+Shift+P no macOS.

Descompilar o modelo JSON do ARM de origem

A segunda etapa na migração dos recursos do Azure para o Bicep é a conversão dos modelos JSON do ARM e dos recursos do Azure em modelos Bicep. As ferramentas Bicep incluem o comando decompile para converter modelos. Você pode invocar o comando decompile usando a CLI do Azure ou a CLI do Bicep.

O processo de descompilação não garante um mapeamento completo de JSON para Bicep. Talvez seja necessário revisar o arquivo Bicep gerado para seguir as práticas recomendadas do modelo antes de usar o arquivo para implantar recursos. Considere isso como o ponto de partida da migração. Posteriormente neste módulo, você aprenderá a corrigir todos os problemas encontrados durante o processo de descompilação.

Depois de descompilar o modelo, você concluiu a fase de conversão. Agora, você tem um arquivo Bicep válido para iniciar o processo.

Fase de migração

A meta da fase de migração dos recursos para o Bicep é criar o primeiro rascunho do arquivo Bicep implantável e garantir que ele defina todos os recursos do Azure que estão no escopo da migração.

A fase de migração consiste em três etapas, que você concluíra na sequência:

1. Criar um arquivo Bicep vazio.
2. Copiar cada recurso do modelo descompilado.
3. Identificar e recriar todos os recursos ausentes.

Criar um arquivo Bicep

Uma boa prática é criar um arquivo Bicep do zero. O arquivo criado na fase de conversão é um ponto de referência a ser examinado, mas você não deve tratá-lo como final ou implantá-lo no estado em que se encontra.

Copiar recursos para o novo arquivo Bicep

Copie cada recurso individualmente do arquivo Bicep convertido para o novo arquivo Bicep. Esse processo ajuda você a resolver problemas por recurso e a evitar confusões à medida que o modelo aumenta.

Recriar recursos sem suporte

Nem todos os tipos de recursos do Azure podem ser exportados por meio do portal do Azure, da CLI do Azure ou do Azure PowerShell. Por exemplo, as extensões de máquina virtual como DependencyAgentWindows e MMAExtension (Microsoft Monitoring Agent) são tipos de recursos que não podem ser exportados.

Quando você tenta exportar um recurso por meio do portal do Azure, da CLI do Azure ou do Azure PowerShell e inclui um tipo de recurso sem suporte, uma mensagem de erro detalhada é gerada. Será necessário recriar todos os recursos que não foram exportados no novo arquivo Bicep, como as extensões de máquina virtual. Você pode escolher entre várias ferramentas e abordagens para recriar recursos, incluindo o Azure Resource Explorer, a referência de modelo do ARM e os modelos de início rápido do Azure.

Azure Resource Explorer

O Azure Resource Explorer é uma ferramenta inserida no portal do Azure. O portal não mostra alguns tipos de recursos, mas o Resource Explorer oferece uma representação JSON desses recursos. Para acessar o Resource Explorer, procure-o na caixa de pesquisa:

O painel de resultados mostra uma lista dos provedores de recursos registrados na sua assinatura e detalhes de todos os recursos, os grupos de recursos e as assinaturas que você tem permissão para ver. Para ver uma representação JSON de um recurso, selecione a hierarquia no lado esquerdo do painel:

Ao selecionar um recurso, você pode ver a representação JSON, como neste exemplo:

{
    "name": "DependencyAgentWindows",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rg-app-prod-truckline/providers/Microsoft.Compute/virtualMachines/vm-prod-001/extensions/DependencyAgentWindows",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "eastus",
    "properties": {
        "autoUpgradeMinorVersion": true,
        "provisioningState": "Succeeded",
        "publisher": "Microsoft.Azure.Monitoring.DependencyAgent",
        "type": "DependencyAgentWindows",
        "typeHandlerVersion": "9.10"
    }
}

Use a representação JSON para definir um recurso Bicep:

resource dependencyAgentWindows 'Microsoft.Compute/virtualMachines/extensions@2022-08-01' = {
  parent: virtualMachine
  name: 'DependencyAgentWindows'
  location: 'eastus'
  properties: {
    autoUpgradeMinorVersion: true
    publisher: 'Microsoft.Azure.Monitoring.DependencyAgent'
    type: 'DependencyAgentWindows'
    typeHandlerVersion: '9.10'
  }
}

Observação

A representação JSON inclui uma propriedade chamada provisioningState. A propriedade provisioningState é somente leitura e é definida automaticamente pelo Azure, portanto, não está incluída na definição de recurso Bicep.

Dica

A extensão Bicep para o Visual Studio Code ajuda você a definir os recursos do Azure no Bicep. Por exemplo, a representação Bicep do recurso inclui uma versão da API, mas a versão JSON exportada não. No Visual Studio Code, quando você começa a inserir o tipo de recurso, uma versão da API é sugerida automaticamente.

Referência de modelo ARM

A referência de modelo do ARM é uma fonte de informações sobre a estrutura de modelo do ARM, os tipos de recursos, as versões de API e as definições de propriedade dos recursos do Azure. A documentação fornece exemplos nos formatos Bicep e JSON.

Você pode escolher provedores de recursos e tipos de recursos específicos, como Microsoft.Web/serverfarms, e as respectivas versões de API. Examine as propriedades de recurso que são necessárias e quais delas são opcionais. Você também pode exibir descrições de propriedade que ajudam a entender o que as propriedades fazem.

Modelos de início rápido do Azure

O repositório de Modelos de Início Rápido do Azure é uma coleção de modelos contribuídos pela comunidade. Esse repositório de modelos pesquisáveis fornece exemplos de uma variedade de recursos e soluções do Azure. Em alguns guias de início rápido, um modelo JSON do ARM e um modelo Bicep do ARM estão disponíveis para exibição. Você pode usar esses modelos como um ponto de referência para ajudá-lo a criar e verificar seus modelos para implantação.

Suponha que você queira encontrar um modelo que crie um plano e um aplicativo do Serviço de Aplicativo do Azure. Cada modelo de início rápido oferece a opção de implantar o modelo diretamente no Azure ou exibir o modelo no GitHub.

Tenha em mente que os modelos de início rápido do Azure são contribuições da comunidade. Alguns dos exemplos podem estar desatualizados, pois sempre há novos recursos adicionados aos serviços do Azure. Os exemplos também podem incluir recursos e propriedades que você não precisa para usar o modelo. No entanto, o repositório de modelos de início rápido é um recurso útil para ajudar você a entender como implantar os recursos usando modelos do ARM.