Delen via

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. Met modules 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.

Tip

De keuze tussen moduleregister en sjabloonspecificaties is meestal een kwestie van voorkeur. Er zijn enkele dingen die u moet overwegen wanneer u kiest tussen de twee:

  • Moduleregister wordt alleen ondersteund door Bicep. Als u Bicep niet gebruikt, gebruikt u sjabloonspecificaties.
  • U kunt alleen inhoud in het Bicep-moduleregister implementeren vanuit een ander Bicep-bestand. U kunt sjabloonspecificaties rechtstreeks implementeren vanuit de API, Azure PowerShell, de Azure CLI en Azure Portal. U kunt zelfs UiFormDefinition gebruiken om de implementatie-ervaring van de portal aan te passen.
  • Bicep biedt beperkte mogelijkheden voor het insluiten van andere projectartefacten (waaronder niet-Bicep- en niet-ARM-sjabloonbestanden zoals PowerShell-scripts, CLI-scripts en andere binaire bestanden) met behulp van de loadTextContent en loadFileAsBase64 functies. Sjabloonspecificaties kunnen deze artefacten niet verpakken.

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 een module met een statische naam gelijktijdig wordt geïmplementeerd in hetzelfde bereik, 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 ervoor te zorgen dat modulenamen uniek zijn, is door de name eigenschap weg te laten; er zal automatisch een unieke modulenaam worden gegenereerd.

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 anders is dan 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

Het bestand voor de module kan een lokaal bestand of een extern bestand zijn. Het externe bestand kan een sjabloonspecificatie of een Bicep-moduleregister hebben.

Lokaal bestand

Als de module een lokaal bestand is, geeft u een relatief pad naar dat bestand op. Alle paden in Bicep moeten worden gespecificeerd met de schuine streep (/) als scheidingsteken om consistente compilatie op verschillende platforms te garanderen. Het Windows-teken backslash (\) wordt niet ondersteund. Paden kunnen spaties bevatten.

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

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

Bestand in het register

Er zijn openbare en privémoduleregisters.

Register van openbare module

Note

Niet-Azure-geverifieerde modules worden buiten gebruik gesteld van het openbare moduleregister.

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 zijn ontworpen om het implementatieproces voor algemene Azure-resources en -configuraties te vereenvoudigen en te versnellen. 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:

Schermopname van geverifieerde Azure-modules.

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

Schermopname van versies van Azure Verified Modules.

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 kunt scheiden met het / teken.
  • tag: Dit wordt gebruikt voor het opgeven van een versie voor de module.

Voorbeeld:

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

Note

De alias voor openbare modules is br/public. U kunt deze ook schrijven als:

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: Wordt gebruikt om een versie voor de module op te geven.

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.

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

Decorators worden geschreven in de indeling @expression en worden boven moduledeclaraties geplaatst. In de volgende tabel ziet u de beschikbare decorators voor modules:

Decorator Argument Description
batchSize none Stel exemplaren in om sequentieel te implementeren.
description string Geef beschrijvingen op voor de module.

Decorators bevinden zich in de sys-naamruimte. Als u een decorator wilt onderscheiden van een ander item met dezelfde naam, moet u de 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.

Modules worden standaard parallel geïmplementeerd. 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 anders is dan het bereik voor het Bicep-bestand dat deze bevat. Gebruik de scope eigenschap om het bereik voor de module in te stellen. Wanneer de scope eigenschap niet wordt verstrekt, wordt de module ingezet op het doelbereik van de ouder.

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, kunt u het bereik voor een module instellen op de symbolische naam voor die resource. U kunt ook de bereikfuncties gebruiken om een geldig bereik op te halen.

Deze functies zijn:

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 de eigenschap wordt gebruikt als een module, kunt u die 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 Bicep versie 0.35.1 en hoger kan de @secure() decorator worden toegepast op module-uitvoer om ze als gevoelig te markeren, zodat hun waarden niet worden weergegeven in logboeken of implementatiegeschiedenis. Dit 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. Hierdoor is de identiteit beschikbaar in de module, bijvoorbeeld voor toegang tot een Sleutelkluis. Deze mogelijkheid is echter bedoeld voor toekomstig gebruik en wordt nog niet ondersteund door back-endservices.

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.
  • Last updated on