Bicep-moduler

Artikel
11/20/2021
7 minuter för att läsa

Med Bicep kan du organisera distributioner i moduler. En modul är bara en Bicep-fil som distribueras från en annan Bicep-fil. Med moduler förbättrar du 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 mallspecifikt eller privat register. Mallspecifikter och moduler i registret är bara tillgängliga för användare med rätt behörigheter.

Tips

Valet mellan mallspecifikter och privata register är främst en fråga om prioritet. Om du distribuerar mallar eller Bicep-filer utan andra projektartefakter är mallspecifikter ett enklare alternativ. Om du distribuerar projektartefakter med mallarna eller Bicep-filerna kan du integrera det privata registret med ditt utvecklingsarbete och sedan enklare distribuera allt från registret.

Bicep-moduler konverteras till en enda Azure Resource Manager med kapslade mallar.

Microsoft Learn

Mer information om moduler och praktisk vägledning finns i Skapa sammansättningsbara Bicep-filer med hjälp av moduler på Microsoft Learn.

Definitionssyntax

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

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

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 får 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. Mer information finns i Sökväg till modul.

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

Om du behöver ange ett annat omfång ä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 fler än en instans av en modul lägger du till uttrycket for . Du kan använda batchSize målaren 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 om de inte är beroende av andra moduler eller resurser. Normalt behöver du inte ange beroenden eftersom de fastställs 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. Alla dessa alternativ visas nedan.

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. Det Windows omsnedstrecket ( \ ) 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

Om du har publicerat en modul till ett registerkan du länka till den 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 repository anropas i Azure Container Registry. Filsökvägen kan innehålla segment som avgränsas med / tecknet .
tagg används för att ange en version för modulen.

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 till 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 filen bicepconfig.json. 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'
  }
}

Fil i mallspecifikt

När du har skapat en mallspecifiktkan 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 din Bicep-fil genom att skapa ett alias för resursgruppen som innehåller dina mallspecifikter. När du använder ett alias blir syntaxen:

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

I följande modul distribueras en mallspecifikt för att skapa ett lagringskonto. Prenumerationen och resursgruppen för mallspecifikationen definieras i aliaset med namnet ContosoSpecs.

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

Parametrar

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

Följande Bicep-exempel har tre parametrar – storagePrefix, storageSKU och location. Parametern storageSKU har ett standardvärde så du behöver inte ange ett värde för den 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@2021-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@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

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 omfånget för modulen. När omfångsegenskapen inte anges distribueras modulen i det överordnade omfå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@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

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

Ange omfångsegenskapen till ett giltigt omfångsobjekt. Om bicep-filen distribuerar en resursgrupp, prenumeration eller hanteringsgrupp kan du ange det symboliska namnet för en modul för den resursen. Eller så kan du använda omfångsfunktionerna för att få ett giltigt omfång.

De här funktionerna är:

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

param managementGroupName string

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

Utdata

Du kan hämta värden från en modul och använda dem i bicep-huvudfilen. Om du vill hämta ett utdatavärde från en modul använder outputs du 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@2021-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

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

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

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.