Moduly Bicep

Pomocí Bicep můžete nasazení uspořádat do modulů. Modul je soubor Bicep, který nasazuje jiný soubor Bicep. Modul může být také šablona Azure Resource Manageru (šablona ARM) pro JSON. Díky modulům zlepšíte čitelnost souborů Bicep zahrnutí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í:

• Modulový registr je podporován pouze Bicepem. Pokud nepoužíváte Bicep, použijte specifikace šablon.
• Obsah v registru modulu Bicep můžete nasadit pouze z jiného souboru Bicep. Specifikace šablon můžete 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ů jiných než Bicep a jiných souborů šablon než ARM, jako jsou 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 jsou převedeny do jedné šablony ARM 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ů.

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

Jednoduchý příklad z reálného světa vypadá takto:

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

Jako modul můžete také použít šablonu ARM pro JSON:

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, anebo soubor v registru. Místní soubor může být buď soubor Bicep, nebo šablona ARM pro JSON. Další informace najdete v tématu Cesta k modulu.

Vlastnost name je nepovinná. Ve vygenerované šabloně se z něj stane název vnořeného prostředku nasazení. Pokud není zadaný žádný název, vygeneruje se jako název vnořeného prostředku nasazení identifikátor GUID.

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ů, může jedno nasazení zobrazit nesprávný výstup. Pokud máte obavy o souběžná nasazení do stejného oboru, zadejte jedinečný název modulu. Dalším způsobem, jak zajistit jedinečné názvy modulů, je vynechat vlastnost name, čímž se automaticky vygeneruje jedinečný název modulu.

V následujícím příkladu je název nasazení zřetězen 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')
}

Nezadání názvu modulu je také platné. Jako název modulu se vygeneruje identifikátor GUID.

module stgModule 'storageAccount.bicep' = {
  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. Podobá se 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. Pomocí dekorátoru batchSize určete, 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, protože jsou určeny implicitně. Pokud potřebujete nastavit explicitní závislost, přidejte dependsOn ji do definice modulu. Pro více informací o závislostech si přečtěte Závislosti prostředků v Bicep.

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 tomuto souboru. Všechny cesty v Bicep musí být zadány s použitím lomítka jako oddělovače adresářů (/), aby byla kompilace konzistentní mezi platformami. Znak zpětného lomítka (\) v systému Windows není podporován. Cesty můžou obsahovat mezery.

Chcete-li například nasadit soubor, který je o jednu úroveň výš v adresáři od vašeho hlavního souboru, použijte:

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

Soubor v registru

Existují veřejné a privátní registry modulů.

Veřejný registr modulů

Note

Moduly bez verifikace Azure se vyřazují z veřejného registru modulů.

Ověřené moduly Azure jsou předem připravené, předem otestované a předem ověřené moduly, které můžete použít k nasazení prostředků v Azure. Zaměstnanci Microsoftu vytvořili a vlastní tyto moduly. Byly navrženy tak, aby zjednodušily a urychlily proces nasazení pro běžné prostředky a konfigurace Azure. Moduly také odpovídají osvědčeným postupům, jako je Azure Well-Architected Framework.

Projděte si moduly Bicep, kde najdete seznam dostupných modulů. Výběrem zvýrazněných čísel na následujícím snímku obrazovky přejděte 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: Toto 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é můžete oddělit pomocí znaku / .
• tag: Slouží k zadání verze modulu.

Například:

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

Note

Alias pro veřejné moduly je br/public. Můžete 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: Toto je název schématu pro registr Bicep.
• cesta k souboru: Tato cesta se volá repository ve službě Azure Container Registry. Cesta k souboru může obsahovat segmenty oddělené znakem / .
• tag: Slouží k určení verze modulu.

Napří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 spustí bicep restore ke zkopírování externího modulu do lokální 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, nakonfigurujte aliasy v souboru bicepconfig.json. 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'
  }
}

Registr veřejného modulu má předdefinovaný alias:

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

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

Soubor podle specifikace šablony

Po vytvoření specifikace šablony propojte 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>' = {

Pro zjednodušení souboru Bicep vytvořte alias pro skupinu prostředků, která obsahuje specifikace šablon. 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 s názvem 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ů:

Decorator	Argument	Description
batchSize	none	Nastavte instance pro postupné nasazení.
description	řetězec	Zadejte popisy modulu.

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

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 sériově.

@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.

Description

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

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

Pro text popisu můžete použít text ve formátu Markdownu.

Parameters

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, storageSKUa location. 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@2025-06-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@2025-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

Nastavení rozsahu modulu

Když deklarujete modul, nastavte obor modulu, který se liší od oboru souboru Bicep, který ho obsahuje. scope Pomocí vlastnosti nastavte obor modulu. Když není zadána vlastnost scope, modul se nasadí v cílovém oboru rodiče.

Následující soubor Bicep vytvoří skupinu prostředků a konto úložiště v této skupině prostředků. Soubor se nasadí do předplatného, ale modul je přiřazený nové skupině 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@2025-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

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

targetScope = 'subscription'

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

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

scope Nastavte vlastnost 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 rozsahu k získání platného rozsahu.

Tyto funkce jsou:

• resourceGroup
• subscription
• managementGroup
• tenant

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

param managementGroupName string

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

Output

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

output storageEndpoint object = stg.properties.primaryEndpoints

Pokud se vlastnost 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@2025-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

U Bicep verze 0.35.1 a novější je možné dekorátor použít na výstupy modulu, který je označí @secure() jako citlivé a tím zajistí, že se jejich hodnoty nezpřístupní v protokolech nebo v historii nasazení. To je užitečné, když modul potřebuje vrátit citlivá data, jako je vygenerovaný klíč nebo připojovací řetězec, do nadřazeného souboru Bicep bez rizika vystavení. Další informace najdete v tématu Zabezpečené výstupy.

Identita modulu

Od verze 0.36.1 bicep můžete k modulu přiřadit spravovanou identitu přiřazenou uživatelem. Díky tomu je identita dostupná v modulu, například pro přístup ke službě Key Vault. Tato funkce je ale určená pro budoucí použití a back-endové služby ji zatím nepodporují.

param identityId string

module mod './module.bicep' = {
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identityId}': {}
    }
  }
  name: 'mod'
  params: {
    keyVaultUri: 'keyVaultUri'
    identityId: identityId
  }
}

Související obsah

• Pokud chcete modulu předat citlivou hodnotu, použijte getSecret funkci.