Moduly bicep

Článek
11/20/2021
6 min ke čtení

Bicep umožňuje organizovat nasazení do modulů. Modul je pouze soubor bicep, který je nasazen z jiného souboru bicep. Pomocí modulů můžete zlepšit čitelnost svých souborů bicep zapouzdřením složitých podrobností o vašem nasazení. Můžete také snadno znovu použít moduly pro různá nasazení.

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

Tip

Volba mezi specifikacemi šablony a soukromými Registry je většinou podstatou předvolby. Pokud nasazujete šablony nebo soubory bicep bez dalších artefaktů projektu, jsou specifikace šablon jednodušší. Pokud nasazujete artefakty projektu se šablonami nebo soubory bicep, můžete integrovat privátní registr se svou vývojovou prací a pak ji snáze nasadit z registru.

Moduly bicep jsou převedeny na jednu šablonu Azure Resource Manager s vnořenými šablonami.

Microsoft Learn

Další informace o modulech a o praktických pokynech najdete v tématu Vytvoření bicep souborů s možností sestavení pomocí modulů v Microsoft Learn.

Syntaxe definice

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

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

Jednoduché příklad reálného světa by vypadal například takto:

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

Pomocí symbolického názvu se na modul odkazuje v jiné části souboru bicep. Například můžete použít symbolický název a získat výstup z modulu. Symbolický název může obsahovat a-z, A-Z, 0-9 a podtržítko ( _ ). Název nesmí začínat číslicí. 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. Další informace najdete v tématu cesta k modulu.

Vlastnost Name je povinná. Bude se jednat o název vnořeného prostředku nasazení ve vygenerované šabloně.

Pokud potřebujete zadat obor , který se liší od rozsahu pro hlavní soubor, přidejte vlastnost Scope. 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>
  }
}

K podmíněnému nasazení modulu přidejte if výraz. Použití je podobné 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>
  }
}

Chcete-li nasadit více než jednu instanci modulu, přidejte for výraz. Pomocí batchSize dekoratér můžete určit, jestli se instance nasazují podle sériového nebo paralelního. Další informace najdete 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 jsou moduly nasazeny paralelně, pokud nejsou závislé na jiných modulech nebo prostředcích. Obvykle nemusíte nastavovat závislosti, protože jsou implicitně určeny. Pokud potřebujete nastavit explicitní závislost, můžete 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 pro modul 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. Všechny tyto možnosti jsou uvedeny níže.

Místní soubor

Pokud je modul místním souborem, zadejte relativní cestu k tomuto souboru. Všechny cesty v bicep musí být zadané pomocí oddělovače adresáře dopředného lomítka (/), aby se zajistila konzistentní kompilace napříč platformami. znak zpětného lomítka ( \ ) Windows není podporován. Cesty můžou obsahovat mezery.

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

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

Soubor v registru

Pokud jste modul publikovali do registru, můžete ho propojit s tímto modulem. Zadejte název služby Azure Container registry a cestu k modulu. Zadejte cestu modulu s následující syntaxí:

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

br je název schématu pro bicep registru.
cesta k souboru je volána repository v Azure Container Registry. Cesta k souboru může obsahovat segmenty, které jsou odděleny / znakem.
k určení verze modulu se používá značka .

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 Visual Studio Code automaticky volá obnovení Bicep , které zkopíruje externí modul do místní mezipaměti. Obnovení externího modulu může chvíli trvat. Pokud IntelliSense pro modul nefunguje hned, počkejte, až se obnovení dokončí.

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

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

Soubor ve specifikaci šablony

Po vytvoření specifikace šablonyse můžete připojit k této specifikaci šablony v modulu. Zadejte specifikace š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 vaše specifikace šablony. Při použití aliasu se zobrazí syntaxe:

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

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

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

Parametry

Parametry, které zadáte do definice modulu, odpovídají parametrům v souboru bicep.

Následující příklad bicep má tři parametry – storagePrefix, storageSKU a Location. Parametr storageSKU má výchozí hodnotu, takže nemusíte zadat hodnotu pro tento parametr během nasazování.

@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

Chcete-li použít předchozí příklad jako modul, zadejte hodnoty pro tyto parametry.

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

Nastavit obor modulu

Při deklaraci modulu můžete nastavit obor pro modul, který se liší od rozsahu obsahujícího soubor bicep. Pomocí scope Vlastnosti nastavte obor pro modul. Pokud není zadána vlastnost oboru, modul je nasazen do cílového 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@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

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

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

Tyto funkce jsou:

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

Z modulu můžete získat hodnoty a použít je v hlavním souboru bicep. Chcete-li získat výstupní hodnotu z modulu, použijte outputs vlastnost objektu Module.

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

output storageEndpoint object = stg.properties.primaryEndpoints

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

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

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.