Bicep-modules

Artikel
02/02/2024

Met Bicep kunt u implementaties in modules organiseren. Een module is een Bicep-bestand (of een ARM JSON-sjabloon) die is geïmplementeerd vanuit een ander Bicep-bestand. 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, een openbaar register 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 nog niet gebruikt, gebruikt u sjabloonspecificaties.
Inhoud in het Bicep-moduleregister kan alleen worden geïmplementeerd vanuit een ander Bicep-bestand. Sjabloonspecificaties kunnen rechtstreeks vanuit de API, Azure PowerShell, Azure CLI en Azure Portal worden geïmplementeerd. U kunt zelfs de implementatie-ervaring van de portal aanpassen UiFormDefinition .
Bicep heeft een aantal beperkte mogelijkheden voor het insluiten van andere projectartefacten (waaronder niet-Bicep- en niet-ARM-sjabloonbestanden). Bijvoorbeeld 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 Azure Resource Manager-sjabloon met geneste sjablonen. Voor meer informatie over hoe Bicep configuratiebestanden oplost en hoe Bicep 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.

Trainingsmateriaal

Als u liever meer wilt weten over modules via stapsgewijze richtlijnen, raadpleegt u Samenstelbare Bicep-bestanden maken met behulp van modules.

Definitiesyntaxis

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

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 JSON-sjabloon gebruiken als een module:

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 JSON-sjabloon zijn. Zie Pad naar module voor meer informatie.

De naameigenschap is vereist. Deze wordt de naam van de geneste implementatieresource in de gegenereerde sjabloon.

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 gebruiken met dezelfde statische naam (examplemodule) en gericht zijn 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.

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

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. Het gebruik 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. U kunt de batchSize decorator gebruiken om op te geven of de exemplaren serieel of parallel worden geïmplementeerd. Zie Iteratieve lussen in Bicep voor meer informatie.

// 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 ze impliciet worden bepaald. Als u een expliciete afhankelijkheid wilt instellen, kunt u toevoegen dependsOn aan de moduledefinitie. Zie Resourceafhankelijkheden 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 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. Al deze opties worden hieronder weergegeven.

Lokaal bestand

Als de module een lokaal bestand is, geeft u een relatief pad naar dat bestand op. Alle paden in Bicep moeten worden opgegeven met behulp van het adreslijstscheidingsteken voor slash (/) om consistente compilatie tussen platforms te garanderen. Het Windows-backslashteken (\) 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 register

Register van openbare module

Het openbare moduleregister wordt gehost in een Microsoft-containerregister (MCR). De broncode en de modules worden opgeslagen in GitHub. Als u de beschikbare modules en hun versies wilt bekijken, raadpleegt u de Bicep-registermodule-index.

The screenshot of public module registry.

Selecteer de versies om de beschikbare versies te bekijken. U kunt ook broncode selecteren om de broncode van de module te bekijken en de Leesmij-bestanden te openen.

Er zijn momenteel slechts enkele gepubliceerde modules. Er komen nog meer modules. Als u graag een bijdrage wilt leveren aan het register, raadpleegt u de handleiding voor bijdragen.

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

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

br/public is de alias voor het openbare moduleregister. Deze alias is vooraf gedefinieerd in uw configuratie.
bestandspad kan segmenten bevatten die kunnen worden gescheiden door het / teken.
de tag wordt gebruikt voor het opgeven van een versie voor de module.

Bijvoorbeeld:

module hw 'br/public:samples/hello-world:1.0.2' = {
  name: 'helloWorld'
  params: {
    name: 'John Dole'
  }
}

Notitie

br/public is de alias voor het openbare register. Het kan ook worden geschreven 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 is de schemanaam voor een Bicep-register.
bestandspad wordt aangeroepen repository in Azure Container Registry. Het bestandspad kan segmenten bevatten die worden gescheiden door het / teken.
de tag wordt gebruikt voor het opgeven van een versie voor de module.

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 de Bicep-extensie in Visual Studio Code bicep-herstel 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, kunt u aliassen configureren 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'
  }
}

Er is een alias voor het register van de openbare module vooraf gedefinieerd:

module hw 'br/public:samples/hello-world:1.0.2' = {
  name: 'helloWorld'
  params: {
    name: 'John Dole'
  }
}

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

Bestand in sjabloonspecificatie

Nadat u een sjabloonspecificatie hebt gemaakt, kunt u een koppeling maken naar die sjabloonspecificatie in een module. Geef de sjabloonspecificatie op in de volgende indeling:

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

U kunt uw Bicep-bestand echter vereenvoudigen door een alias te maken 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 ContosoSpecs.

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

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, storageSKU en locatie. De parameter storageSKU heeft een standaardwaarde, zodat u tijdens de implementatie geen waarde hoeft 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@2021-04-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@2021-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 declareren, kunt u een bereik instellen voor de module die verschilt van het bereik voor het bicep-bestand. Gebruik de scope eigenschap om het bereik voor de module in te stellen. Wanneer de bereikeigenschap niet is opgegeven, 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 heeft het bereik van 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@2021-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@2021-04-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2021-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 bereikeigenschap 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)
}

Uitvoer

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

output storageEndpoint object = stg.properties.primaryEndpoints

Wanneer u deze uitvoerwaarde gebruikt als module, kunt u deze uitvoerwaarde ophalen.

targetScope = 'subscription'

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

resource demoRG 'Microsoft.Resources/resourceGroups@2021-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

Volgende stappen

Zie Azure-resources implementeren met bicep-sjablonen voor een zelfstudie.
Gebruik de functie getSecret om een gevoelige waarde door te geven aan een module.