Bicep-modules

Met Bicep kunt u implementaties in modules organiseren. Een module is een Bicep-bestand dat door een ander Bicep-bestand wordt geïmplementeerd. Een module kan ook een Azure Resource Manager-sjabloon (ARM-sjabloon) voor JSON zijn. Door modules te gebruiken, verbetert u de leesbaarheid van uw Bicep bestanden door complexe details van uw implementatie in te kapselen. U kunt modules ook eenvoudig hergebruiken voor verschillende implementaties.

Als u modules wilt delen met andere personen in uw organisatie, maakt u een sjabloonspecificatie of een persoonlijk register. Sjabloonspecificaties en modules in het register zijn alleen beschikbaar voor gebruikers met de juiste machtigingen.

Bicep-modules worden geconverteerd naar één ARM-sjabloon met geneste sjablonen. Voor meer informatie over hoe Bicep configuratiebestanden oplost en hoe Bicep een door de gebruiker gedefinieerd configuratiebestand samenvoegt met het standaardconfiguratiebestand, raadpleegt u het proces voor het oplossen van configuratiebestanden en het proces voor het samenvoegen van configuratiebestanden.

Modules definiëren

De basissyntaxis voor het definiëren van een module is:

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

Een eenvoudig voorbeeld in de praktijk ziet er als volgt uit:

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

U kunt ook een ARM-sjabloon voor JSON als module gebruiken:

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

Gebruik de symbolische naam om te verwijzen naar de module in een ander deel van het Bicep-bestand. U kunt bijvoorbeeld de symbolische naam gebruiken om de uitvoer van een module op te halen. De symbolische naam kan a-z, A-Z, 0-9 en onderstrepingsteken (_) bevatten. De naam kan niet beginnen met een getal. Een module kan niet dezelfde naam hebben als een parameter, variabele of resource.

Het pad kan een lokaal bestand of een bestand in een register zijn. Het lokale bestand kan een Bicep-bestand of een ARM-sjabloon voor JSON zijn. Zie Pad naar een module voor meer informatie.

De name eigenschap is optioneel. Deze wordt de naam van de geneste implementatieresource in de gegenereerde sjabloon. Als er geen naam wordt opgegeven, wordt er een GUID gegenereerd als de naam voor de geneste implementatieresource.

Als u een module met een statische naam gelijktijdig in hetzelfde bereik implementeert, kan de ene implementatie de uitvoer van de andere implementatie verstoren. Als twee Bicep-bestanden bijvoorbeeld dezelfde module met dezelfde statische naam (examplemodule) gebruiken en zijn gericht op dezelfde resourcegroep, kan één implementatie de verkeerde uitvoer weergeven. Als u zich zorgen maakt over gelijktijdige implementaties in hetzelfde bereik, geeft u uw module een unieke naam. Een andere manier om unieke modulenamen te garanderen, is door de eigenschap name weg te laten; er wordt dan automatisch een unieke modulenaam gegenereerd. De no-module-name linter-regel is ontworpen om deze schonere coderingspraktijk af te dwingen door een module te markeren die nog steeds een expliciete name eigenschap bevat.

In het volgende voorbeeld wordt de implementatienaam samengevoegd tot de modulenaam. Als u een unieke naam opgeeft voor de implementatie, is de modulenaam ook uniek.

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

Het niet opgeven van een modulenaam is ook toegestaan. Er wordt een GUID gegenereerd als de modulenaam.

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

Als u een bereik wilt opgeven dat verschilt van het bereik voor het hoofdbestand, voegt u de bereikeigenschap toe. Zie Modulebereik instellen voor meer informatie.

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

Als u een module voorwaardelijk wilt implementeren, voegt u een if expressie toe. Dit is vergelijkbaar met het voorwaardelijk implementeren van een resource.

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

Als u meer dan één exemplaar van een module wilt implementeren, voegt u de for expressie toe. Gebruik de batchSize decorator om op te geven of de exemplaren serieel of parallel worden geïmplementeerd. Zie voor meer informatie Iteratieve lussen in 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>
  }
}]

Net als resources worden modules parallel geïmplementeerd, tenzij ze afhankelijk zijn van andere modules of resources. Normaal gesproken hoeft u geen afhankelijkheden in te stellen, omdat deze impliciet worden bepaald. Als u een expliciete afhankelijkheid wilt instellen, voegt u deze toe dependsOn aan de moduledefinitie. Zie Resourceafhankelijkheden in Bicep voor meer informatie over afhankelijkheden.

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

Pad naar een module

U kunt een lokaal bestand of een extern bestand voor de module gebruiken. U vindt het externe bestand in een sjabloonspecificatie of een Bicep moduleregister.

Lokaal bestand

Als de module een lokaal bestand is, geeft u een relatief pad naar dat bestand op. In Bicep moet u in alle paden het directoryscheidingsteken met slash (/) gebruiken om consistente compilatie op verschillende platforms te garanderen. Het Windows-teken backslash (\) wordt niet ondersteund. Paden kunnen spaties bevatten.

Als u een bestand wilt implementeren dat één niveau hoger is in de map vanuit het hoofdbestand, gebruikt u het volgende voorbeeld:

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

Bestand in het register

Er zijn openbare en privémoduleregisters.

Register van openbare module

Azure-geverifieerde modules zijn vooraf gedefinieerde, vooraf geteste en vooraf gedefinieerde modules die u kunt gebruiken om resources in Azure te implementeren. Microsoft-werknemers hebben deze modules gemaakt en bezitten. Ze vereenvoudigen en versnellen het implementatieproces voor algemene Azure resources en configuraties. De modules zijn ook afgestemd op best practices zoals Azure Well-Architected Framework.

Blader door Bicep Modules om de lijst met beschikbare modules weer te geven. Selecteer de gemarkeerde nummers in de volgende schermopname om rechtstreeks naar die gefilterde weergave te gaan:

In de modulelijst ziet u de nieuwste versie. Selecteer het versienummer om een lijst met beschikbare versies weer te geven.

Als u een koppeling wilt maken naar een openbare module, geeft u het modulepad op met de volgende syntaxis:

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

• br/public: dit is de alias voor openbare modules. U kunt deze alias aanpassen in het Bicep-configuratiebestand.
• bestandspad: dit kan segmenten bevatten die u scheidt met het / teken.
• tag: Hiermee geeft u een versie voor de module op.

Voorbeeld:

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

Privémoduleregister

Als u een module naar een register hebt gepubliceerd, kunt u een koppeling naar die module maken. Geef de naam op voor het Azure-containerregister en een pad naar de module. Geef het modulepad op met de volgende syntaxis:

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

• br: Dit is een schemanaam voor een Bicep-register.
• bestandspad: dit wordt repository genoemd in Azure Container Registry. Het bestandspad kan segmenten bevatten die worden gescheiden door het / teken.
• tag: Hiermee geeft u een versie voor de module op.

Voorbeeld:

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

Wanneer u naar een module in een register verwijst, roept bicep restore de Bicep-extensie in Visual Studio Code automatisch aan om de externe module naar de lokale cache te kopiëren. Het duurt even voordat de externe module is hersteld. Als IntelliSense voor de module niet onmiddellijk werkt, wacht u totdat het herstellen is voltooid.

Het volledige pad voor een module in een register kan lang zijn. In plaats van het volledige pad op te geven telkens wanneer u de module wilt gebruiken, configureert u aliassen in het bicepconfig.json-bestand. De aliassen maken het gemakkelijker om naar de module te verwijzen. Met een alias kunt u bijvoorbeeld het pad verkorten naar:

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

Het register van de openbare module heeft een vooraf gedefinieerde alias:

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

U kunt de openbare alias in het bicepconfig.json-bestand overschrijven.

Vanaf Bicep CLI v0.43.1 blokkeert de Bicep het gebruik van aangepaste domeinen expliciet bij het verwijzen naar of herstellen van modules vanuit een Azure Container Registry (ACR). Deze beveiliging voorkomt het gebruik van niet-ondersteunde configuraties die anders nalevingsproblemen veroorzaken.

Als u probeert te verwijzen naar een aangepast domein, zoalsmoduleStore.myCompany.com, retourneert de Bicep CLI diagnostische fout BCP446. Voorbeeld:

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

Bicep valideert alle registerhostnamen op basis van een ingebouwde acceptatielijst. Op dit moment zijn alleen de volgende domeinen toegestaan:

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

Als uw organisatie aangepaste domeinen gebruikt, werkt u uw Bicep-bestanden bij om te voldoen aan deze beperkingen:

• Terugkeren naar systeemeigen hostnamen: Werk alle Bicep moduleverwijzingen bij om het systeemeigen .azurecr.io (of relevante cloudspecifieke) domein te gebruiken.
• Lokale cache wissen: Nadat u uw verwijzingen hebt bijgewerkt, moet u mogelijk de lokale modulecache wissen. Voer bicep restore opnieuw uit om de modules op te halen met behulp van de gecorrigeerde systeemeigen hostnamen.

Bestand in template specificatie

Nadat u een sjabloonspecificatie hebt gemaakt, koppelt u deze sjabloonspecificatie in een module. Geef de sjabloonspecificatie op in de volgende indeling:

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

Als u het Bicep-bestand wilt vereenvoudigen, maakt u een alias voor de resourcegroep die de sjabloonspecificaties bevat. Wanneer u een alias gebruikt, wordt de syntaxis:

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

In de volgende module wordt een sjabloonspecificatie geïmplementeerd om een opslagaccount te maken. Het abonnement en de resourcegroep voor de sjabloonspecificatie worden gedefinieerd in de alias met de naam ContosoSpecs.

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

Decorators gebruiken

Schrijf decorators in de indeling @expression en plaats ze boven moduledeclaraties. In de volgende tabel ziet u de beschikbare decorators voor modules:

Decorators bevinden zich in de sys-naamruimte. Als u een decorator wilt onderscheiden van een ander item met dezelfde naam, moet u het decorator vooraf laten gaan door sys. Als uw Bicep-bestand bijvoorbeeld een parameter met de naam descriptionbevat, moet u de sys naamruimte toevoegen wanneer u de description decorator gebruikt.

BatchSize

U kunt @batchSize() alleen toepassen op een resource- of moduledefinitie die gebruikmaakt van een for expressie.

De implementatie-engine implementeert standaard modules parallel. Wanneer u de @batchSize(int) decorator toevoegt, implementeert u exemplaren serieel.

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

Zie Implementeren in batches voor meer informatie.

Description

Als u uitleg wilt toevoegen, voegt u een beschrijving toe aan moduledeclaraties. Voorbeeld:

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

U kunt markdown-opgemaakte tekst gebruiken voor de beschrijvingstekst.

Parameters

De parameters die u in de moduledefinitie opgeeft, komen overeen met de parameters in het Bicep-bestand.

Het volgende Bicep-voorbeeld heeft drie parameters: storagePrefix, storageSKUen location. De storageSKU parameter heeft een standaardwaarde, dus u hoeft tijdens de implementatie geen waarde op te geven voor die parameter.

@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

Als u het voorgaande voorbeeld als een module wilt gebruiken, geeft u waarden op voor deze parameters.

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

Modulebereik instellen

Wanneer u een module declareert, stelt u een bereik in voor de module die verschilt van het bereik voor het Bicep-bestand dat deze bevat. Gebruik de scope eigenschap om het bereik voor de module in te stellen. Wanneer u de scope eigenschap niet opgeeft, wordt de module geïmplementeerd op het doelbereik van het bovenliggende item.

Met het volgende Bicep-bestand maakt u een resourcegroep en een opslagaccount in die resourcegroep. Het bestand wordt geïmplementeerd in een abonnement, maar de module is gescopeerd voor de nieuwe resourcegroep.

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

In het volgende voorbeeld worden opslagaccounts geïmplementeerd in twee verschillende resourcegroepen. Beide resourcegroepen moeten al bestaan.

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

Stel de scope eigenschap in op een geldig bereikobject. Als uw Bicep-bestand een resourcegroep, abonnement of beheergroep implementeert, stelt u het bereik voor een module in op de symbolische naam voor die resource. Of gebruik de bereikfuncties om een geldig bereik op te halen.

Deze functies zijn:

• resourceGroup
• subscription
• managementGroup
• tenant

In het volgende voorbeeld wordt de managementGroup functie gebruikt om het bereik in te stellen.

param managementGroupName string

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

Output

U kunt waarden ophalen uit een module en deze gebruiken in het belangrijkste Bicep-bestand. Als u een uitvoerwaarde van een module wilt ophalen, gebruikt u de outputs eigenschap in het moduleobject.

In het eerste voorbeeld wordt een opslagaccount gemaakt en worden de primaire eindpunten geretourneerd:

@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

Wanneer u de eigenschap als module gebruikt, kunt u deze uitvoerwaarde ophalen:

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

Met behulp van Bicep versie 0.35.1 of hoger kunt u de @secure() decorator toepassen op module-uitvoer om ze als gevoelig te markeren, zodat hun waarden niet worden weergegeven in logboeken of implementatiegeschiedenis. Deze methode is handig wanneer een module gevoelige gegevens, zoals een gegenereerde sleutel of verbindingsreeks, moet retourneren aan het bovenliggende Bicep-bestand zonder risico's te lopen. Zie Beveiligde uitvoer voor meer informatie.

Module-identiteit

Vanaf Bicep versie 0.36.1 kunt u een door de gebruiker toegewezen beheerde identiteit toewijzen aan een module. Deze identiteit is beschikbaar in de module, bijvoorbeeld voor toegang tot een Key Vault. Back-endservices bieden echter nog geen ondersteuning voor deze mogelijkheid.

param identityId string

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

Verwante inhoud

• Gebruik de getSecret functie om een gevoelige waarde door te geven aan een module.