Bicep-modules

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 opnieuw gebruiken voor verschillende implementaties.

Als u modules wilt delen met andere personen in uw organisatie, maakt u een sjabloonspecificatie, een openbaar register of een privé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 tussen de twee kiest:

  • 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 de 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 (inclusief niet-Bicep- en niet-ARM-sjabloonbestanden. PowerShell-scripts, CLI-scripts en andere binaire bestanden) bijvoorbeeld 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.

Microsoft Learn

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

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

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

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 zich in sjabloonspecificatie of een Bicep-moduleregister bevindt. 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 op verschillende platforms te garanderen. Het teken Windows backslash (\) wordt niet ondersteund. Paden kunnen spaties bevatten.

Als u bijvoorbeeld een bestand wilt implementeren dat één niveau hoger is in de map vanuit uw 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. Het README-bestand in de GitHub opslagplaats bevat de beschikbare modules en de meest recente versies:

Bicep public module registry modules

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

Er zijn momenteel slechts enkele gepubliceerde modules. Er komen 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 register van de openbare module.
  • bestandspad kan segmenten bevatten die kunnen worden gescheiden door het / teken.
  • 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>' = {}

Zie aliassen en het configureren van aliassen verderop in deze sectie voor meer informatie.

Register van privémodule

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 door het / teken worden gescheiden.
  • tag wordt gebruikt voor het opgeven van een versie voor de module.

Bijvoorbeeld:

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 bestand bicepconfig.json. Met de aliassen kunt u gemakkelijker verwijzen naar de module. Met een alias kunt u bijvoorbeeld het pad verkorten naar:

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

Een alias voor het register van de openbare module is 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 bestand bicepconfig.json overschrijven.

Bestand in sjabloonspecificatie

Nadat u een sjabloonspecificatie hebt gemaakt, kunt u deze sjabloonspecificatie in een module koppelen. 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 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 is gericht op 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 voor 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 als module gebruikt, kunt u die 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