Bicep-moduler

Artikel
10/16/2024

Med Bicep kan du organisera distributioner i moduler. En modul är en Bicep-fil (eller en Azure Resource Manager JSON-mall) som distribueras från en annan Bicep-fil. Med moduler kan du förbättra läsbarheten för dina Bicep-filer genom att kapsla in komplex information om distributionen. Du kan också enkelt återanvända moduler för olika distributioner.

Om du vill dela moduler med andra personer i din organisation skapar du en mallspecifikation eller ett privat register. Mallspecifikationer och moduler i registret är endast tillgängliga för användare med rätt behörighet.

Dricks

Valet mellan modulregister och mallspecifikationer är främst en fråga om inställningar. Det finns några saker att tänka på när du väljer mellan de två:

Modulregistret stöds endast av Bicep. Om du ännu inte använder Bicep använder du mallspecifikationer.
Innehåll i Bicep-modulregistret kan bara distribueras från en annan Bicep-fil. Mallspecifikationer kan distribueras direkt från API:et, Azure PowerShell, Azure CLI och Azure-portalen. Du kan till och med använda UiFormDefinition för att anpassa portaldistributionsupplevelsen.
Bicep har vissa begränsade funktioner för inbäddning av andra projektartefakter (inklusive icke-Bicep- och icke-ARM-mallfiler. Till exempel PowerShell-skript, CLI-skript och andra binärfiler) med hjälp loadTextContent av funktionerna och loadFileAsBase64 . Mallspecifikationer kan inte paketera dessa artefakter.

Bicep-moduler konverteras till en enda Azure Resource Manager-mall med kapslade mallar. Mer information om hur Bicep löser konfigurationsfiler och hur Bicep sammanfogar användardefinierad konfigurationsfil med standardkonfigurationsfilen finns i Konfigurationsfilmatchningsprocess och Sammanslagning av konfigurationsfil.

Utbildningsresurser

Om du hellre vill lära dig mer om moduler via stegvis vägledning kan du läsa Skapa komposterbara Bicep-filer med hjälp av moduler.

Definiera moduler

Den grundläggande syntaxen för att definiera en modul är:

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

Så ett enkelt, verkligt exempel skulle se ut så här:

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

Du kan också använda en ARM JSON-mall som en modul:

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

Använd det symboliska namnet för att referera till modulen i en annan del av Bicep-filen. Du kan till exempel använda det symboliska namnet för att hämta utdata från en modul. Det symboliska namnet kan innehålla a-z, A-Z, 0-9 och understreck (_). Namnet kan inte börja med ett tal. En modul kan inte ha samma namn som en parameter, variabel eller resurs.

Sökvägen kan vara antingen en lokal fil eller en fil i ett register. Den lokala filen kan vara antingen en Bicep-fil eller en ARM JSON-mall. Mer information finns i Sökväg till modul.

Namnegenskapen krävs. Det blir namnet på den kapslade distributionsresursen i den genererade mallen.

Om en modul med ett statiskt namn distribueras samtidigt till samma omfång finns det potential att en distribution stör utdata från den andra distributionen. Om två Bicep-filer till exempel använder samma modul med samma statiska namn (examplemodule) och riktar sig till samma resursgrupp kan en distribution visa fel utdata. Om du är orolig för samtidiga distributioner till samma omfång ger du modulen ett unikt namn.

I följande exempel sammanfogas distributionsnamnet till modulnamnet. Om du anger ett unikt namn för distributionen är modulnamnet också unikt.

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

Om du behöver ange ett omfång som skiljer sig från omfånget för huvudfilen lägger du till omfångsegenskapen. Mer information finns i Ange modulomfång.

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

Om du vill distribuera en modul villkorligt lägger du till ett if uttryck. Användningen liknar villkorlig distribution av en resurs.

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

Om du vill distribuera mer än en instans av en modul lägger du till uttrycket for . Du kan använda dekoratören batchSize för att ange om instanserna ska distribueras seriellt eller parallellt. Mer information finns i Iterativa loopar i 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>
  }
}]

Precis som resurser distribueras moduler parallellt såvida de inte är beroende av andra moduler eller resurser. Vanligtvis behöver du inte ange beroenden eftersom de bestäms implicit. Om du behöver ange ett explicit beroende kan du lägga till dependsOn i moduldefinitionen. Mer information om beroenden finns i Resursberoenden.

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

Sökväg till modul

Filen för modulen kan vara antingen en lokal fil eller en extern fil. Den externa filen kan finnas i mallspecifikationen eller i ett Bicep-modulregister.

Lokal fil

Om modulen är en lokal fil anger du en relativ sökväg till filen. Alla sökvägar i Bicep måste anges med hjälp av katalogavgränsaren för snedstreck (/) för att säkerställa konsekvent kompilering mellan plattformar. Windows-omvänt snedstreck (\) stöds inte. Sökvägar kan innehålla blanksteg.

Om du till exempel vill distribuera en fil som är upp en nivå i katalogen från huvudfilen använder du:

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

Fil i registret

Register över offentliga moduler

Kommentar

Moduler som inte är AVM-moduler (Azure-verifierade moduler) dras tillbaka från det offentliga modulregistret.

Azure-verifierade moduler är fördefinierade, förtestade och förverifierade moduler för distribution av resurser i Azure. Modulerna har skapats och ägs av Microsoft-anställda och är utformade för att förenkla och påskynda distributionsprocessen för vanliga Azure-resurser och konfigurationer samtidigt som de överensstämmer med bästa praxis. t.ex. well-architected Framework.

Bläddra till Azure Verified Modules Bicep Indexför att se listan över tillgängliga moduler, välj de markerade numren i följande skärmbild som ska tas direkt till den filtrerade vyn.

Skärmbilden av Azure Verified Modules (AVM).

Modullistan visar den senaste versionen. Välj versionsnumret för att se en lista över tillgängliga versioner:

Skärmbilden av AvM-versioner (Azure Verified Modules).

Om du vill länka till en offentlig modul anger du modulsökvägen med följande syntax:

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

br/public är aliaset för offentliga moduler. Du kan anpassa det här aliaset i Bicep-konfigurationsfilen.
filsökväg kan innehålla segment som kan avgränsas med / tecknet.
-taggen används för att ange en version för modulen.

Till exempel:

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

Kommentar

br/public är aliaset för offentliga moduler. Den kan också skrivas som:

module <symbolic-name> 'br:mcr.microsoft.com/bicep/<file-path>:<tag>' = {}

Privat modulregister

Om du har publicerat en modul till ett register kan du länka till modulen. Ange namnet på Azure-containerregistret och en sökväg till modulen. Ange modulsökvägen med följande syntax:

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

br är schemanamnet för ett Bicep-register.
filsökvägen anropas repository i Azure Container Registry. Filsökvägen kan innehålla segment som avgränsas med / tecknet.
-taggen används för att ange en version för modulen.

Till exempel:

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

När du refererar till en modul i ett register anropar Bicep-tillägget i Visual Studio Code automatiskt bicep-återställning för att kopiera den externa modulen till den lokala cachen. Det tar en stund att återställa den externa modulen. Om intellisense för modulen inte fungerar omedelbart väntar du tills återställningen har slutförts.

Den fullständiga sökvägen för en modul i ett register kan vara lång. I stället för att ange den fullständiga sökvägen varje gång du vill använda modulen kan du konfigurera alias i bicepconfig.json-filen. Aliasen gör det enklare att referera till modulen. Med ett alias kan du till exempel förkorta sökvägen till:

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

Ett alias för det offentliga modulregistret har fördefinierades:

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

Du kan åsidosätta det offentliga aliaset i filen bicepconfig.json.

Fil i mallspecifikation

När du har skapat en mallspecifikation kan du länka till mallspecifikationen i en modul. Ange mallspecifikationen i följande format:

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

Du kan dock förenkla Bicep-filen genom att skapa ett alias för resursgruppen som innehåller mallspecifikationerna. När du använder ett alias blir syntaxen:

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

Följande modul distribuerar en mallspecifikation för att skapa ett lagringskonto. Prenumerationen och resursgruppen för mallspecifikationen definieras i aliaset ContosoSpecs.

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

Använda dekoratörer

Dekoratörer är skrivna i formatet @expression och placeras ovanför moduldeklarationer. I följande tabell visas tillgängliga dekoratörer för moduler.

Dekoratör	Argument	beskrivning
batchSize	inget	Konfigurera instanser för att distribuera sekventiellt.
beskrivning	sträng	Ange beskrivningar för modulen.

Dekoratörer finns i sys-namnområdet. Om du behöver skilja en dekoratör från ett annat objekt med samma namn, förorda dekoratören med sys. Om din Bicep-fil till exempel innehåller en parameter med namnet descriptionmåste du lägga till sys-namnområdet när du använder beskrivningsdekoratören.

BatchSize

Du kan bara använda @batchSize() en resurs- eller moduldefinition som använder ett for uttryck.

Som standard distribueras moduler parallellt. När du lägger till dekoratören @batchSize(int) distribuerar du instanser seriellt.

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

Mer information finns i Distribuera i batchar.

beskrivning

Lägg till en förklaring genom att lägga till en beskrivning i moduldeklarationer. Till exempel:

@description('Create storage accounts referencing an AVM.')
module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Markdown-formaterad text kan användas för beskrivningstexten.

Parametrar

De parametrar som du anger i moduldefinitionen matchar parametrarna i Bicep-filen.

Följande Bicep-exempel har tre parametrar – storagePrefix, storageSKU och plats. Parametern storageSKU har ett standardvärde så att du inte behöver ange något värde för parametern under distributionen.

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

output storageEndpoint object = stg.properties.primaryEndpoints

Om du vill använda föregående exempel som en modul anger du värden för dessa parametrar.

targetScope = 'subscription'

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

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

Ange modulomfång

När du deklarerar en modul kan du ange ett omfång för modulen som skiljer sig från omfånget för den innehållande Bicep-filen. Använd egenskapen scope för att ange modulens omfång. När omfångsegenskapen inte tillhandahålls distribueras modulen i det överordnade målomfånget.

Följande Bicep-fil skapar en resursgrupp och ett lagringskonto i den resursgruppen. Filen distribueras till en prenumeration, men modulen är begränsad till den nya resursgruppen.

// 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@2024-03-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

I nästa exempel distribueras lagringskonton till två olika resursgrupper. Båda dessa resursgrupper måste redan finnas.

targetScope = 'subscription'

resource firstRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2024-03-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'
  }
}

Ange omfångsegenskapen till ett giltigt omfångsobjekt. Om din Bicep-fil distribuerar en resursgrupp, prenumeration eller hanteringsgrupp kan du ange omfånget för en modul till det symboliska namnet för resursen. Du kan också använda omfångsfunktionerna för att få ett giltigt omfång.

De här funktionerna är:

I följande exempel används managementGroup funktionen för att ange omfånget.

param managementGroupName string

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

Output

Du kan hämta värden från en modul och använda dem i huvudfilen för Bicep. Om du vill hämta ett utdatavärde från en modul använder du outputs egenskapen för modulobjektet.

Det första exemplet skapar ett lagringskonto och returnerar de primära slutpunkterna.

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

output storageEndpoint object = stg.properties.primaryEndpoints

När du används som modul kan du hämta utdatavärdet.

targetScope = 'subscription'

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

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

Nästa steg

En självstudiekurs finns i Distribuera Azure-resurser med hjälp av Bicep-mallar.
Om du vill skicka ett känsligt värde till en modul använder du funktionen getSecret .

Dela via