Migrar para o Bicep

Existem muitos benefícios para definir os recursos do Azure no Bicep, incluindo sintaxe mais simples, modularidade, gerenciamento automático de dependência, validação de tipo e IntelliSense, além de uma experiência de criação aprimorada.

Ao migrar JSON existentes dos modelos do ARM (Azure Resource Manager) para o Bicep, é recomendável seguir o fluxo de trabalho de cinco fases:

A primeira etapa do processo é capturar uma representação inicial dos recursos do Azure. Se for necessário, é possível descompilar o arquivo JSON em um arquivo Bicep inicial, que você deve aprimorar com a refatoração. Quando você tiver um arquivo de trabalho, deverá testar e implantar usando um processo que minimiza o risco de alterações significativas ao seu ambiente do Azure.

Neste artigo, resumimos esse fluxo de trabalho recomendado. Para obter diretrizes detalhadas, confira Migrar recursos do Azure e modelos do ARM JSON para usar o Bicep.

Fase 1: conversão

Na fase de conversão da migração dos recursos para o Bicep, a meta é 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, que você concluíra na sequência:

1. Capture uma representação dos recursos do Azure. Se você tiver um modelo JSON existente que esteja convertendo em Bicep, a primeira etapa será fácil: você já tem o modelo de origem. Se você estiver convertendo os recursos do Azure implantados por meio do portal ou de outra ferramenta, é necessário capturar as definições do recurso. Você pode capturar uma representação JSON dos recursos usando os cmdlets do portal do Azure, da CLI do Azure ou do Azure PowerShell para exportar recursos individuais, vários recursos e grupos de recursos inteiros. Você pode usar o comando Insert Resource no Visual Studio Code para importar uma representação do Bicep do recurso do Azure.

2. Se necessário, converta a representação JSON em Bicep usando o comando decompile.A ferramenta Bicep inclui o comando decompile para converter modelos. Você pode invocar o comando decompile na extensão Bicep do Visual Studio Code, na CLI do Azure ou na CLI do Bicep. O processo de descompilação é um processo de melhor esforço e não garante um mapeamento completo de JSON para Bicep. Talvez seja necessário revisar o arquivo Bicep gerado para seguir as melhores práticas do modelo antes de usar o arquivo para implantar recursos.

Fase 2: Migrar

Na fase de migração dos seus recursos para o Bicep, a meta é 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. É uma boa prática criar um arquivo Bicep por completo. 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.

2. Copiar cada recurso do modelo descompilado. 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 qualquer confusão à medida que o modelo aumenta de tamanho.

3. Identificar e recriar todos os recursos ausentes. 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, extensões de máquina virtual como DependencyAgentWindows e MMAExtension (Microsoft Monitoring Agent) não são tipos de recursos com suporte para exportação. Qualquer recurso não exportado, como extensões de máquina virtual, deve ser recriado no novo arquivo Bicep. É possível recriar recursos por meio de diversas ferramentas e abordagens, como o Azure Resource Explorer, a documentação de referência do Bicep e do modelo do ARM e o site de Modelos de início rápido do Azure.

Fase 3: refatoração

Na fase de refatoração da migração de sua origem para Bicep, a meta é aprimorar a qualidade do seu código Bicep. Esses aprimoramentos podem incluir alterações, como a adição de comentários de código, que alinham o modelo aos padrões do modelo.

A fase de implantação consiste em oito etapas, que você concluirá em qualquer ordem:

1. Examinar as versões de API do recurso. Quando os recursos do Azure são exportados, o modelo exportado pode não ter a versão da API mais recente para um tipo de recurso. Se houver propriedades específicas necessárias para implantações futuras, atualize a API para a versão apropriada. É uma boa prática examinar as versões de API de cada recurso exportado.

2. Examinar as sugestões de linter no novo arquivo Bicep. Ao usar a extensão do Bicep para Visual Studio Code para criar arquivos Bicep o linter Bicep é executado automaticamente e realça sugestões e erros em seu código. Muitas das sugestões e muitos dos erros incluem uma opção para aplicar uma correção rápida para o problema. Examine essas recomendações e ajuste o arquivo Bicep.

3. Revisar parâmetros, variáveis e nomes simbólicos. É possível que os nomes dos parâmetros, das variáveis e os nomes simbólicos gerados pelo descompilador não correspondam à convenção de nomenclatura padrão. Examine os nomes gerados e faça os ajustes necessários.

4. Simplificar expressões. Talvez o processo de descompilação nem sempre aproveite alguns dos recursos do Bicep. Examine todas as expressões geradas na conversão e simplifique-as. Por exemplo, o modelo descompilado pode incluir uma função concat() ou format() que pode ser simplificada usando a interpolação de cadeia de caracteres. Examine as sugestões do linter e faça os ajustes necessários.

5. Examinar recursos filho e de extensão. Existem diversas maneiras de declarar recursos filho e recursos de extensão no Bicep, incluindo a concatenação dos nomes de seus recursos, o uso da palavra-chave parent e o uso de recursos aninhados. Considere a análise desses recursos após a descompilação e verifique se a estrutura atende aos seus padrões. Por exemplo, lembre-se de não usar a concatenação de cadeia de caracteres para criar nomes de recursos filho: você deve usar a propriedade parent ou um recurso aninhado. Da mesma forma, as sub-redes podem ser referenciadas como propriedades de uma rede virtual ou como um recurso separado.

6. Modularizar os recursos. Se estiver convertendo um modelo que tenha muitos recursos, considere a possibilidade de dividir os tipos de recursos individuais em módulos para simplificar. Os módulos do Bicep ajudam a reduzir a complexidade de suas implantações e a aumentar a capacidade de reutilização do seu código Bicep.

   Observação

   É possível usar os modelos JSON como módulos em uma implantação do Bicep. O Bicep tem a capacidade de reconhecer módulos JSON e referenciá-los de maneira semelhante a como você usa os módulos Bicep.

7. Adicione comentários e descrições. Um bom código Bicep é autodocumentado. O Bicep permite que você adicione comentários e @description() atributos ao seu código que o ajudarão a documentar sua infraestrutura. O Bicep dá suporte a comentários de linha única usando uma sequência de caracteres // e comentários de várias linhas que começam com um /* e terminam com um */. Você pode adicionar comentários a linhas específicas no código e a seções de código.

8. Seguir as melhores práticas do Bicep. Verifique se o arquivo Bicep está seguindo as recomendações padrão. Examine o documento de referência de melhores práticas do Bicep para descobrir qualquer coisa que você possa ter perdido.

Fase 4: teste

Na fase de teste da migração dos seus recursos para o Bicep, a meta é verificar a integridade dos modelos migrados e executar uma implantação de teste.

A fase de teste consiste em duas etapas, que você concluirá na sequência:

1. Executar a operação de teste de hipóteses de implantação de modelo do ARM. Para ajudar você a verificar os modelos convertidos antes da implantação, use a operação de teste de hipóteses de implantação de modelo do Azure Resource Manager. Ela compara o estado atual do seu ambiente com o estado desejado definido no modelo. A ferramenta gera a lista de alterações que ocorrerão sem aplicá-las ao ambiente. Use o teste de hipóteses com implantações de modo incremental e completo. Mesmo que você pretenda implantar seu modelo usando o modo incremental, é uma boa ideia executar a operação de teste de hipóteses no modo completo.

2. Executar uma implantação de teste. Antes de introduzir o modelo Bicep convertido em produção, considere a possibilidade de executar várias implantações de teste. Se você tiver vários ambientes (por exemplo, desenvolvimento, teste e produção), o ideal será tentar primeiro implantar o modelo em um dos ambientes que não sejam de produção. Após a implantação, compare os recursos originais com as novas implantações de recursos para fins de consistência.

Fase 5: implantação

Na fase de implantação da migração dos recursos para o Bicep, a meta é implantar o arquivo Bicep final em produção.

A fase de implantação consiste em quatro etapas, que você concluirá na sequência:

1. Preparar um plano de reversão. A capacidade de recuperação de uma implantação com falha é crucial. Crie uma estratégia de reversão se alguma alteração significativa for introduzida nos ambientes. Faça o inventário dos tipos de recursos que são implantados, como máquinas virtuais, aplicativos Web e bancos de dados. O plano de dados de cada recurso também será considerado. Você tem uma forma de recuperar uma máquina virtual e os respectivos dados? Você tem um modo de recuperar um banco de dados após a exclusão? Um plano de reversão bem desenvolvido ajuda a reduzir ao mínimo o tempo de inatividade em caso de problemas em uma implantação.

2. Executar a operação de teste de hipóteses em produção. Antes de implantar o arquivo Bicep final em produção, execute a operação de teste de hipóteses no ambiente de produção usando valores de parâmetros em produção e considere a possibilidade de documentar os resultados.

3. Fazer a implantação manual. Se você pretende usar o modelo convertido em um pipeline, como o Azure DevOps ou o GitHub Actions, considere a possibilidade de executar a implantação no computador local primeiro. É preferível testar a funcionalidade do modelo antes de incorporá-lo ao pipeline de produção. Dessa forma, você pode agir rapidamente caso ocorra um problema.

4. Executar smoke tests. Após a conclusão da implantação, você deve executar uma série de smoke tests para garantir funcionamento correto do seu aplicativo ou carga de trabalho. Por exemplo, teste para ver se o aplicativo Web pode ser acessado por meio de canais de acesso normal, como a Internet pública ou por uma VPN corporativa. Para bancos de dados, tente fazer uma conexão de banco de dados e executar uma série de consultas. No caso de uma máquina virtual, faça logon nela e verifique se todos os serviços estão funcionando.

Próximas etapas

Para saber mais sobre o descompilador Bicep, confira Descompilação de JSON do modelo do ARM para Bicep.