Migrar para o Bicep

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

Ao migrar modelos JSON Azure Resource Manager (modelos ARM) existentes para o Bicep, recomendamos seguir o fluxo de trabalho de cinco fases:

A primeira etapa do processo é capturar uma representação inicial de seus recursos do Azure. Se necessário, você descompila o arquivo JSON para um arquivo Bicep inicial, que você melhora refatoração. Quando você tem um arquivo de trabalho, testa e implanta usando um processo que minimiza o risco de interromper alterações em seu ambiente do Azure.

Neste artigo, resumimos esse fluxo de trabalho recomendado. Para obter orientações detalhadas, consulte Migrar recursos do Azure e modelos JSON ARM para usar o Bicep.

Fase 1: Converter

Na fase de conversão da migração de seus recursos para o Bicep, o objetivo é capturar uma representação inicial de seus recursos do Azure. O arquivo Bicep criado nesta 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ê conclui em sequência:

1. Capture uma representação dos seus recursos do Azure. Se você tiver um modelo JSON existente que está convertendo para Bicep, a primeira etapa é fácil - você já tem seu modelo de origem. Se você estiver convertendo recursos do Azure que foram implantados usando o portal ou outra ferramenta, precisará capturar as definições de recursos. Você pode capturar uma representação JSON de seus recursos usando o portal do Azure, a CLI do Azure ou os cmdlets do Azure PowerShell para exportar recursos únicos, vários recursos e grupos de recursos inteiros. Você pode usar o comando Inserir Recurso no Visual Studio Code para importar uma representação Bicep do seu recurso do Azure.

2. Se necessário, converta a representação JSON em Bicep usando o comando decompile. As ferramentas do Bíceps incluem o decompile comando para converter modelos. Você pode invocar o decompile comando do Visual Studio Code com a extensão Bicep, a CLI do Azure ou a partir da 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 atender às práticas recomendadas do modelo antes de usar o arquivo para implantar recursos.

Nota

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

O Visual Studio Code permite que você cole JSON como Bicep. Para obter mais informações, consulte Colar JSON como Bicep.

Fase 2: Migrar

Na fase de migração de seus recursos para o Bicep, o objetivo é 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ê conclui em sequência:

1. Crie um novo arquivo Bicep vazio. É uma boa prática criar um novo arquivo Bicep. O arquivo que você criou na fase de conversão é um ponto de referência para você examinar, mas você não deve tratá-lo como final ou implantá-lo como está.

2. Copie cada recurso do seu modelo descompilado. Copie cada recurso individualmente do arquivo Bicep convertido para o novo arquivo Bicep. Esse processo ajuda você a resolver quaisquer problemas por recurso e a evitar qualquer confusão à medida que seu modelo cresce em tamanho.

3. Identifique e recrie quaisquer recursos em falta. 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 suportados para exportação. Para qualquer recurso que não tenha sido exportado, como extensões de máquina virtual, você precisa recriar esses recursos no novo arquivo Bicep. Você pode recriar recursos usando várias ferramentas e abordagens, incluindo o Gerenciador de Recursos do Azure, a documentação de referência de modelo Bicep e ARM e o site Modelos de Início Rápido do Azure.

Fase 3: Refatorar

Na fase de refatoração da migração de seus recursos para o Bicep, o objetivo é melhorar 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 com seus padrões de modelo.

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

1. Revise as versões da API de recursos. Quando você exporta recursos do Azure, o modelo exportado pode não conter a versão de 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 revisar as versões da API para cada recurso exportado.

2. Reveja as sugestões de linter no seu novo ficheiro Bicep. Quando você usa a extensão Bicep para Visual Studio Code para criar arquivos Bicep, o linter Bicep é executado automaticamente e destaca sugestões e erros em seu código. Muitas das sugestões e erros incluem uma opção para aplicar uma solução rápida do problema. Reveja estas recomendações e ajuste o seu ficheiro Bicep.

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

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

5. Analise os recursos filho e de extensão. Há várias maneiras de declarar recursos filho e recursos de extensão no Bicep, incluindo concatenar os nomes de seus recursos, usar a palavra-chave parent e usar recursos aninhados. Considere revisar esses recursos após a descompilação e verifique se a estrutura atende aos seus padrões. Por exemplo, certifique-se de não usar concatenação de cadeia de caracteres para criar nomes de recursos filho - você deve usar a parent propriedade 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. Se você estiver convertendo um modelo que tenha muitos recursos, considere dividir os tipos de recursos individuais em módulos para simplificar. Os módulos Bicep ajudam a reduzir a complexidade de suas implantações e aumentam a reutilização do seu código Bicep.

   Nota

   É possível usar seus 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 forma semelhante à forma como você usa os módulos Bicep.

7. Adicione comentários e descrições. Um bom código Bicep é auto-documentável. O Bicep permite que você adicione comentários e @description() atributos ao seu código que ajudam a documentar sua infraestrutura. O Bicep suporta 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 */arquivo . Você pode adicionar comentários a linhas específicas em seu código e para seções de código.

8. Siga as melhores práticas do Bicep. Certifique-se de que seu arquivo Bicep está seguindo as recomendações padrão. Analise o documento de referência de práticas recomendadas do Bicep para verificar se você pode ter perdido.

Fase 4: Teste

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

A fase de teste consiste em duas etapas, que você conclui em sequência:

1. Execute a operação hipotética de implantação de modelo ARM. Para ajudá-lo a verificar seus modelos convertidos antes da implantação, você pode usar a operação hipotética de implantação de modelo do Azure Resource Manager. Ele 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 aplicar as alterações ao seu ambiente. Você pode usar hipóteses com implantações de modo incremental e completo. Mesmo que você planeje implantar seu modelo usando o modo incremental, é uma boa ideia executar sua operação hipotética no modo completo.

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

Fase 5: Implantação

Na fase de implantação da migração de seus recursos para o Bicep, o objetivo é implantar seu arquivo final do Bicep na produção.

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

1. Prepare 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 quaisquer alterações significativas forem introduzidas em seus ambientes. Faça um inventário dos tipos de recursos implantados, como máquinas virtuais, aplicativos Web e bancos de dados. O plano de dados de cada recurso também deve ser considerado. Você tem uma maneira de recuperar uma máquina virtual e seus dados? Você tem uma maneira de recuperar um banco de dados após a exclusão? Um plano de reversão bem desenvolvido ajuda a manter o tempo de inatividade ao mínimo se surgir algum problema de uma implantação.

2. Execute a operação hipotética em relação à produção. Antes de implantar seu arquivo Bicep final na produção, execute a operação hipotética em seu ambiente de produção, certificando-se de usar valores de parâmetros de produção e considere documentar os resultados.

3. Implante manualmente. Se você for usar o modelo convertido em um pipeline, como o Azure DevOps ou as Ações do GitHub, considere executar a implantação da sua máquina local primeiro. É preferível testar a funcionalidade do modelo antes de incorporá-lo ao seu pipeline de produção. Dessa forma, você pode responder rapidamente se houver um problema.

4. Execute testes de fumaça. Após a conclusão da implantação, você deve executar uma série de testes de fumaça para garantir que seu aplicativo ou carga de trabalho esteja funcionando corretamente. Por exemplo, teste para ver se seu aplicativo Web está acessível por meio de canais de acesso normais, como a Internet pública ou por uma VPN corporativa. Para bancos de dados, tente fazer uma conexão de banco de dados e execute uma série de consultas. Com máquinas virtuais, inicie sessão na máquina virtual e certifique-se de que todos os serviços estão ativos e em execução.

Próximos passos

Para saber mais sobre o descompilador Bicep, consulte Descompilando modelo ARM JSON para Bicep.