Documentación del código mediante la adición de comentarios y metadatos

  • 4 minutos

Un código de Bicep en condiciones es autodocumentado; Es decir, utiliza una nomenclatura clara y una buena estructura, de modo que cuando los compañeros lean el código sepan al instante en qué consiste. Si tienen que hacer algún cambio, tendrán la seguridad de que están modificando los sitios adecuados.

Sin embargo, en algunas situaciones, es posible que tengamos que aclarar algún código incluyendo más documentación en los archivos de Bicep. Además, una vez que la plantilla se ha implementado y los recursos se han creado en Azure, es importante que cualquiera que visualice el entorno de Azure entienda qué es cada recurso y para qué sirve.

En esta unidad, aprenderemos a agregar comentarios a los archivos de Bicep y a usar etiquetas de recursos para agregar metadatos a los recursos de Azure. Gracias a esta información extra, nuestros compañeros sabrán qué es lo que el código hace, la lógica que usó para escribir el código y la finalidad de los recursos de Azure.

Agregar comentarios al código

Bicep le permite agregar comentarios al código. Los comentarios son texto legible que documenta el código, pero que se omite cuando el archivo se implementa en Azure.

Bicep admite dos tipos de comentarios:

  • Comentarios de una sola línea, que comienzan con una secuencia de caracteres de doble barra diagonal (//) y continúan hasta el final de la línea, como se aprecia aquí:

    // We need to define a firewall rule to allow Azure services to access the database.

resource firewallRule 'Microsoft.Sql/servers/firewallRules@2023-08-01-preview' = {
  parent: sqlServer
  name: 'AllowAllAzureIPs'
  properties: {
    startIpAddress: '0.0.0.0' // This combination represents 'all Azure IP addresses'.
    endIpAddress: '0.0.0.0'
  }
}

  • Comentarios de varias líneas, que usan una secuencia de caracteres formada por /* y */ para rodear el comentario y pueden abarcar varias líneas, como se muestra aquí:

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

Sugerencia

No utilice los comentarios para hablar de partes obvias y claras del código. Cuando hay demasiados comentarios, en realidad se reduce la legibilidad del código. Además, es fácil olvidarse de actualizar los comentarios cuando el código cambia posteriormente, así que mejor centrarse en documentar la lógica que sea singular y las expresiones complejas.

Los comentarios de Bicep se pueden usar también para agregar un bloque estructurado de varias líneas al principio de cada archivo, como una especie de manifiesto. El equipo puede decidir que cada plantilla y cada módulo deben tener un manifiesto que describa la finalidad de la plantilla y lo que contiene, como en este ejemplo:

/*
  SYNOPSIS: Module for provisioning Azure SQL server and database.
  DESCRIPTION: This module provisions an Azure SQL server and a database, and configures the server to accept connections from within Azure.
  VERSION: 1.0.0
  OWNER TEAM: Website
*/

Agregar comentarios a archivos de parámetros

Los archivos de parámetros le permiten crear un archivo JSON para especificar un conjunto de valores de parámetro de la implementación. Estos valores de parámetro deben coincidir con los parámetros declarados en la plantilla de Bicep.

Documentar los valores que se especifican en los archivos de parámetros suele ser beneficioso también. Agregar comentarios a los archivos de parámetros viene bien cuando trabajamos con valores de parámetro que podrían no estar del todo claros para alguien que lee el archivo.

Por ejemplo, la plantilla de Bicep de nuestro sitio web puede incluir un parámetro relativo a la dirección URL para acceder a la API de existencias de productos de la empresa, de forma que el sitio web muestre si quedan existencias de juguetes en el almacén. Las direcciones URL de acceso a la API de existencias de cada entorno no son fáciles de entender, por lo que son buenas candidatas para incluir un comentario en ellas:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "productStockCheckApiUrl": {
        "value": "https://x73.mytoycompany.com/e4/j7" // This is the URL to the product stock API in the development environment.
      }
    }
  }

Sugerencia

Cuando trabajamos con archivos de parámetros y otros archivos JSON que incluyen comentarios, se suele usar la extensión de archivo .jsonc, y no .json. Esto ayuda a Visual Studio Code y a otras herramientas a saber que el uso de comentarios está permitido.

Adición de descripciones a parámetros, variables y salidas

Al crear un parámetro, una variable o una salida, puede aplicar el decorador @description() para ayudar a explicar su finalidad:

@description('The Azure region into which the resources should be deployed.')
param location string = resourceGroup().location

@description('Indicates whether the web application firewall policy should be enabled.')
var enableWafPolicy = (environmentType == 'prod')

@description('The default host name of the App Service app.')
output hostName string = app.properties.defaultHostName

Las descripciones son más eficaces que los comentarios porque, cuando un usuario usa la extensión de Visual Studio Code para Bicep, las descripciones se muestran cada vez que alguien mantiene el puntero sobre un nombre simbólico. Además, cuando alguien usa el archivo de Bicep como módulo, verá las descripciones que se aplican a los parámetros.

Agregar descripciones a recursos

También puede ser útil agregar descripciones a los recursos que defina. También puede aplicar el decorador @description() a los recursos.

Además, algunos recursos admiten la adición de descripciones u otra información legible en el propio recurso. Por ejemplo, muchos recursos de Azure Policy y asignaciones de roles de control de acceso basado en rol (RBAC) de Azure incluyen una propiedad de descripción, como la siguiente:

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: storageAccount
  name: guid(roleDefinitionId, resourceGroup().id)
  properties: {
    principalType: 'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    principalId: principalId
    description: 'Contributor access on the storage account is required to enable the application to create blob containers and upload blobs.'
  }
}

El uso de esta propiedad es adecuado para explicar por qué hemos creado cada asignación de roles. La descripción se implementa en Azure con el recurso, por lo que cualquier persona que audite la configuración de RBAC del entorno de Azure comprenderá inmediatamente la finalidad de la asignación de roles.

Usar etiquetas de recursos

Los comentarios del archivo de Bicep no aparecen en ninguna parte de los recursos implementados: están ahí únicamente como ayuda para documentar archivos de Bicep. Sin embargo, muchas veces es necesario llevar un seguimiento de la información relativa a los recursos de Azure implementados, por ejemplo, para lo siguiente:

  • Destinar los costes de Azure a centros de coste específicos
  • Saber cómo se deben clasificar y proteger los datos contenidos en las bases de datos y las cuentas de almacenamiento
  • Registrar el nombre del equipo o la persona responsable de la administración del recurso
  • Llevar un seguimiento del nombre del entorno con el que está relacionado el recurso (como producción o desarrollo).

Las etiquetas de recursos le permiten almacenar metadatos importantes sobre los recursos. Las etiquetas de recursos se definen en el código de Bicep y Azure almacena la información con el recurso cuando este se implementa:

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  tags: {
    CostCenter: 'Marketing'
    DataClassification: 'Public'
    Owner: 'WebsiteTeam'
    Environment: 'Production'
  }
  sku: {
    name: storageAccountSkuName
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Las etiquetas de un recurso se pueden consultar con herramientas como Azure PowerShell y la CLI de Azure. Asimismo, las etiquetas pueden visualizarse en Azure Portal:

Captura de pantalla de Azure Portal de una cuenta de almacenamiento, que muestra la ubicación de las etiquetas

Lo normal es usar el mismo conjunto de etiquetas en todos los recursos, de modo que es buena idea definir las etiquetas como parámetros o variables y, seguidamente, reutilizarlas en cada recurso:

param tags object = {
  CostCenter: 'Marketing'
  DataClassification: 'Public'
  Owner: 'WebsiteTeam'
  Environment: 'Production'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  tags: tags
}

resource appServiceApp 'Microsoft.Web/sites@2023-12-01' = {
  tags: tags
}