Documenter votre code en ajoutant des commentaires et des métadonnées

4 minutes

Tout bon code Bicep est auto-documenté. Cela signifie qu’il utilise une affection de noms claire et une bonne structure afin de permettre aux collègues qui lisent votre code de comprendre rapidement ce qui se produit. S’ils ont besoin d’apporter des modifications, ils le font là où il faut, sans hésitation.

Cependant, dans certains cas, vous pouvez être amené à clarifier une partie du code en documentant davantage vos fichiers Bicep. De même, après avoir déployé votre modèle et créé des ressources dans Azure, il est important que les personnes voyant votre environnement Azure comprennent à quoi correspond chaque ressource et à quoi elle sert.

Dans cette unité, vous allez apprendre à ajouter des commentaires à vos fichiers Bicep et à utiliser des étiquettes de ressources pour ajouter des métadonnées à vos ressources Azure. Cette documentation additionnelle offre à vos collègues des insights sur la fonction de votre code, votre logique utilisée pour l’écrire et l’objet de vos ressources Azure.

Ajouter des commentaires à votre code

Bicep vous permet d’ajouter des commentaires à votre code. Les commentaires sont destinés à documenter le code avec du texte explicite, mais sont ignorés lorsque le fichier est déployé dans Azure.

Bicep prend en charge deux types de commentaires :

Les commentaires sur une seule ligne commencent par la séquence de caractères // (double barre oblique) et continuent jusqu’à la fin de la ligne, comme dans l’exemple suivant :

// 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'
  }
}

Les commentaires multilignes utilisent les séquences de caractères /* et */ de part et d’autre du commentaire et peuvent s’étendre sur plusieurs lignes, comme dans l’exemple suivant :
```
/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/
```

Conseil

Évitez d’utiliser des commentaires pour les parties évidentes et claires de votre code. En effet, des commentaires en trop grand nombre réduisent la lisibilité de votre code. De même, il est facile d’oublier de mettre à jour les commentaires à mesure que votre code évolue dans le temps. Bornez-vous à documenter les expressions logiques et complexes.

Vous pouvez aussi vous servir des commentaires Bicep pour ajouter un bloc multiligne structuré au début de chaque fichier. Vous pouvez voir cela comme un manifeste. Votre équipe peut décider d’assortir chaque modèle et chaque module d’un manifeste qui décrit la fonction du modèle et son contenu, comme dans cet exemple :

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

Ajouter des commentaires à des fichiers de paramètres

Les fichiers de paramètres vous permettent de créer un fichier JSON pour spécifier un ensemble de valeurs de paramètres pour votre déploiement. Les valeurs de paramètres doivent correspondre aux paramètres qui sont déclarés dans le modèle Bicep.

Documenter les valeurs que vous spécifiez dans les fichiers de paramètres s’avère aussi souvent bénéfique. Il est recommandé d’ajouter des commentaires aux fichiers de paramètres lorsque les valeurs de paramètres que vous utilisez ne sont pas immédiatement intelligibles pour les personnes qui lisent le fichier.

Par exemple, le modèle Bicep de votre site web peut inclure un paramètre pour l’URL qui donne accès à l’API de stock des produits de votre entreprise et qui permet à votre site web d’indiquer si vos jouets sont en stock dans votre entrepôt. Les URL d’accès à l’API de stock pour chaque environnement n’étant pas faciles à comprendre, il est dans ce cas tout indiqué d’ajouter un commentaire :

{
    "$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.
      }
    }
  }

Conseil

Quand vous utilisez des fichiers de paramètres et d’autres fichiers JSON qui contiennent des commentaires, vous devez généralement utiliser l’extension de fichier .jsonc au lieu de .json. Cela aide Visual Studio Code et d’autres outils à comprendre que les commentaires sont autorisés.

Ajouter des descriptions aux paramètres, aux variables et aux sorties

Quand vous créez un paramètre, une variable ou une sortie, vous pouvez appliquer l’élément décoratif @description() pour expliquer son objectif :

@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

Les descriptions sont plus puissantes que les commentaires car, quand une personne utilise l’extension Visual Studio Code pour Bicep, elles apparaissent chaque fois que cette personne pointe le curseur sur un nom symbolique. En outre, quand une personne utilise votre fichier Bicep comme module, elle voit les descriptions que vous appliquez à vos paramètres.

Ajouter des descriptions aux ressources

Il peut également s’avérer utile d’ajouter des descriptions aux ressources que vous définissez. Vous pouvez appliquer l’élément décoratif @description() à des ressources également.

De plus, certaines ressources prennent en charge l’ajout de descriptions ou d’autres informations explicites dans la ressource elle-même. Par exemple, un grand nombre de ressources Azure Policy et d’attributions de rôle de contrôle d’accès en fonction du rôle (RBAC) Azure incluent une propriété de description, comme celle-ci :

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.'
  }
}

Il est judicieux d’utiliser cette propriété pour expliquer pour quelle raison vous avez créé chaque attribution de rôle. La description étant déployée sur Azure avec la ressource, toute personne qui effectue un audit de la configuration RBAC de votre environnement Azure comprend immédiatement l’objectif de l’attribution de rôle.

Appliquer des étiquettes de ressources

Les commentaires figurant dans votre fichier Bicep n’apparaissent nulle part dans vos ressources déployées. Ils sont là uniquement pour vous aider à documenter vos fichiers Bicep. Cependant, nombreux sont les cas où vous devez assurer le suivi des informations sur les ressources Azure déployées, à savoir :

Répartition des coûts Azure entre des centres de coûts spécifiques.
Compréhension de la façon dont les données contenues dans les bases de données et les comptes de stockage doivent être classifiées et protégées.
Enregistrement du nom de l’équipe ou de la personne chargée de la gestion de la ressource.
Suivi du nom de l’environnement dont relève la ressource (p.ex., production ou développement).

Les étiquettes de ressources vous permettent de stocker des métadonnées importantes sur des ressources. Vous définissez des étiquettes de ressources dans votre code Bicep, puis Azure stocke les informations avec la ressource lorsqu’elle est déployée :

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'
  }
}

Vous pouvez interroger les étiquettes d’une ressource à l’aide d’outils comme Azure PowerShell et Azure CLI et afficher ces étiquettes sur le portail Azure :

Capture d’écran du portail Azure pour un compte de stockage, montrant l’emplacement des étiquettes.

Il est courant d’utiliser le même jeu d’étiquettes pour toutes les ressources. Il est donc souvent opportun de définir les étiquettes sous forme de paramètres ou de variables, puis de les réutiliser dans chaque ressource :