Bicep-modules

Met Bicep kunt u implementaties organiseren in modules. Een module is slechts een Bicep-bestand dat 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 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 Azure Resource Manager sjabloon met geneste sjablonen.

Microsoft Learn

Zie Samen te stellen Bicep-bestanden maken met behulp van modules op Microsoft Learn voor meer informatie over modules 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 uit de echte wereld ziet er dan als volgende uit:

module stgModule '../storageAccount.bicep' = {
  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 mag 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. Zie Pad naar module voor meer informatie.

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

Als u een bereik moet opgeven dat verschilt van het bereik voor het hoofdbestand, voegt u de eigenschap scope toe. Zie Set module scope (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 expressie if 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 expressie for toe. U kunt deator gebruiken om op te geven of de exemplaren batchSize 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 deze impliciet worden bepaald. Als u een expliciete afhankelijkheid moet 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 de sjabloonspecificatie of een Bicep-moduleregister. 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 mapscheidingsteken slash (/) om consistente compilatie tussen platformen te garanderen. Het 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

Als u een module naar een register hebt gepubliceerd,kunt u een koppeling naar die module maken. Geef de naam voor het Azure-containerregister en een pad naar de module op. 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 repository aangeroepen in Azure Container Registry. Het bestandspad kan segmenten bevatten die worden gescheiden door het / teken.
• 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 verwijst naar een module in een register, roept de Bicep-extensie in Visual Studio Code automatisch bicep restore aan om de externe module naar de lokale cache te kopiëren. Het duurt even om de externe module te herstellen. Als IntelliSense voor de module niet onmiddellijk werkt, wacht u tot het herstellen is voltooid.

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

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

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 met de naam ContosoSpecs.

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

Parameters

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

Het volgende Bicep-voorbeeld heeft drie parameters: storagePrefix, storageSKU en location. 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

Bij het declareren van een module kunt u een bereik instellen voor de module dat verschilt van het bereik voor het bicep-bestand. Gebruik de scope eigenschap om het bereik voor de module in te stellen. Wanneer de eigenschap scope niet is opgegeven, wordt de module geïmplementeerd op het bovenliggende doelbereik.

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 beperkt tot 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 eigenschap scope 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:

• resourceGroup
• Abonnement
• 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)
}

Uitvoer

U kunt waarden uit een module op halen en deze gebruiken in het hoofdbestand bicep. Gebruik de eigenschap van het moduleobject om een uitvoerwaarde van een outputs module op te halen.

In het eerste voorbeeld wordt een opslagaccount gemaakt en worden de primaire eindpunten retourneert.

@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 krijgen.

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.
• Als u een gevoelige waarde wilt doorgeven aan een module, gebruikt u de functie getSecret.