Refactorización del archivo de Bicep

  • 5 minutos

Después de convertir y migrar la plantilla a Bicep, debe mejorar el archivo. Este proceso se denomina refactorización. La tercera fase del flujo de trabajo recomendado para migrar la plantilla de ARM JSON y los recursos de Azure a Bicep es la fase de refactorización:

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

El objetivo principal de la fase de refactorización consiste en mejorar la calidad del código de Bicep. Las mejoras pueden incluir cambios, como agregar comentarios de código, que alineen la plantilla con los estándares de plantilla.

La fase de refactorización consta de ocho pasos, que se pueden realizar en cualquier orden:

  • Revisión de las versiones de la API de los recursos.
  • Revisión de las sugerencias del linter en el nuevo archivo de Bicep.
  • Revisión de los parámetros, las variables y los nombres simbólicos.
  • Simplificación de las expresiones.
  • Revisión de los recursos secundarios y de extensión.
  • Modularización.
  • Agregar comentarios.
  • Seguimiento de los procedimientos recomendados de Bicep.

En el ejemplo siguiente, se muestra la salida del comando decompile de Bicep de una plantilla JSON que crea un plan de App Service:

@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

La implementación se realizará correctamente si implementa esta plantilla de Bicep tal y como está, pero podría mejorarla para alinearla con los estándares de su plantilla.

Revisión de las versiones de la API de los recursos

Cuando se usa Bicep para interactuar con los recursos de Azure, se especifica la versión de la API que se va a usar. A medida que los productos de Azure cambian y mejoran, se lanzan versiones de la API más recientes para proporcionar acceso a nuevas funcionalidades. Al exportar recursos de Azure, es posible que la plantilla exportada no tenga la versión más reciente de la API para un tipo de recurso. Si necesita propiedades específicas para futuras implementaciones, actualice la API a la versión adecuada. Se recomienda revisar las versiones de la API de cada recurso exportado.

La referencia de la plantilla de ARM de Azure puede ayudarle a comprobar las propiedades de los recursos y las versiones de la API adecuadas para su plantilla.

Revisión de las sugerencias del linter en el nuevo archivo de Bicep

Al crear archivos de Bicep con la extensión de Bicep para Visual Studio Code, el linter se ejecuta automáticamente, resalta los errores en el código y proporciona sugerencias. Muchas de las sugerencias y errores incluyen una opción para aplicar una corrección rápida del problema. Revise estas recomendaciones y ajuste su archivo de Bicep.

Revisión de los parámetros, las variables y los nombres simbólicos

Si su infraestructura es compatible con varios entornos, como los de producción y desarrollo, cree parámetros que sean compatibles con estos entornos. Una buena convención de nomenclatura de los parámetros facilita la personalización de las implementaciones por entorno.

Es posible que los nombres de parámetros, las variables y los nombres simbólicos generados por el descompilador no coincidan con la convención de nomenclatura estándar. Revise los nombres generados y realice los ajustes necesarios.

Por ejemplo, en el siguiente ejemplo, la variable denominada appServicePlanName_var tiene anexado _var al final del nombre de la variable 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 conseguir una mayor claridad, se recomienda quitar _var del nombre de la variable. Pero, al cambiar el nombre de la variable, su nuevo nombre entra en conflicto con el nombre simbólico del recurso del plan de App Service. Por lo tanto, es recomendable cambiar el nombre de los recursos primero y, después, cambiar el nombre de las variables que se usan en sus definiciones.

Sugerencia

Cuando cambie el nombre de los identificadores, procure de hacerlo de modo coherente en todas las partes de la plantilla. Esto es especialmente importante en el caso de los parámetros, variables y recursos a los que se hace referencia en toda la plantilla.

Visual Studio Code ofrece una forma muy cómoda de cambiar el nombre de los símbolos; solo hay que seleccionar el identificador que queremos cambiar de nombre, presionar F2, escribir el nuevo nombre y, por último, presionar Entrar:

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

En estos pasos se cambia el nombre del identificador y se actualizan automáticamente todas las referencias a él.

Simplifica expresiones

Es posible que el proceso de descompilación no siempre aproveche algunas características de Bicep. Revise las expresiones que se generan en la conversión y simplifíquelas. Por ejemplo, la plantilla descompilada podría incluir una función concat() o format() que se puede simplificar con la interpolación de cadenas. Revise las sugerencias del linter y realice los ajustes necesarios.

Revisión de los recursos secundarios y de extensión

Bicep proporciona varias maneras de declarar recursos secundarios y de extensión, entre las que se incluyen la concatenación de los nombres de los recursos, el uso de la propiedad parent y el empleo de recursos anidados.

Considere la posibilidad de revisar estos recursos después de la descompilación para asegurarse de que la estructura cumple sus estándares. Por ejemplo, asegúrese de que no usa la concatenación de cadenas para crear nombres de los recursos secundarios. En su lugar, use la propiedad parent o un recurso anidado. Del mismo modo, puede hacer referencia a las subredes como propiedades de una red virtual o como recursos independientes.

Modularización

Si va a convertir una plantilla que tiene muchos recursos, considere la posibilidad de dividir los tipos de recursos individuales en módulos para simplificar. El uso de módulos en Bicep ayuda a reducir la complejidad de las implementaciones de plantillas.

Nota:

Es posible usar las plantillas JSON como módulos en una implementación de Bicep. Bicep puede reconocer módulos de JSON y hacer referencia a ellos de forma similar a como se usan los módulos de Bicep.

Adición de comentarios y descripciones

Un código de Bicep en condiciones es autodocumentado; En Bicep, puede agregar comentarios y descripciones al código para documentar la infraestructura. Los comentarios y las descripciones pueden ayudar a los compañeros de equipo a comprender el código y aumentar la confianza cuando se realizan cambios. Tanto los comentarios como las descripciones son visibles cuando se trabaja con un archivo de Bicep en Visual Studio Code, como cuando es necesario especificar un valor de parámetro para un módulo. Pero los comentarios se omiten al implementar un archivo de Bicep en Azure.

Puede agregar comentarios de una sola línea mediante la secuencia de caracteres //. Para los comentarios de varias líneas, comience con un /* y termine con un */. Puede agregar comentarios que se aplican a líneas específicas o a secciones del código.

Puede agregar un comentario de varias líneas al principio del archivo:

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

Puede agregar comentarios de una sola línea se pueden agregar como encabezados en las secciones de código o en líneas individuales para describir el 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.

Bicep proporciona un decorador @description, que puede usar para documentar el propósito de los parámetros, variables, recursos, módulos y salidas. Puede agregar la descripción en la línea situada encima del elemento que va a describir:

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

Seguimiento de los procedimientos recomendados de Bicep

Asegúrese de que el archivo de Bicep sigue las recomendaciones estándar. Revise los procedimientos recomendados de Bicep para comprobar si ha pasado algo por alto.

La plantilla convertida

Después de realizar las mejoras adecuadas, revise la plantilla final antes de implementarla. La plantilla actualizada incluye nombres revisados, versiones de API, descripciones y comentarios agregados:

/*
  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.