Refactoriser le fichier Bicep

  • 5 minutes

Après les phases de conversion et de migration de votre modèle vers Bicep, vous devez améliorer le fichier. Ce processus est appelé refactorisation. La troisième phase du workflow recommandé pour la migration de votre modèle ARM JSON et de vos ressources Azure vers Bicep est la phase de refactorisation :

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

L’objectif principal de cette phase de refactorisation est d’améliorer la qualité de votre code Bicep. Les améliorations peuvent inclure des modifications, comme l’ajout de commentaires de code qui mettent le modèle en conformité avec vos standards.

La phase de refactorisation comprend huit étapes que vous pouvez effectuer dans n’importe quel ordre :

  • Passer en revue les versions d’API des ressources.
  • Passer en revue les suggestions du linter dans votre nouveau fichier Bicep.
  • Réviser les paramètres, les variables et les noms symboliques.
  • Simplifier les expressions.
  • Passer en revue les ressources enfants et d’extension.
  • Modulariser.
  • Ajouter des commentaires.
  • Suivre les bonnes pratiques de Bicep.

L’exemple suivant montre la sortie de la commande Bicep decompile d’un modèle JSON qui crée un plan 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

Si vous déployez ce modèle Bicep tel quel, le déploiement réussit, mais vous pouvez améliorer le modèle pour le mettre en conformité avec vos standards.

Passer en revue les versions d’API des ressources

Quand vous utilisez Bicep pour interagir avec vos ressources Azure, vous spécifiez une version d’API à utiliser. À mesure que les produits Azure évoluent et s’améliorent, des versions d’API plus récentes sont publiées pour accéder aux nouvelles fonctionnalités. Quand vous exportez des ressources Azure, le modèle exporté risque de ne pas avoir la dernière version de l’API pour un type de ressource. Si vous avez besoin de propriétés spécifiques pour les futurs déploiements, mettez à jour l’API vers la version appropriée. Il est préférable de passer en revue les versions d’API pour chaque ressource exportée.

Les Informations de référence sur les modèles ARM Azure peuvent vous permettre de vérifier les versions d’API et les propriétés de ressource appropriées pour votre modèle.

Passer en revue les suggestions du linter dans votre nouveau fichier Bicep

Quand vous créez des fichiers Bicep en utilisant l’extension Bicep pour Visual Studio Code, le linter s’exécute automatiquement et met en évidence les erreurs dans votre code et offre des suggestions. La majorité des suggestions et des erreurs incluent une option permettant d’appliquer un correctif rapide au problème. Passez en revue ces recommandations et modifiez votre fichier Bicep.

Réviser les paramètres, les variables et les noms symboliques

Si votre infrastructure prend en charge plusieurs environnements, comme la production et le développement, créez des paramètres qui prennent en charge ces environnements. Une bonne convention d’affectation de noms facilite la personnalisation de vos déploiements par environnement.

Il est possible que les noms de paramètres, les noms de variables et les noms symboliques générés par le décompiler ne correspondent pas à votre convention d’affectation de noms standard. Examinez les noms générés et apportez les modifications nécessaires.

Dans l’exemple suivant, _var est ajouté à la variable nommée appServicePlanName_var à la fin du nom de la variable d’origine :

@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' = {

Pour que ce soit plus clair, il est judicieux de supprimer la partie _var du nom de la variable. Cependant, quand vous renommez la variable, son nouveau nom est en conflit avec le nom symbolique de la ressource du plan App Service. Il est donc judicieux de renommer d’abord les ressources, puis de renommer les variables utilisées dans leurs définitions.

Conseil

Quand vous renommez des identificateurs, veillez à le faire de façon cohérente dans toutes les parties de votre modèle. Ceci est particulièrement important pour les paramètres, les variables et les ressources auxquels vous faites référence dans votre modèle.

Visual Studio Code offre un moyen pratique de renommer les symboles : sélectionnez l’identificateur que vous souhaitez renommer, appuyez sur F2, entrez un nouveau nom, puis appuyez sur Entrée :

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

Ces étapes renomment l’identificateur et mettent automatiquement à jour toutes les références à ce dernier.

Simplifier les expressions

Le processus du décompiler risque de ne pas toujours tirer parti de certaines fonctionnalités de Bicep. Passez en revue les expressions qui sont générées dans la conversion et simplifiez-les. Par exemple, le modèle décompilé est susceptible d’inclure une fonction concat() ou format() que vous pouvez simplifier en utilisant une interpolation de chaîne. Passez en revue les suggestions du linter et apportez les modifications nécessaires.

Passer en revue les ressources enfants et d’extension

Bicep offre plusieurs moyens de déclarer des ressources enfants et d’extension, notamment en concaténant les noms de vos ressources, en utilisant la propriété parent et en utilisant des ressources imbriquées.

Pensez à examiner ces ressources après la décompilation pour vérifier que la structure correspond à vos standards. Par exemple, veillez à ne pas utiliser la concaténation de chaînes pour créer des noms de ressources enfants. Utilisez plutôt la propriété parent ou une ressource imbriquée. De même, vous pouvez référencer les sous-réseaux en tant que propriétés d’un réseau virtuel ou en tant que ressources distinctes.

Modulariser

Si vous convertissez un modèle qui contient un grand nombre de ressources, pour des raisons de simplicité, envisagez de diviser les différents types de ressources en modules. L’utilisation de modules dans Bicep permet de réduire la complexité des déploiements de vos modèles.

Notes

Il est possible d’utiliser vos modèles JSON comme modules dans un déploiement Bicep. Bicep peut reconnaître des modules JSON et les référencer de la même façon que vous utilisez des modules Bicep.

Ajouter des commentaires et des descriptions

Tout bon code Bicep est auto-documenté. Dans Bicep, vous pouvez ajouter des commentaires et des descriptions à votre code pour documenter votre infrastructure. Les commentaires et les descriptions peuvent aider vos collègues à comprendre le code et à gagner en confiance quand des modifications sont apportées. Les commentaires et les descriptions sont visibles quand vous utilisez un fichier Bicep dans Visual Studio Code, par exemple quand vous devez spécifier une valeur de paramètre pour un module. Mais quand vous déployez un fichier Bicep sur Azure, les commentaires sont ignorés.

Vous pouvez ajouter des commentaire de ligne uniques en utilisant la séquence de caractères //. Pour les commentaire de ligne multiples, commencez par un /* et terminez par un */. Vous pouvez ajouter des commentaires qui s’appliquent à des lignes spécifiques de votre code ou à des sections de code.

Vous pouvez ajouter un commentaire multiligne au début du fichier :

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

Vous pouvez ajouter des commentaires de ligne uniques comme en-têtes pour des sections du code ou sur des lignes individuelles pour décrire le code :

// 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 fournit un élément décoratif @description que vous pouvez utiliser pour documenter l’objectif de vos paramètres, variables, ressources, modules et sorties. Vous pouvez ajouter la description sur la ligne au-dessus de l’élément que vous décrivez :

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

Suivre les bonnes pratiques de Bicep

Vérifiez que votre fichier Bicep suit les recommandations standard. Consultez Bonnes pratiques de Bicep pour savoir si vous êtes éventuellement passé à côté de quelque chose.

Le modèle converti

Après avoir apporté les améliorations appropriées, passez en revue le modèle final avant de le déployer. Le modèle mis à jour inclut les noms révisés, les versions d’API, des descriptions et les commentaires ajoutés :

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