Les 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. En utilisant des modules, vous améliorez la lisibilité de vos fichiers Bicep en encapsulant des 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.

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.

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 vous déployez un module avec un nom statique simultanément dans la même étendue, un déploiement peut interférer 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 est généré automatiquement. La règle no-module-name du linter est conçue pour faire respecter cette pratique de codage plus propre en signalant tout module contenant encore une propriété name explicite.

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 est 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

Vous pouvez utiliser un fichier local ou un fichier externe pour le module. Vous pouvez trouver le fichier externe 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. Dans Bicep, vous devez utiliser le séparateur de répertoires de barre oblique (/) pour tous les chemins 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.

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

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

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 simplifient et accélèrent le processus de déploiement pour les ressources et configurations courantes Azure. Les modules s’alignent également sur les meilleures pratiques telles qu’Azure Well-Architected Framework.

Parcourez Bicep modules 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 séparez avec le / caractère.
• balise : spécifie une version pour le module.

Par exemple:

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

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 : spécifie 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 .

À compter de Bicep CLI v0.43.1, le Bicep bloque explicitement l’utilisation de domaines personnalisés lors du référencement ou de la restauration de modules à partir d’un Azure Container Registry (ACR). Cette protection empêche l’utilisation de configurations non prises en charge qui entraîneraient autrement des problèmes de conformité.

Si vous essayez de référencer un domaine personnalisé, par moduleStore.myCompany.comexemple, l’interface CLI Bicep retourne l’erreur de diagnostic BCP446. Par exemple:

module foo 'br:moduleStore.myCompany.com/networking/hub:1.0.0' = { ... }

Bicep valide tous les noms d’hôte de registre par rapport à une liste d’autorisation intégrée. Actuellement, seuls les domaines suivants sont autorisés :

• *.azurecr.io
• *.azurecr.cn
• *.azurecr.us
• mcr.microsoft.com
• mcr.azure.cn
• ghcr.io

Si votre organisation utilise des domaines personnalisés, mettez à jour vos fichiers Bicep pour respecter ces restrictions :

• Revenez aux noms d’hôte natifs : Mettez à jour toutes les références de module Bicep pour utiliser le domaine natif .azurecr.io (ou spécifique au cloud approprié).
• Effacer le cache local : Après avoir mis à jour vos références, vous devrez peut-être effacer votre cache de module local. Réexécutez bicep restore pour récupérer les modules en utilisant les noms d’hôte natifs corrigés.

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 de la spécification de modèle sont définis dans l’alias appelé ContosoSpecs.

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

Utiliser des décorateurs

Écrivez des décorateurs au format @expression et placez-les au-dessus des déclarations de module. Le tableau suivant présente les décorateurs disponibles pour les modules :

Les éléments décoratifs se trouvent dans l’espace de noms sys. Si vous devez différencier un décorateur d’un autre élément portant le même nom, préfixez le décorateur avec 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.

BatchSize

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

Par défaut, le moteur de déploiement déploie des modules 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.

Description

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.

Parameters

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@2025-06-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@2025-04-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 vous ne fournissez pas la scope propriété, 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@2025-04-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@2025-04-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2025-04-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, définissez 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
• subscription
• managementGroup
• tenant

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

param managementGroupName string

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

Output

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@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Lorsque vous utilisez la propriété en tant que module, vous pouvez obtenir cette valeur de sortie :

targetScope = 'subscription'

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

resource demoRG 'Microsoft.Resources/resourceGroups@2025-04-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 Bicep version 0.35.1 ou ultérieure, vous pouvez appliquer le décorateur @secure() aux sorties de module afin de les marquer comme sensibles, pour garantir que leurs valeurs ne soient pas exposées dans les journaux ni dans l’historique de déploiement. Cette approche est utile lorsqu’un module doit retourner des données sensibles, telles qu’une clé générée ou un chaîne de connexion, au fichier Bicep parent sans risquer d’exposition. Pour plus d’informations, consultez Sorties sécurisées.

Identité de module

À compter de Bicep version 0.36.1, vous pouvez affecter une identité managée affectée par l’utilisateur à un module. Cette identité est disponible dans le module, par exemple pour accéder à un Key Vault. Toutefois, les services principaux ne prennent pas encore en charge cette fonctionnalité.

param identityId string

module mod './module.bicep' = {
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identityId}': {}
    }
  }
  name: 'mod'
  params: {
    keyVaultUri: 'keyVaultUri'
    identityId: identityId
  }
}

Contenu connexe

• Pour passer une valeur sensible à un module, utilisez la getSecret fonction.