Ajouter des paramètres et des sorties aux modules

  • 7 minutes

Chaque module que vous créez doit avoir un objectif clair. C’est comme si votre module avait un contrat. Il accepte un ensemble de paramètres, crée un ensemble de ressources et peut fournir des sorties au modèle parent. Les personnes qui utilisent le module n’ont pas besoin de savoir comment il fonctionne, juste de savoir qu’il remplit son rôle.

Quand vous planifiez un module, tenez compte des éléments suivants :

  • Ce que vous devez savoir pour pouvoir satisfaire l’objectif du module.
  • Ce que les personnes qui consomment votre module doivent s’attendre à fournir.
  • Ce que les personnes qui consomment votre module doivent attendre comme sorties.

Paramètres du module

Réfléchissez aux paramètres acceptés par votre module, et si chaque paramètre doit être facultatif ou obligatoire.

Quand vous créez des paramètres pour des modèles, une bonne pratique est d’ajouter des paramètres par défaut quand vous le pouvez. Dans les modules, les paramètres par défaut ne sont pas aussi importants, car votre module est utilisé par un modèle parent qui utilise peut-être ses propres paramètres par défaut. Si vous avez des paramètres similaires dans les deux fichiers, tous deux avec des valeurs par défaut, les utilisateurs de votre modèle risquent de ne pas arriver à déterminer quelle valeur par défaut est appliquée et, par conséquent, à assurer la cohérence. Il est souvent préférable de conserver la valeur par défaut sur le modèle parent et de la supprimer sur le module.

Vous devez aussi réfléchir à la façon dont vous gérez les paramètres qui contrôlent les références SKU de vos ressources et d’autres paramètres de configuration importants. Quand vous créez un modèle Bicep autonome, il est courant d’y incorporer des règles métier. Par exemple : Quand je déploie un environnement de production, le compte de stockage doit utiliser le niveau GRS. Mais les modules présentent parfois des intérêts différents.

Si vous créez un module qui doit être réutilisable et flexible, n’oubliez pas que les règles métier de chaque modèle parent peuvent être différentes. Ce n’est donc pas la peine d’incorporer des règles métier dans des modules génériques. Définissez les règles métier dans votre modèle parent, puis passez explicitement la configuration du module à travers des paramètres.

Toutefois, si vous créez un module pour permettre à votre organisation de déployer facilement des ressources qui répondent à vos besoins spécifiques, vous pouvez ajouter des règles métier pour simplifier les modèles parents.

Quels que soient les paramètres que vous attribuez à votre module, veillez à ajouter une description explicite en utilisant l’attribut @description :

@description('The name of the storage account to deploy.')
param storageAccountName string

Utiliser des conditions

L’un des objectifs de l’utilisation de code de type Bicep pour déployer une infrastructure est d’éviter de dupliquer les efforts, voire de créer plusieurs modèles pour des objectifs identiques ou similaires. Les fonctionnalités de Bicep vous offrent une boîte à outils puissante pour créer des modules réutilisables qui fonctionnent dans diverses situations. Vous pouvez combiner des fonctionnalités comme les modules, les expressions, les valeurs de paramètre par défaut et les conditions pour générer du code réutilisable qui vous offre la flexibilité dont vous avez besoin.

Supposons que vous créez un module qui déploie un compte Azure Cosmos DB. Quand il est déployé dans votre environnement de production, vous devez configurer le compte pour qu’il envoie ses journaux à un espace de travail Log Analytics. Pour configurer l’envoi des journaux à Log Analytics, vous définissez une ressource diagnosticSettings.

Vous pouvez satisfaire votre exigence en ajoutant une condition à la définition de ressource et en rendant le paramètre d’ID d’espace de travail facultatif avec une valeur par défaut :

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

Quand vous ajoutez ce module dans un modèle Bicep, vous pouvez facilement le configurer pour envoyer les journaux du compte Azure Cosmos DB à Log Analytics en définissant un ID d’espace de travail. Sinon, si vous n’avez pas besoin des journaux pour l’environnement que vous déployez, omettez le paramètre. Il a une valeur par défaut. Le module encapsule la logique nécessaire pour agir conformément à vos besoins.

Conseil

N’oubliez pas de vérifier que votre modèle est valide dans les deux scénarios, quand l’instruction if a la valeur true ou false.

Sorties du module

Les modules peuvent définir des sorties. C’est une bonne idée de créer une sortie pour les informations dont le modèle parent peut avoir besoin. Par exemple, si votre module définit un compte de stockage, créez une sortie pour le nom du compte de stockage afin que le modèle parent puisse y accéder.

Avertissement

N’utilisez pas de sorties pour les valeurs de secret. Les sorties sont journalisées dans le cadre de l’historique de déploiement, elles ne sont donc pas appropriées pour les valeurs sécurisées. À la place, vous pouvez utiliser l’une des options suivantes :

  • Utilisez une sortie pour fournir le nom de la ressource. Le modèle parent peut ensuite créer une ressource existing avec ce nom et rechercher la valeur sécurisée de manière dynamique.
  • Écrivez la valeur dans un secret Azure Key Vault. Le modèle parent peut alors lire le secret dans le coffre quand il en a besoin.

Un modèle parent peut utiliser des sorties de module dans des variables, des propriétés dans d’autres définitions de ressource, ou peut exposer des variables et des propriétés sous forme de sorties. En exposant et en utilisant des sorties dans vos fichiers Bicep, vous pouvez créer des ensembles réutilisables de modules Bicep qui peuvent être partagés avec votre équipe et réutilisés dans plusieurs déploiements. Une bonne pratique également est d’ajouter une description explicite aux sorties en utilisant l’attribut @description :

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

Conseil

Vous pouvez aussi utiliser des services dédiés pour stocker, gérer et accéder aux paramètres créés par votre modèle Bicep. Key Vault est conçu pour stocker des valeurs sécurisées. Azure App Configuration est conçu pour stocker d’autres valeurs (non sécurisées).

Chaîner les modules

Souvent, vous créez un fichier Bicep parent qui compose plusieurs modules ensemble. Par exemple, imaginez que vous créez un modèle Bicep pour déployer des machines virtuelles qui utilisent des réseaux virtuels dédiés. Vous pouvez créer un module pour définir un réseau virtuel. Vous pouvez ensuite prendre l’ID de ressource de sous-réseau du réseau virtuel comme sortie de ce module et l’utiliser comme entrée du module de machine virtuelle :

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

Dans cet exemple, des noms symboliques sont utilisés pour les références entre les modules. Cette référence permet à Bicep de comprendre automatiquement les relations entre les modules.

Comme Bicep comprend qu’il y a une dépendance, il déploie les modules dans l’ordre :

  1. Bicep déploie tout le contenu du module virtualNetwork.
  2. Si le déploiement réussit, Bicep accède à la valeur de sortie subnetResourceId et la transmet au module virtualMachine sous forme de paramètre.
  3. Bicep déploie tout le contenu du module virtualMachine.

Notes

Quand vous dépendez d’un module, Bicep attend la fin de tout le déploiement du module. Souvenez-vous en quand vous planifiez vos modules. Si vous créez un module qui définit une ressource dont le déploiement prend beaucoup de temps, toutes les autres ressources qui dépendent de ce module attendent que le déploiement du module se termine.