Refatorar o arquivo Bicep

  • 5 minutos

Após as fases de conversão e migração da conversão do modelo em Bicep, você precisará aprimorar o arquivo. Esse processo é chamado de refatoração. A terceira fase do fluxo de trabalho recomendado para migrar o modelo do ARM em JSON e os recursos do Azure para o Bicep é a fase de refatoração:

Diagram that shows the refactor phase of the recommended workflow for migrating Azure resources to Bicep.

O foco principal da fase de refatoração é aprimorar a qualidade do código Bicep. Os aprimoramentos podem incluir alterações, como a adição de comentários de código, que alinham o modelo aos padrões de modelo.

A fase de refatoração consiste em oito etapas, que podem ser realizadas em qualquer ordem:

  • Examinar as versões de API do recurso.
  • Examinar as sugestões de linter no novo arquivo Bicep.
  • Revisar parâmetros, variáveis e nomes simbólicos.
  • Simplificar expressões.
  • Examinar recursos filho e de extensão.
  • Modularizar os recursos.
  • Adicionar comentários.
  • Seguir as melhores práticas do Bicep.

O exemplo a seguir mostra a saída do comando Bicep decompile de um modelo JSON que cria um plano do Serviço de Aplicativo:

@description('Location for resources.')
param location string = resourceGroup().location

@allowed([
  'prod'
  'dev'
  'test'
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service Plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

Se você implantar esse modelo Bicep no estado em que se encontra, a implantação será bem-sucedida, mas você pode aprimorá-lo para alinhá-lo aos seus padrões de modelo.

Examinar as versões de API do recurso

Ao usar o Bicep para interagir com os recursos do Azure, você especifica uma versão de API a ser usada. À medida que os produtos do Azure são alterados e aprimorados, são lançadas versões de API mais recentes para oferecer acesso a novas funcionalidades. Quando os recursos do Azure são exportados, o modelo exportado pode não ter a última versão da API de um tipo de recurso. Se você precisar de propriedades específicas 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.

A referência de modelo do ARM do Azure pode ajudar você a verificar as versões de API e as propriedades de recurso apropriadas para seu modelo.

Examinar as sugestões de linter no novo arquivo Bicep

Quando você cria arquivos Bicep usando a extensão Bicep para Visual Studio Code, o linter é executado automaticamente e realça os erros no código e fornece sugestões. Muitas das sugestões e muitos dos erros incluem uma opção para aplicar uma correção rápida ao problema. Examine essas recomendações e ajuste o arquivo Bicep.

Revisar parâmetros, variáveis e nomes simbólicos

Se a sua infraestrutura der suporte a vários ambientes, como produção e desenvolvimento, crie parâmetros que deem suporte a esses ambientes. Uma boa convenção de nomenclatura de parâmetro facilita a personalização das implantações por ambiente.

É possível que os nomes de parâmetros, variáveis e 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.

No seguinte exemplo, a variável chamada appServicePlanName_var tem _var acrescentado ao final do nome da variável original:

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {

Para aumentar a clareza, é melhor remover _var do nome da variável. Mas, quando você renomear a variável, o novo nome entrará em conflito com o nome simbólico do recurso do plano do Serviço de Aplicativo. Portanto, é interessante renomear os recursos primeiro e, depois, renomear as variáveis usadas nas definições deles.

Dica

Ao renomear os identificadores, não se esqueça de renomeá-los de maneira consistente em todas as partes do modelo. Isso é especialmente importante para os parâmetros, as variáveis e os recursos que são referenciados no modelo.

O Visual Studio Code oferece uma forma conveniente de renomear os símbolos: escolha o identificador que deseja renomear, selecione F2, insira um novo nome e selecione ENTER:

Screenshot from Visual Studio Code that shows how to rename a symbol.

Essas etapas renomeiam o identificador e atualizam automaticamente todas as referências a ele.

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 você pode simplificar usando a interpolação de cadeia de caracteres. Examine as sugestões do linter e faça os ajustes necessários.

Examinar recursos filho e de extensão

O Bicep oferece várias maneiras de declarar recursos filho e de extensão, incluindo a concatenação dos nomes dos recursos, o uso da propriedade parent e o uso de recursos aninhados.

Considere examinar esses recursos após a descompilação para verificar se essa estrutura atende aos seus padrões. Por exemplo, não use a concatenação de cadeia de caracteres para criar nomes de recursos filho. Nesse caso, use 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.

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. O uso de módulos no Bicep ajuda a reduzir a complexidade das implantações de modelo.

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.

Adicionar comentários e descrições

Um bom código Bicep é autodocumentado. No Bicep, você pode adicionar comentários e descrições ao código para documentar a infraestrutura. Esses comentários e descrições podem ajudar seus colegas de equipe a entender o código e aumentar o nível de confiança durante as alterações. Comentários e descrições ficam visíveis quando você trabalha com um arquivo Bicep no Visual Studio Code, por exemplo, quando você precisa especificar um valor de parâmetro para um módulo. Mas quando você implanta um arquivo Bicep no Azure, os comentários são ignorados.

Você pode adicionar comentários de linha única usando a sequência de caracteres //. Para comentários de várias linhas, comece com um /* e termine com um */. Você pode adicionar comentários aplicados a linhas específicas ou a seções do código.

Você pode adicionar um comentário multilinha no início do arquivo:

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

É possível adicionar comentários de linha única como cabeçalhos de seções do código ou a linhas individuais para descrever o código:

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.

O Bicep fornece um decorador @description que você pode usar para documentar a finalidade de seus parâmetros, variáveis, recursos, módulos e saídas. Você pode adicionar a descrição na linha acima do item que está descrevendo:

@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

Seguir as melhores práticas do Bicep

Verifique se o arquivo Bicep segue as recomendações padrão. Examine as práticas recomendadas do Bicep para saber se faltou algo.

O modelo convertido

Depois de fazer os devidos aprimoramentos, examine o modelo final antes de implantá-lo. O modelo atualizado inclui nomes revisados, versões da API, descrições e comentários adicionados:

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

// Parameters
@description('Location for all resources.')
param location string = resourceGroup().location

@allowed([
  'prod' // Production environment
  'dev' // Development environment
  'test' // Test environment
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service plan instances.')
param appServicePlanInstanceCount int = 1

// Variables
@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.