Lägga till parametrar och utdata i moduler

  • 7 minuter

Varje modul som du skapar bör ha ett tydligt syfte. Tänk på en modul som att ha ett kontrakt. Den accepterar en uppsättning parametrar, skapar en uppsättning resurser och kan ge vissa utdata tillbaka till den överordnade mallen. Den som använder modulen behöver inte oroa sig för hur den fungerar, bara att den gör vad de förväntar sig.

När du planerar en modul bör du tänka på följande:

  • Vad du behöver veta för att kunna uppfylla modulens syfte.
  • Vad alla som använder din modul förväntar sig att tillhandahålla.
  • Vad alla som använder modulen förväntar sig att komma åt som utdata.

Modulparametrar

Tänk på de parametrar som modulen accepterar och om varje parameter ska vara valfri eller obligatorisk.

När du skapar parametrar för mallar är det bra att lägga till standardparametrar där du kan. I moduler är det inte alltid lika viktigt att lägga till standardparametrar eftersom modulen används av en överordnad mall som kan använda sina egna standardparametrar. Om du har liknande parametrar i båda filerna, båda med standardvärden, kan det vara svårt för mallens användare att ta reda på vilket standardvärde som ska tillämpas och framtvinga konsekvens. Det är ofta bättre att lämna standardvärdet på den överordnade mallen och ta bort det från modulen.

Du bör också tänka på hur du hanterar parametrar som styr SKU:erna för dina resurser och andra viktiga konfigurationsinställningar. När du skapar en fristående Bicep-mall är det vanligt att bädda in affärsregler i mallen. Till exempel: När jag distribuerar en produktionsmiljö bör lagringskontot använda GRS-nivån. Men moduler presenterar ibland olika problem.

Om du skapar en modul som måste vara återanvändbar och flexibel bör du komma ihåg att affärsreglerna för varje överordnad mall kan vara olika, så det kanske inte är lika meningsfullt att bädda in affärsregler i generiska moduler. Överväg att definiera affärsreglerna i den överordnade mallen och sedan uttryckligen skicka modulkonfigurationen via parametrar.

Men om du skapar en modul som är avsedd att göra det enkelt för din egen organisation att distribuera resurser som passar dina specifika behov är det klokt att inkludera affärsregler för att förenkla de överordnade mallarna.

Oavsett vilka parametrar du tar med i modulen ser du till att du lägger till en beskrivande beskrivning med hjälp av attributet @description :

@description('The name of the storage account to deploy.')
param storageAccountName string

Använda villkor

Ett av målen med att distribuera en infrastruktur med hjälp av kod som Bicep är att undvika duplicering av arbete, eller till och med att skapa flera mallar för samma eller liknande ändamål. Biceps funktioner ger dig en kraftfull verktygslåda för att skapa återanvändbara moduler som fungerar i olika situationer. Du kan kombinera funktioner som moduler, uttryck, standardparametervärden och villkor för att skapa återanvändbar kod som ger dig den flexibilitet du behöver.

Anta att du skapar en modul som distribuerar ett Azure Cosmos DB-konto. När det distribueras till produktionsmiljön måste du konfigurera kontot så att det skickar loggarna till en Log Analytics-arbetsyta. Om du vill konfigurera loggar som ska skickas till Log Analytics definierar du en diagnostikuppsättningsresurs .

Du kan uppfylla dina krav genom att lägga till ett villkor i resursdefinitionen och göra parametern för arbetsyte-ID valfri genom att lägga till ett standardvärde:

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

När du inkluderar den här modulen i en Bicep-mall kan du enkelt konfigurera den för att skicka Azure Cosmos DB-kontologgarna till Log Analytics genom att ange ett arbetsyte-ID. Om du inte behöver loggar för miljön som du distribuerar utelämnar du parametern. Den har ett standardvärde. Modulen kapslar in den logik som krävs för att göra det rätta för dina behov.

Dricks

Kom ihåg att testa att mallen är giltig för båda scenarierna. när -instruktionen if utvärderas som antingen true eller false.

Modulutdata

Moduler kan definiera utdata. Det är en bra idé att skapa utdata för den information som den överordnade mallen kan behöva använda. Om modulen till exempel definierar ett lagringskonto bör du överväga att skapa utdata för lagringskontots namn så att den överordnade mallen kan komma åt det.

Varning

Använd inte utdata för hemliga värden. Utdata loggas som en del av distributionshistoriken, så de är inte lämpliga för säkra värden. Du kan i stället överväga något av följande alternativ:

  • Använd utdata för att ange resursens namn. Sedan kan den överordnade mallen skapa en existing resurs med det namnet och leta upp det säkra värdet dynamiskt.
  • Skriv värdet till en Azure Key Vault-hemlighet. Be den överordnade mallen att läsa hemligheten från valvet när den behöver den.

En överordnad mall kan använda modulutdata i variabler, använda egenskaper för andra resursdefinitioner eller exponera variabler och egenskaper som själva utdata. Genom att exponera och använda utdata i dina Bicep-filer kan du skapa återanvändbara uppsättningar med Bicep-moduler som kan delas med ditt team och återanvändas i flera distributioner. Det är också en bra idé att lägga till en beskrivande beskrivning i utdata med hjälp av attributet @description :

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

Dricks

Du kan också använda dedikerade tjänster för att lagra, hantera och komma åt de inställningar som din Bicep-mall skapar. Key Vault är utformat för att lagra säkra värden. Azure App Configuration är utformat för att lagra andra (icke-säkra) värden.

Kedja ihop moduler

Det är vanligt att skapa en överordnad Bicep-fil som består av flera moduler tillsammans. Anta till exempel att du skapar en ny Bicep-mall för att distribuera virtuella datorer som använder dedikerade virtuella nätverk. Du kan skapa en modul för att definiera ett virtuellt nätverk. Du kan sedan ta det virtuella nätverkets resurs-ID för undernätet som utdata från modulen och använda det som indata till modulen för den virtuella datorn:

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

I det här exemplet används symboliska namn för referensen mellan modulerna. Den här referensen hjälper Bicep att automatiskt förstå relationerna mellan modulerna.

Eftersom Bicep förstår att det finns ett beroende distribuerar det modulerna i ordning:

  1. Bicep distribuerar allt i modulen virtualNetwork .
  2. Om distributionen lyckas kommer Bicep åt subnetResourceId utdatavärdet och skickar det till modulen virtualMachine som en parameter.
  3. Bicep distribuerar allt i modulen virtualMachine .

Kommentar

När du är beroende av en modul väntar Bicep på att hela moduldistributionen ska slutföras. Det är viktigt att komma ihåg detta när du planerar dina moduler. Om du skapar en modul som definierar en resurs som tar lång tid att distribuera väntar alla andra resurser som är beroende av modulen tills hela modulens distribution slutförs.