Modules Bicep

Avec Bicep, vous pouvez organiser les déploiements en modules. Un module est un fichier Bicep déployé par un autre fichier Bicep. Un module peut également être un modèle Azure Resource Manager (modèle ARM) pour JSON. Les modules permettent d’améliorer la lisibilité de vos fichiers Bicep en encapsulant les détails complexes de votre déploiement. Vous pouvez également facilement réutiliser des modules pour différents déploiements.

Pour partager des modules avec d’autres personnes de votre organisation, créez une spécification de modèle ou un registre privé. Les spécifications et modules de modèle dans le Registre sont disponibles uniquement pour les utilisateurs disposant des autorisations appropriées.

Conseil

Le choix entre un registre de modules et des specs de modèle est principalement une question de préférence. Vous devez prendre en compte certaines choses quand vous choisissez entre les deux :

• Le registre de modules est pris en charge uniquement par Bicep. Si vous n’utilisez pas Bicep, utilisez des spécifications de modèle.
• Vous pouvez déployer du contenu dans le registre de modules Bicep uniquement à partir d’un autre fichier Bicep. Vous pouvez déployer des spécifications de modèle directement à partir de l’API, d’Azure PowerShell, d’Azure CLI et du portail Azure. Vous pouvez même utiliser UiFormDefinition pour personnaliser l’expérience de déploiement du portail.
• Bicep dispose de fonctionnalités limitées pour incorporer d’autres artefacts de projet (y compris des fichiers non-Bicep et non-ARM-template tels que des scripts PowerShell, des scripts CLI et d’autres fichiers binaires) à l’aide des fonctions loadTextContent et loadFileAsBase64. Les specs de modèle ne peuvent pas empaqueter ces artefacts.

Les modules Bicep sont convertis en un seul modèle ARM avec des modèles imbriqués. Pour plus d’informations sur la façon dont Bicep résout les fichiers de configuration et comment Bicep fusionne un fichier de configuration défini par l’utilisateur avec le fichier de configuration par défaut, consultez processus de résolution de fichiers de configuration et processus de fusion de fichiers de configuration.

Ressources de formation

Si vous souhaitez en savoir plus sur les modules via des instructions pas à pas, consultez Créer des fichiers Bicep composables à l’aide de modules.

Définir des modules

La syntaxe de base pour définir un module est la suivante :

@<decorator>(<argument>)
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Un exemple simple et réel ressemble à ceci :

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Vous pouvez également utiliser un modèle ARM pour JSON en tant que module :

module stgModule '../storageAccount.json' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Utilisez le nom symbolique pour référencer le module dans une autre partie du fichier Bicep. Par exemple, vous pouvez utiliser le nom symbolique pour obtenir la sortie d’un module. Le nom symbolique peut contenir les lettres a à z et A à Z, les chiffres 0 à 9 et le trait de soulignement (_). Le nom ne peut pas commencer par un chiffre. Un module ne peut pas avoir le même nom qu’un paramètre, un module ou une ressource.

Le chemin d’accès peut être un fichier local ou un fichier dans un registre. Le fichier local peut être un fichier Bicep ou un modèle ARM pour JSON. Pour plus d’informations, consultez Chemin d’accès à un module.

La propriété name est facultative. Elle devient le nom de la ressource de déploiement imbriquée dans le modèle généré. Si aucun nom n’est fourni, un GUID est généré comme nom pour la ressource de déploiement imbriquée.

Si un module portant un nom statique est déployé simultanément dans la même étendue, il est possible qu’un déploiement interfère avec la sortie de l’autre déploiement. Par exemple, si deux fichiers Bicep utilisent le même module avec le même nom statique (examplemodule) et sont ciblés sur le même groupe de ressources, un déploiement peut afficher la sortie incorrecte. Si l’existence de déploiements simultanés dans la même étendue vous préoccupe, attribuez un nom unique à votre module. Une autre façon de s’assurer que les noms de modules uniques consiste à ne pas supprimer la name propriété, un nom de module unique sera généré automatiquement.

L’exemple suivant concatène le nom du déploiement au nom du module. Si vous fournissez un nom unique pour le déploiement, le nom du module est également unique.

module stgModule 'storageAccount.bicep' = {
  name: '${deployment().name}-storageDeploy'
  scope: resourceGroup('demoRG')
}

Ne pas fournir de nom de module est également valable. Un GUID sera généré en tant que nom de module.

module stgModule 'storageAccount.bicep' = {
  scope: resourceGroup('demoRG')
}

Si vous devez spécifier une étendue différente de celle du fichier principal, ajoutez la propriété d’étendue. Pour plus d’informations, consultez Définir l’étendue du module.

// deploy to different scope
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  scope: <scope-object>
  params: {
    <parameter-names-and-values>
  }
}

Pour déployer un module de manière conditionnelle, ajoutez une expression if. Cela est similaire au déploiement conditionnel d’une ressource.

// conditional deployment
module <symbolic-name> '<path-to-file>' = if (<condition-to-deploy>) {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Pour déployer plus d’une instance d’un module, ajoutez l’expression for. Utilisez le batchSize décorateur pour spécifier si les instances sont déployées en série ou en parallèle. Pour plus d’informations, consultez Boucles itératives dans Bicep.

// iterative deployment
@batchSize(int) // optional decorator for serial deployment
module <symbolic-name> '<path-to-file>' = [for <item> in <collection>: {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}]

À l’instar des ressources, les modules sont déployés en parallèle, sauf s’ils dépendent d’autres modules ou ressources. En règle générale, vous n’avez pas besoin de définir des dépendances, car elles sont déterminées implicitement. Si vous devez définir une dépendance explicite, ajoutez dependsOn à la définition du module. Pour en savoir plus sur les dépendances, consultez Dépendances de ressources dans Bicep.

module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
  dependsOn: [
    <symbolic-names-to-deploy-before-this-item>
  ]
}

Chemin d’accès à un module

Le fichier du module peut être soit un fichier local, soit un fichier externe. Le fichier externe peut se trouver dans une spécification de modèle ou un registre de modules Bicep.

Fichier local

Si le module est un fichier local, fournissez un chemin d’accès relatif à ce fichier. Tous les chemins d’accès dans Bicep doivent être spécifiés par le séparateur de répertoires de barre oblique (/) pour garantir une compilation cohérente entre les plateformes. La barre oblique inverse Windows (\) n’est pas prise en charge. Les chemins d’accès peuvent contenir des espaces.

Par exemple, pour déployer un fichier d’un niveau supérieur dans le répertoire à partir de votre fichier principal, utilisez :

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Fichier dans le registre

Il existe des registres de modules publics et privés.

Registre de module public

Remarque

Les modules non vérifiés Azure sont supprimés du registre des modules publics.

Les modules vérifiés Azure sont prédéfinis, prétestés et préverifiés que vous pouvez utiliser pour déployer des ressources sur Azure. Les employés de Microsoft ont créé et possèdent ces modules. Ils ont été conçus pour simplifier et accélérer le processus de déploiement pour les ressources et configurations Azure courantes. Les modules s’alignent également sur les meilleures pratiques telles qu’Azure Well-Architected Framework.

Parcourez les modules Bicep pour afficher la liste des modules disponibles. Sélectionnez les nombres mis en surbrillance dans la capture d’écran suivante pour accéder directement à cette vue filtrée :

La liste de modules affiche la dernière version. Sélectionnez le numéro de version pour afficher la liste des versions disponibles.

Pour créer un lien vers un module public, spécifiez le chemin d’accès au module avec la syntaxe suivante :

module <symbolic-name> 'br/public:<file-path>:<tag>' = {}

• br/public : il s’agit de l’alias pour les modules publics. Vous pouvez personnaliser cet alias dans le fichier config Bicep.
• chemin d’accès au fichier : il peut contenir des segments que vous pouvez séparer avec le / caractère.
• balise : cette balise est utilisée pour définir la version du module.

Par exemple :

module storage 'br/public:avm/res/storage/storage-account:0.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Remarque

L’alias pour les modules publics est br/public. Vous pouvez également l’écrire comme suit :

module <symbolic-name> 'br:mcr.microsoft.com/bicep/<file-path>:<tag>' = {}

Registre de module privé

Si vous avez publié un module dans un registre, vous pouvez créer un lien vers ce module. Indiquez le nom du registre de conteneurs Azure et un chemin d’accès au module. Spécifiez le chemin d’accès au module avec la syntaxe suivante :

module <symbolic-name> 'br:<registry-name>.azurecr.io/<file-path>:<tag>' = {

• br: il s’agit d’un nom de schéma pour un registre Bicep.
• chemin d’accès au fichier : ceci est appelé repository dans Azure Container Registry. Le chemin d’accès au fichier peut contenir des segments séparés par le / caractère.
• balise: permet de spécifier une version pour le module.

Par exemple :

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Lorsque vous référencez un module dans un Registre, l’extension Bicep dans Visual Studio Code appelle bicep restore automatiquement pour copier le module externe dans le cache local. La restauration du module externe prend quelques instants. Si IntelliSense pour le module ne fonctionne pas immédiatement, attendez la fin de la restauration.

Le chemin d’accès complet d’un module dans un registre peut être long. Au lieu de fournir le chemin d’accès complet chaque fois que vous souhaitez utiliser le module, configurez les alias dans le fichier bicepconfig.json. Les alias permettent de référencer plus facilement le module. Par exemple, grâce à un alias, vous pouvez raccourcir le chemin d’accès à :

module stgModule 'br/ContosoModules:storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Le registre de modules publics a un alias prédéfini :

module storage 'br/public:avm/res/storage/storage-account:0.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Vous pouvez remplacer l’alias public dans le fichier bicepconfig.json .

Fichier dans une spec de modèle

Une fois que vous avez créé une spec de modèle, créez un lien vers cette spécification de modèle dans un module. Spécifiez la spec de modèle en respectant le format suivant :

module <symbolic-name> 'ts:<sub-id>/<rg-name>/<template-spec-name>:<version>' = {

Pour simplifier votre fichier Bicep, créez un alias pour le groupe de ressources qui contient vos spécifications de modèle. Quand vous utilisez un alias, la syntaxe devient :

module <symbolic-name> 'ts/<alias>:<template-spec-name>:<version>' = {

Le module suivant déploie une spec de modèle pour créer un compte de stockage. L’abonnement et le groupe de ressources pour la spec de modèle sont définis dans l’alias nommé ContosoSpecs.

module stgModule 'ts/ContosoSpecs:storageSpec:2.0' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Utiliser des éléments décoratifs

Les éléments décoratifs sont écrits au format @expression et sont placés au-dessus des déclarations de modules. Le tableau suivant présente les décorateurs disponibles pour les modules :

Décorateur	Raisonnement	Descriptif
batchSize	Aucune	Configurez des instances pour un déploiement séquentiel.
description	chaîne	Fournissez des descriptions pour le module.

Les éléments décoratifs se trouvent dans l’espace de noms sys. Si vous devez différencier un élément décoratif d'un autre élément portant le même nom, faites précéder l’élément décoratif de sys. Par exemple, si votre fichier Bicep inclut un paramètre nommé description, vous devez ajouter l'espace de noms sys lorsque vous utilisez le décorateur description.

Taille de lot

Vous pouvez appliquer @batchSize() uniquement à une définition de ressource ou de module qui utilise une expression for.

Par défaut, les modules sont déployés en parallèle. Lorsque vous ajoutez l’élément décoratif @batchSize(int), vous déployez des instances en série.

@batchSize(3)
module storage 'br/public:avm/res/storage/storage-account:0.11.1' = [for storageName in storageAccounts: {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}]

Pour plus d’informations, consultez Déployer par lots.

Descriptif

Pour ajouter une explication, ajoutez une description aux déclarations de modules. Par exemple :

@description('Create storage accounts referencing an AVM.')
module storage 'br/public:avm/res/storage/storage-account:0.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Vous pouvez utiliser le texte mis en forme Markdown pour le texte de description.

Paramètres

Les paramètres que vous fournissez dans votre définition de module correspondent aux paramètres du fichier Bicep.

L’exemple Bicep suivant a trois paramètres : storagePrefix, storageSKUet location. Le storageSKU paramètre a une valeur par défaut. Vous n’avez donc pas besoin de fournir une valeur pour ce paramètre pendant le déploiement.

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Pour utiliser l’exemple précédent comme module, fournissez des valeurs pour ces paramètres.

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Définir l’étendue du module

Lorsque vous déclarez un module, définissez une étendue pour le module différent de l’étendue du fichier Bicep qui le contient. Utilisez la propriété scope pour définir l’étendue du module. Lorsque la scope propriété n’est pas fournie, le module est déployé dans l’étendue cible du parent.

Le fichier Bicep suivant crée un groupe de ressources et un compte de stockage dans ce groupe de ressources. Le fichier est déployé dans un abonnement, mais le module est limité au nouveau groupe de ressources.

// set the target scope for this file
targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

param location string = deployment().location

var resourceGroupName = '${namePrefix}rg'

resource newRG 'Microsoft.Resources/resourceGroups@2024-03-01' = {
  name: resourceGroupName
  location: location
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: newRG
  params: {
    storagePrefix: namePrefix
    location: location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

L’exemple suivant déploie des comptes de stockage sur deux groupes de ressources différents. Ces deux groupes de ressources doivent déjà exister.

targetScope = 'subscription'

resource firstRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup2'
}

module storage1 '../create-storage-account/main.bicep' = {
  name: 'westusdeploy'
  scope: firstRG
  params: {
    storagePrefix: 'stg1'
    location: 'westus'
  }
}

module storage2 '../create-storage-account/main.bicep' = {
  name: 'eastusdeploy'
  scope: secondRG
  params: {
    storagePrefix: 'stg2'
    location: 'eastus'
  }
}

Définissez la scope propriété sur un objet d’étendue valide. Si votre fichier Bicep déploie un groupe de ressources, un abonnement ou un groupe d’administration, vous pouvez définir l’étendue d’un module sur le nom symbolique de cette ressource. Vous pouvez également utiliser les fonctions d’étendue pour obtenir une étendue valide.

Ces fonctions sont les suivantes :

• resourceGroup
• abonnement
• managementGroup
• locataire

L’exemple suivant utilise la fonction managementGroup pour définir l’étendue.

param managementGroupName string

module mgDeploy 'main.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupName)
}

Sortie

Vous pouvez obtenir des valeurs d’un module et les utiliser dans le fichier Bicep principal. Pour obtenir une valeur de sortie d’un module, utilisez la propriété outputs sur l’objet de module.

Le premier exemple crée un compte de stockage et retourne les points de terminaison principaux :

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Lorsque la propriété est utilisée comme module, vous pouvez obtenir cette valeur de sortie :

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Avec la version 0.35.1 et ultérieures de Bicep, l’élément décoratif @secure() peut être appliqué aux résultats du module pour les marquer comme sensibles, garantissant ainsi que leurs valeurs ne sont pas exposées dans les journaux ou l'historique de déploiement. Cela est utile lorsqu’un module doit retourner des données sensibles, telles qu’une clé générée ou une chaîne de connexion, au fichier Bicep parent sans risquer d’exposition. Pour plus d’informations, consultez Sorties sécurisées.

Contenu connexe

• Pour obtenir un didacticiel, consultez Créer votre premier fichier Bicep.
• Pour passer une valeur sensible à un module, utilisez la getSecret fonction.