Skapa och använda Bicep-moduler

  • 10 minuter

Moduler är oberoende Bicep-filer. De innehåller vanligtvis uppsättningar med resurser som distribueras tillsammans. Moduler kan användas från andra Bicep-mallar.

Med hjälp av moduler kan du återanvända din Bicep-kod, och du kan göra dina Bicep-filer mer läsbara och begripliga eftersom de alla fokuserar på ett specifikt jobb. Huvudmallarna skapar sedan flera moduler tillsammans.

Fördelarna med moduler

I ditt leksaksföretag har du etablerat molnresurser med hjälp av många enskilda Bicep-filer. Med tiden växer dessa mallar avsevärt. Så småningom får du monolitisk kod som är svår att läsa och navigera i, och ännu svårare att underhålla.

Den här metoden tvingar dig också att duplicera delar av koden när du vill återanvända den i andra mallar. När du ändrar något måste du söka igenom och uppdatera flera filer.

Bicep-moduler hjälper dig att hantera dessa utmaningar genom att dela upp koden i mindre, mer hanterbara filer som flera mallar kan referera till. Moduler ger dig några viktiga fördelar.

Återanvändning

När du har skapat en modul kan du återanvända den i flera Bicep-filer, även om filerna är för olika projekt eller arbetsbelastningar. När du till exempel skapar en lösning kan du skapa separata moduler för appkomponenterna, databasen och de nätverksrelaterade resurserna. När du sedan börjar arbeta med ett annat projekt med liknande nätverkskrav kan du återanvända relevant modul.

Diagram som visar en mall som refererar till tre moduler: program, databas och nätverk. Nätverksmodulen återanvänds sedan i en annan mall.

Du kan till och med dela moduler i ditt team, i din organisation eller med Azure-communityn. Du lär dig mer om att dela Bicep-moduler i en framtida Microsoft Learn-modul.

Inkapsling

Moduler hjälper dig att hålla ihop relaterade resursdefinitioner. När du till exempel definierar en Azure Functions-app distribuerar du vanligtvis appen, en värdplan för appen och ett lagringskonto för appens metadata. Dessa tre komponenter definieras separat, men de representerar en logisk gruppering av resurser, så det kan vara meningsfullt att definiera dem som en modul.

På så sätt behöver huvudmallen inte vara medveten om information om hur en funktionsapp distribueras. Det är modulens ansvar.

Sammanställning

När du har skapat en uppsättning moduler kan du skapa dem tillsammans. Du kan till exempel skapa en modul som distribuerar ett virtuellt nätverk och en annan modul som distribuerar en virtuell dator. Du definierar parametrar och utdata för varje modul så att du kan ta viktig information från en och skicka den till den andra.

Diagram som visar en mall som refererar till två moduler och skickar utdata från en till parametern för en annan.

Dricks

Det är bra att tänka på Bicep-moduler som byggstenar som du kan kombinera på olika sätt för att stödja dina distributioner.

Funktioner

Ibland kan du behöva använda moduler för att få åtkomst till vissa funktioner. Du kan till exempel använda moduler och loopar tillsammans för att distribuera flera uppsättningar resurser. Du kan också använda moduler för att definiera resurser i olika omfång i en enda distribution.

Skapa en modul

En modul är en vanlig Bicep-fil. Du skapar den precis som du gör med andra Bicep-filer.

I allmänhet är det inte bra att skapa en modul för varje resurs som du distribuerar. En bra Bicep-modul definierar vanligtvis flera relaterade resurser. Men om du har en komplex resurs med mycket konfiguration kan det vara klokt att skapa en enda modul för att kapsla in komplexiteten. Den här metoden håller dina huvudmallar enkla och ostädade.

Dela upp en befintlig Bicep-mall i moduler

Du kan bygga upp en stor Bicep-mall och sedan bestämma att den ska delas upp i moduler. Ibland är det uppenbart hur du ska dela upp en stor Bicep-fil. Du kan ha en uppsättning resurser som tydligt hör ihop i en modul. Andra gånger är det inte lika enkelt att bestämma vilka resurser som ska grupperas i en modul.

Bicep-visualiseraren kan hjälpa dig att sätta hela Bicep-filen i perspektiv. Visualiseraren ingår i Bicep-tillägget för Visual Studio Code.

Om du vill visa visualiseraren öppnar du Visual Studio Code Explorer, väljer och håller ned (eller högerklickar på) Bicep-filen och väljer sedan Öppna Bicep Visualizer. Visualiseraren visar en grafisk representation av resurserna i Bicep-filen. Den innehåller rader mellan resurser för att visa de beroenden som Bicep identifierar.

Du kan använda visualiseraren för att dela upp dina filer. Fundera på om visualiseringen illustrerar några kluster av resurser. Det kan vara bra att flytta dessa kluster till en modul tillsammans.

Tänk dig till exempel följande visualisering för en Bicep-fil. Två distinkta uppsättningar med resurser definieras. Det kan vara bra att gruppera dem i separata databas- och nätverksmoduler.

Kapsla moduler

Moduler kan innehålla andra moduler. Med hjälp av den här kapslingstekniken kan du skapa några moduler som distribuerar små uppsättningar resurser och sedan skapa dem i större moduler som definierar komplexa topologier för resurser. En mall kombinerar dessa delar till en distribuerbar artefakt.

Dricks

Även om det är möjligt att kapsla flera lager av moduler kan det bli komplext. Om du får ett fel eller om något annat går fel är det svårare att ta reda på vad du behöver åtgärda när du har många lager av kapsling.

För komplexa distributioner är det ibland klokt att använda distributionspipelines för att distribuera flera mallar i stället för att skapa en enda mall som gör allt med kapsling. Du får lära dig mer om distributionspipelines i en framtida Microsoft Learn-modul.

Välj bra filnamn

Se till att använda ett beskrivande filnamn för varje modul. Filnamnet blir i praktiken identifieraren för modulen. Det är viktigt att dina kollegor kan förstå modulens syfte bara genom att titta på filnamnet.

Använda modulen i en Bicep-mall

Du använder en modul i en Bicep-mall med hjälp av nyckelordet module så här:

module appModule 'modules/app.bicep' = {
  name: 'myApp'
  params: {
    location: location
    appServiceAppName: appServiceAppName
    environmentType: environmentType
  }
}

En moduldefinition innehåller följande komponenter:

  • Nyckelordet module.
  • Ett symboliskt namn, till exempel appModule. Det här namnet används i den här Bicep-filen när du vill referera till modulen. Det symboliska namnet visas aldrig i Azure.
  • Modulsökvägen, till exempel modules/app.bicep. Det här är vanligtvis sökvägen till en Bicep-fil i det lokala filsystemet. I en framtida Microsoft Learn-modul får du lära dig hur du kan dela moduler med hjälp av register och mallspecifikationer som har egna modulsökvägsformat.

    Dricks

    Du kan också använda en JSON Azure Resource Manager-mall (ARM-mall) som en modul. Den här möjligheten kan vara användbar om du har en uppsättning mallar som du ännu inte har migrerat till Bicep.

  • Egenskapen name som anger namnet på distributionen. Du får lära dig mer om distributioner i nästa avsnitt.
  • Egenskapen params , där du kan ange värden för de parametrar som modulen förväntar sig. Du får lära dig mer om modulparametrar i nästa lektion.

Så här fungerar moduler

Att förstå hur moduler fungerar är inte nödvändigt för att använda dem, men det kan hjälpa dig att undersöka problem med dina distributioner eller förklara oväntat beteende.

Distributioner

I Azure är en distribution en särskild resurs som representerar en distributionsåtgärd. Distributioner är Azure-resurser som har resurstypen Microsoft.Resources/deployments. När du skickar en Bicep-distribution skapar eller uppdaterar du en distributionsresurs. På samma sätt skapar portalen en distributionsresurs åt dig när du skapar resurser i Azure Portal.

Alla ändringar i Azure-resurser skapar eller använder dock inte distributioner. När du till exempel använder Azure Portal för att ändra en befintlig resurs skapar den vanligtvis ingen distribution för att göra ändringen. När du använder verktyg från tredje part som Terraform för att distribuera eller konfigurera dina resurser kanske de inte skapar distributioner.

När du distribuerar en Bicep-fil med hjälp av Azure CLI eller Azure PowerShell kan du ange namnet på distributionen. Om du inte anger något namn skapar Azure CLI eller Azure PowerShell automatiskt ett distributionsnamn åt dig från mallens filnamn. Om du till exempel distribuerar en fil med namnet main.bicep är mainstandarddistributionsnamnet .

När du använder moduler skapar Bicep en separat distribution för varje modul. Den name egenskap som du anger för modulen blir namnet på distributionen. När du distribuerar en Bicep-fil som innehåller en modul skapas flera distributionsresurser: en för den överordnade mallen och en för varje modul.

Anta till exempel att du skapar en Bicep-fil med namnet main.bicep. Den definierar en modul med namnet myApp. När du distribuerar filen main.bicep skapas två distributioner. Den första heter main, och den skapar en annan distribution med namnet myApp som innehåller dina programresurser.

Diagram som visar två Bicep-filer, som var och en har ett separat distributionsnamn.

Du kan visa och visa information om distributionsresurser för att övervaka statusen för dina Bicep-distributioner eller för att visa historik för distributioner. Men när du återanvänder samma namn för en distribution skriver Azure över den senaste distributionen med samma namn. Om du behöver behålla distributionshistoriken kontrollerar du att du använder ett unikt namn för varje distribution. Du kan inkludera datum och tid för distributionen i namnet för att göra den unik.

Genererade JSON ARM-mallar

När du distribuerar en Bicep-fil konverterar Bicep den till en JSON ARM-mall. Den här konverteringen kallas även för transpilering. De moduler som mallen använder är inbäddade i JSON-filen. Oavsett hur många moduler du inkluderar i mallen skapas bara en enda JSON-fil.

I exemplet som beskrivs i föregående avsnitt genererar Bicep en enda JSON-fil trots att det ursprungligen fanns två Bicep-filer.

Diagram som visar två Bicep-filer som överförs till en enda JSON-fil.