Moduly Bicep

Bicep umožňuje uspořádat nasazení do modulů. Modul je soubor Bicep (nebo šablona JSON Azure Resource Manageru), který je nasazený z jiného souboru Bicep. Díky modulům zlepšíte čitelnost souborů Bicep zapouzdřením složitých podrobností o nasazení. Moduly můžete také snadno opakovaně používat pro různá nasazení.

Pokud chcete sdílet moduly s dalšími lidmi ve vaší organizaci, vytvořte specifikaci šablony nebo privátní registr. Specifikace šablon a moduly v registru jsou k dispozici pouze uživatelům se správnými oprávněními.

Tip

Volba mezi registrem modulů a specifikacemi šablon je většinou otázkou preference. Při výběru mezi těmito dvěma možnostmi je potřeba vzít v úvahu několik věcí:

• Registr modulů podporuje pouze Bicep. Pokud ještě nepoužíváte Bicep, použijte specifikace šablon.
• Obsah v registru modulu Bicep lze nasadit pouze z jiného souboru Bicep. Specifikace šablon je možné nasadit přímo z rozhraní API, Azure PowerShellu, Azure CLI a webu Azure Portal. Můžete dokonce použít UiFormDefinition k přizpůsobení prostředí nasazení portálu.
• Bicep má několik omezených možností pro vkládání jiných artefaktů projektu (včetně souborů mimo Bicep a souborů bez šablony ARM). Například skripty PowerShellu, skripty rozhraní příkazového řádku a další binární soubory) pomocí funkcí loadTextContent a loadFileAsBase64 funkcí. Specifikace šablon nemohou tyto artefakty zabalit.

Moduly Bicep se převedou na jednu šablonu Azure Resource Manageru s vnořenými šablonami. Další informace o tom, jak Bicep řeší konfigurační soubory a jak Bicep slučuje uživatelsky definovaný konfigurační soubor s výchozím konfiguračním souborem, najdete v tématu Proces překladu konfiguračních souborů a proces sloučení konfiguračních souborů.

Školicí materiály

Pokud byste se raději seznámili s moduly podrobnými pokyny, přečtěte si téma Vytváření kompozovatelných souborů Bicep pomocí modulů.

Definování modulů

Základní syntaxe pro definování modulu je:

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

Příklad jednoduchého reálného světa by tedy vypadal takto:

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

Šablonu JSON ARM můžete použít také jako modul:

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

K odkazování na modul v jiné části souboru Bicep použijte symbolický název. K získání výstupu z modulu můžete například použít symbolický název. Symbolický název může obsahovat a-z, A-Z, 0-9 a podtržítko (_). Název nemůže začínat číslem. Modul nemůže mít stejný název jako parametr, proměnná nebo prostředek.

Cesta může být buď místní soubor, nebo soubor v registru. Místní soubor může být buď soubor Bicep, nebo šablona JSON ARM. Další informace najdete v tématu Cesta k modulu.

Vlastnost name je povinná. Ve vygenerované šabloně se z něj stane název vnořeného prostředku nasazení.

Pokud se modul se statickým názvem nasadí souběžně do stejného oboru, existuje potenciál pro jedno nasazení, aby ovlivnilo výstup z druhého nasazení. Pokud například dva soubory Bicep používají stejný modul se stejným statickým názvem (examplemodule) a cílí na stejnou skupinu prostředků, jedno nasazení může zobrazit nesprávný výstup. Pokud máte obavy o souběžná nasazení do stejného oboru, zadejte jedinečný název modulu.

Následující příklad zřetězí název nasazení s názvem modulu. Pokud zadáte jedinečný název nasazení, název modulu je také jedinečný.

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

Pokud potřebujete zadat obor , který se liší od oboru hlavního souboru, přidejte vlastnost oboru. Další informace najdete v tématu Nastavení oboru modulu.

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

Pokud chcete podmíněně nasadit modul, přidejte if výraz. Použití se podobá podmíněnému nasazení prostředku.

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

Pokud chcete nasadit více než jednu instanci modulu, přidejte for výraz. Dekorátor můžete použít batchSize k určení, zda jsou instance nasazeny sériově nebo paralelně. Další informace naleznete v tématu Iterativní smyčky v 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>
  }
}]

Podobně jako prostředky se moduly nasazují paralelně, pokud nezávisí na jiných modulech nebo prostředcích. Obvykle nemusíte nastavovat závislosti podle jejich implicitního určení. Pokud potřebujete nastavit explicitní závislost, můžete ji přidat dependsOn do definice modulu. Další informace o závislostech najdete v tématu Závislosti prostředků.

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

Cesta k modulu

Soubor modulu může být buď místní soubor, nebo externí soubor. Externí soubor může být ve specifikaci šablony nebo v registru modulu Bicep.

Místní soubor

Pokud je modul místním souborem, zadejte relativní cestu k housku. Všechny cesty v Bicep musí být zadány pomocí oddělovače adresářů lomítko (/), aby se zajistila konzistentní kompilace napříč platformami. Zpětné lomítko systému Windows (\) není podporováno. Cesty můžou obsahovat mezery.

Pokud chcete například nasadit soubor o jednu úroveň v adresáři z hlavního souboru, použijte:

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

Soubor v registru

Veřejný registr modulů

Poznámka:

Moduly bez AVM (ověřené moduly Azure) se vyřadí z veřejného registru modulů.

Ověřené moduly Azure jsou předem připravené, předem otestované a předem ověřené moduly pro nasazování prostředků v Azure. Tyto moduly jsou vytvořené a vlastněné zaměstnanci Microsoftu, které zjednodušují a urychlují proces nasazení pro běžné prostředky a konfigurace Azure a zároveň odpovídají osvědčeným postupům; jako dobře navržená architektura.

Přejděte k indexu Bicep ověřených modulů Azure a zobrazte seznam dostupných modulů. Vyberte zvýrazněná čísla na následujícím snímku obrazovky, který se má provést přímo do tohoto filtrovaného zobrazení.

V seznamu modulů se zobrazuje nejnovější verze. Výběrem čísla verze zobrazíte seznam dostupných verzí:

Pokud chcete vytvořit odkaz na veřejný modul, zadejte cestu k modulu s následující syntaxí:

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

• br/public je alias pro veřejné moduly. Tento alias můžete přizpůsobit v konfiguračním souboru Bicep.
• Cesta k souboru může obsahovat segmenty, které mohou být odděleny znakem / .
• značka se používá k zadání verze modulu.

Příklad:

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

Poznámka:

br/public je alias pro veřejné moduly. Lze ho také napsat takto:

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

Registr privátních modulů

Pokud jste publikovali modul do registru, můžete ho propojit. Zadejte název registru kontejneru Azure a cestu k modulu. Zadejte cestu k modulu s následující syntaxí:

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

• br je název schématu pro registr Bicep.
• Cesta k souboru se volá repository ve službě Azure Container Registry. Cesta k souboru může obsahovat segmenty oddělené znakem / .
• značka se používá k zadání verze modulu.

Příklad:

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

Když odkazujete na modul v registru, rozšíření Bicep v editoru Visual Studio Code automaticky volá obnovení bicep ke zkopírování externího modulu do místní mezipaměti. Obnovení externího modulu chvíli trvá. Pokud intellisense pro modul nefunguje okamžitě, počkejte na dokončení obnovení.

Úplná cesta modulu v registru může být dlouhá. Místo zadání úplné cesty pokaždé, když chcete modul použít, můžete v souboru bicepconfig.json nakonfigurovat aliasy. Aliasy usnadňují odkazování na modul. Například pomocí aliasu můžete zkrátit cestu k:

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

Předdefinoval se alias veřejného registru modulu:

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

Veřejný alias v souboru bicepconfig.json můžete přepsat.

Soubor ve specifikaci šablony

Po vytvoření specifikace šablony můžete odkazovat na tuto specifikaci šablony v modulu. Zadejte specifikaci šablony v následujícím formátu:

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

Soubor Bicep ale můžete zjednodušit vytvořením aliasu pro skupinu prostředků, která obsahuje specifikace šablony. Když použijete alias, syntaxe se stane:

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

Následující modul nasadí specifikaci šablony pro vytvoření účtu úložiště. Předplatné a skupina prostředků pro specifikaci šablony jsou definovány v aliasu ContosoSpecs.

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

Použití dekorátorů

Dekorátory jsou napsány ve formátu @expression a jsou umístěny nad deklaracemi modulu. V následující tabulce jsou uvedeny dostupné dekorátory modulů.

Dekoratér	Argument	Popis
batchSize	Žádná	Nastavte instance pro postupné nasazení.
popis	string	Zadejte popisy modulu.

Dekorátory jsou v oboru názvů sys. Pokud potřebujete odlišit dekorátor od jiné položky se stejným názvem, předkožte dekorátorem .sys Pokud například váš soubor Bicep obsahuje parametr s názvem description, musíte přidat obor názvů sys při použití dekorátoru popisu .

BatchSize

Můžete použít @batchSize() pouze pro definici prostředku nebo modulu, která používá for výraz.

Moduly se ve výchozím nastavení nasazují paralelně. Když přidáte @batchSize(int) dekorátor, nasadíte instance serialně.

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

Další informace najdete v tématu Nasazení v dávkách.

Popis

Pokud chcete přidat vysvětlení, přidejte popis k deklaracím modulů. Příklad:

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

Text ve formátu Markdown lze použít pro text popisu.

Parametry

Parametry, které zadáte v definici modulu, odpovídají parametrům v souboru Bicep.

Následující příklad Bicep má tři parametry – storagePrefix, storageSKU a umístění. Parametr storageSKU má výchozí hodnotu, takže během nasazování nemusíte zadávat hodnotu tohoto parametru.

@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

Pokud chcete jako modul použít předchozí příklad, zadejte hodnoty pro tyto parametry.

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

Nastavení rozsahu modulu

Při deklarování modulu můžete nastavit obor modulu, který se liší od rozsahu souboru obsahujícího Bicep. scope Pomocí vlastnosti nastavte obor modulu. Pokud není zadána vlastnost oboru, modul se nasadí v cílovém oboru nadřazeného objektu.

Následující soubor Bicep vytvoří skupinu prostředků a účet úložiště v této skupině prostředků. Soubor se nasadí do předplatného, ale modul je vymezený na novou skupinu prostředků.

// 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

Další příklad nasadí účty úložiště do dvou různých skupin prostředků. Obě tyto skupiny prostředků už musí existovat.

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

Nastavte vlastnost oboru na platný objekt oboru. Pokud soubor Bicep nasadí skupinu prostředků, předplatné nebo skupinu pro správu, můžete nastavit obor modulu na symbolický název daného prostředku. Nebo můžete použít funkce oboru k získání platného oboru.

Tyto funkce jsou:

• resourceGroup
• předplatné
• managementGroup
• klient

Následující příklad používá managementGroup funkci k nastavení oboru.

param managementGroupName string

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

Výstup

Hodnoty můžete získat z modulu a použít je v hlavním souboru Bicep. Pokud chcete získat výstupní hodnotu z modulu, použijte outputs vlastnost objektu modulu.

První příklad vytvoří účet úložiště a vrátí primární koncové body.

@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

Pokud se používá jako modul, můžete tuto výstupní hodnotu získat.

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

Další kroky

• Kurz najdete v tématu Nasazení prostředků Azure pomocí šablon Bicep.
• Pokud chcete modulu předat citlivou hodnotu, použijte funkci getSecret .