Bicep-Module

Mit Bicep können Sie Bereitstellungen in Modulen organisieren. Bei einem Modul handelt es sich um eine Bicep-Datei, die von einer anderen Bicep-Datei bereitgestellt wird. Ein Modul kann auch eine Azure Resource Manager-Vorlage (ARM-Vorlage) für JSON sein. Mit Modulen verbessern Sie die Lesbarkeit Ihrer Bicep-Dateien, indem Sie komplexe Details Ihrer Bereitstellung kapseln. Sie können Module auch problemlos für verschiedene Bereitstellungen wiederverwenden.

Um Module für andere Personen in Ihrer Organisation freizugeben, erstellen Sie eine Vorlagenspezifikation oder private Registrierung. Vorlagenspezifikationen und Module in der Registrierung sind nur für Benutzer mit den richtigen Berechtigungen verfügbar.

Bicep-Module werden mit geschachtelten Vorlagen in eine einzelne ARM-Vorlage konvertiert. Weitere Informationen dazu, wie Bicep Konfigurationsdateien aufgelöst und wie Bicep eine benutzerdefinierte Konfigurationsdatei mit der Standardkonfigurationsdatei zusammenführt, finden Sie unter Konfigurationsdateiauflösungsprozess und Konfigurationsdateizusammenführungsprozess.

Schulungsangebote

Wenn Sie schrittweise Anleitungen zu Modulen erhalten möchten, lesen Sie " Erstellen von komponierbaren Bicep-Dateien mithilfe von Modulen".

Definieren von Modulen

Die grundlegende Syntax zum Definieren eines Moduls ist:

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

Ein einfaches, reales Beispiel sieht wie folgt aus:

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

Sie können auch eine ARM-Vorlage für JSON als Modul verwenden:

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

Verwenden Sie den symbolischen Namen, um in einem anderen Teil der Bicep-Datei auf das Modul zu verweisen. Beispielsweise können Sie den symbolischen Namen verwenden, um die Ausgabe eines Moduls zu erhalten. Der symbolische Name kann die Zeichen a–z, A–Z und 0–9 sowie Unterstriche (_) enthalten. Der Name darf nicht mit einer Zahl beginnen. Ein Modul darf nicht denselben Namen wie ein Parameter, eine Variable oder eine Ressource haben.

Der Pfad kann entweder eine lokale Datei oder eine Datei in einer Registrierung sein. Die lokale Datei kann entweder eine Bicep-Datei oder eine ARM-Vorlage für JSON sein. Weitere Informationen finden Sie unter Pfad zu einem Modul.

Die name-Eigenschaft ist optional. Sie wird zum Namen der geschachtelten Bereitstellungsressource in der generierten Vorlage. Wenn kein Name angegeben wird, wird ein eindeutiger Bezeichner (GUID) als Name für die Ressource der geschachtelten Bereitstellung generiert.

Wenn ein Modul mit einem statischen Namen gleichzeitig im selben Bereich bereitgestellt wird, besteht die Möglichkeit, dass eine Bereitstellung die Ausgabe aus der anderen Bereitstellung beeinträchtigt. Wenn beispielsweise zwei Bicep-Dateien dasselbe Modul mit demselben statischen Namen (examplemodule) verwenden und auf dieselbe Ressourcengruppe ausgerichtet sind, kann eine Bereitstellung die falsche Ausgabe anzeigen. Wenn Sie sich wegen gleichzeitiger Bereitstellungen im selben Bereich Sorgen machen, geben Sie Ihrem Modul einen eindeutigen Namen. Eine weitere Möglichkeit, um sicherzustellen, dass Modulnamen eindeutig sind, besteht darin, die name-Eigenschaft auszulassen; ein eindeutiger Modulname wird dann automatisch generiert.

Im folgenden Beispiel wird der Bereitstellungsname mit dem Modulnamen verkettet. Wenn Sie einen eindeutigen Namen für die Bereitstellung angeben, ist der Modulname ebenfalls eindeutig.

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

Es ist auch gültig, keinen Modulnamen anzugeben. Eine GUID wird als Modulname generiert.

module stgModule 'storageAccount.bicep' = {
  scope: resourceGroup('demoRG')
}

Wenn Sie einen Bereich angeben müssen, der sich von dem Bereich für die Hauptdatei unterscheidet, fügen Sie die Bereichseigenschaft hinzu. Weitere Informationen finden Sie unter Modulbereich festlegen.

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

Um ein Modul bedingt bereitzustellen, fügen Sie einen if-Ausdruck hinzu. Dies ähnelt der bedingten Bereitstellung einer Ressource.

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

Um mehrere Instanzen eines Moduls bereitzustellen, fügen Sie den for-Ausdruck hinzu. Verwenden Sie den batchSize Dekorateur, um anzugeben, ob die Instanzen serial oder parallel bereitgestellt werden. Für weitere Informationen siehe Iterative Schleifen in 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>
  }
}]

Module werden wie Ressourcen parallel bereitgestellt, es sei denn, sie hängen von anderen Modulen oder Ressourcen ab. In der Regel müssen Keine Abhängigkeiten festgelegt werden, da sie implizit bestimmt werden. Wenn Sie eine explizite Abhängigkeit festlegen müssen, fügen Sie der Moduldefinition hinzu dependsOn . Weitere Informationen zu Abhängigkeiten finden Sie unter "Ressourcenabhängigkeiten" in Bicep.

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

Pfad zu einem Modul

Bei der Datei für das Modul kann es sich entweder um eine lokale oder um eine externe Datei geben. Die externe Datei kann sich in einer Vorlagenspezifikation oder in einer Bicep-Modulregistrierung befinden.

Lokale Datei

Wenn das Modul eine lokale Datei ist, geben Sie einen relativen Pfad zu dieser Datei an. Alle Pfade in Bicep müssen durch das Schrägstrichtrennzeichen (/) angegeben werden, um plattformübergreifende Konsistenz bei Kompilierungen sicherzustellen. Der umgekehrte Schrägstrich von Windows (\) wird nicht unterstützt. Pfade können Leerzeichen enthalten.

Wenn Sie beispielsweise eine Datei deployen möchten, die sich eine Ebene höher im Verzeichnis über Ihrer Hauptdatei befindet, verwenden Sie Folgendes:

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

Datei in der Registrierung

Es gibt öffentliche und private Modulregister.

Öffentliche Modulregistrierung

Azure Verified Modules sind vorgefertigte, vorab getestete und vordefinierte Module, mit denen Sie Ressourcen in Azure bereitstellen können. Microsoft-Mitarbeiter haben diese Module erstellt und besitzen. Sie wurden entwickelt, um den Bereitstellungsprozess für allgemeine Azure-Ressourcen und -Konfigurationen zu vereinfachen und zu beschleunigen. Die Module sind zudem an bewährte Verfahren, wie das Azure Well-Architected Framework, ausgerichtet.

Durchsuchen Sie Bicep-Module, um die Liste der verfügbaren Module zu sehen. Wählen Sie die hervorgehobenen Zahlen im folgenden Screenshot aus, um direkt zu dieser gefilterten Ansicht zu wechseln:

Die Modulliste zeigt die neueste Version. Wählen Sie die Versionsnummer aus, um eine Liste der verfügbaren Versionen anzuzeigen.

Geben Sie zum Verknüpfen mit einem öffentlichen Modul den Modulpfad mit der folgenden Syntax an:

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

• br/public: Dies ist der Alias für öffentliche Module. Sie können diesen Alias in der Bicep-Konfigurationsdatei anpassen.
• Dateipfad: Dies kann Segmente enthalten, die Sie mit dem / Zeichen trennen können.
• tag: Dies wird zum Angeben einer Version für das Modul verwendet.

Zum Beispiel:

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

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

Private Modulregistrierung

Wenn Sie ein Modul in einer Registrierung veröffentlicht haben, können Sie eine Verknüpfung mit diesem Modul herstellen. Geben Sie den Namen für die Azure Container Registry und einen Pfad zum Modul an. Geben Sie den Modulpfad mit der folgenden Syntax an:

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

• br: Das ist der Schemaname für eine Bicep-Registrierung.
• Dateipfad: Dies wird in der Azure-Containerregistrierung repository genannt. Der Dateipfad kann Segmente enthalten, die durch das / Zeichen getrennt sind.
• tag: Wird verwendet, um eine Version für das Modul anzugeben.

Zum Beispiel:

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

Wenn Sie auf ein Modul in einer Registrierung verweisen, ruft die Bicep-Erweiterung in Visual Studio Code automatisch auf bicep restore , um das externe Modul in den lokalen Cache zu kopieren. Die Wiederherstellung des externen Moduls dauert einen Moment. Wenn IntelliSense für das Modul nicht sofort funktioniert, warten Sie, bis die Wiederherstellung abgeschlossen ist.

Der vollständige Pfad für ein Modul in einer Registrierung kann lang sein. Anstatt den vollständigen Pfad jedes Mal bereitzustellen, wenn Sie das Modul verwenden möchten, konfigurieren Sie Aliase in der bicepconfig.json Datei. Die Aliase erleichtern das Verweisen auf das Modul. Mit einem Alias können Sie z. B. den Pfad wie folgt kürzen:

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

Die Registrierung des öffentlichen Moduls weist einen vordefinierten Alias auf:

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

Sie können den öffentlichen Alias in der Datei bicepconfig.json außer Kraft setzen.

Datei in Vorlagenspezifikation

Nachdem Sie eine Vorlagenspezifikation erstellt haben, verknüpfen Sie diese Vorlagenspezifikation in einem Modul. Geben Sie die Vorlagenspezifikation im folgenden Format an:

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

Um Ihre Bicep-Datei zu vereinfachen, erstellen Sie einen Alias für die Ressourcengruppe, die Ihre Vorlagenspezifikationen enthält. Wenn Sie einen Alias verwenden, wird die Syntax wie folgt verwendet:

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

Das folgende Modul stellt eine Vorlagenspezifikation zum Erstellen eines Speicherkontos zur Verfügung. Die Abonnement- und Ressourcengruppe für die Vorlagenspezifikation wird im Alias mit dem Namen ContosoSpecsdefiniert.

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

Verwende Dekoratoren

Decorator-Elemente werden im Format @expression geschrieben und oberhalb von Moduldeklarationen platziert. Die folgende Tabelle zeigt die verfügbaren Dekoratoren für Module:

Decorators befinden sich im sys-Namespace. Wenn Sie einen Dekorator von einem anderen Element mit dem gleichen Namen unterscheiden müssen, stellen Sie dem Dekorator sys voran. Wenn Ihre Bicep-Datei beispielsweise einen Parameter mit dem Namen descriptionenthält, müssen Sie den sys Namespace hinzufügen, wenn Sie den description Dekorierer verwenden.

Batchgröße

Sie können @batchSize() nur auf eine Ressourcen- oder Moduldefinition anwenden, die einen for Ausdruck verwendet.

Standardmäßig werden Module parallel bereitgestellt. Wenn Sie den @batchSize(int)-Dekorator hinzufügen, stellen Sie Instanzen seriell bereit.

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

Weitere Informationen finden Sie unter Bereitstellung in Batches.

Beschreibung

Um eine Erklärung hinzuzufügen, fügen Sie Moduldeklarationen eine Beschreibung hinzu. Zum Beispiel:

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

Mit Markdown formatierter Text kann für den Beschreibungstext verwendet werden.

Parameter

Die Parameter, die Sie in Ihrer Moduldefinition angeben, entsprechen den Parametern in der Bicep-Datei.

Das folgende Bicep-Beispiel weist drei Parameter auf: storagePrefix, , storageSKUund ___location. Der storageSKU Parameter weist einen Standardwert auf, sodass Sie während der Bereitstellung keinen Wert für diesen Parameter angeben müssen.

@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

Um das vorherige Beispiel als Modul zu verwenden, geben Sie Werte für diese Parameter an.

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

Festlegen des Modulbereichs

Wenn Sie ein Modul deklarieren, legen Sie einen Bereich für das Modul fest, das sich von dem Bereich für die Bicep-Datei unterscheidet, die es enthält. Legen Sie den Bereich für das Modul mithilfe der Eigenschaft scope fest. Wenn die scope-Eigenschaft nicht angegeben wird, wird das Modul im Zielbereich des übergeordneten Moduls bereitgestellt.

Die folgende Bicep-Datei erstellt eine Ressourcengruppe und ein Speicherkonto in dieser Ressourcengruppe. Die Datei wird in einem Abonnement bereitgestellt, aber der Bereich des Moduls ist die neue Ressourcengruppe.

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

Im nächsten Beispiel werden Speicherkonten in zwei verschiedenen Ressourcengruppen bereitgestellt. Beide Ressourcengruppen müssen bereits vorhanden sein.

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

Legen Sie die scope Eigenschaft auf ein gültiges Bereichsobjekt fest. Wenn Ihre Bicep-Datei eine Ressourcengruppe, ein Abonnement oder eine Verwaltungsgruppe bereitgestellt, können Sie den Bereich für ein Modul auf den symbolischen Namen für diese Ressource festlegen. Sie können auch die Bereichsfunktionen verwenden, um einen gültigen Bereich zu erhalten.

Dabei handelt es sich um die folgenden Funktionen:

• Ressourcengruppe
• Abonnement
• managementGroup
• Mieter

Im folgenden Beispiel wird der Bereich mithilfe der Funktion managementGroup festgelegt:

param managementGroupName string

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

Ausgabe

Sie können Werte aus einem Modul abrufen und in der Bicep-Hauptdatei verwenden. Um einen Ausgabewert von einem Modul zu erhalten, verwenden Sie die outputs-Eigenschaft für das Modulobjekt.

Im ersten Beispiel wird ein Speicherkonto erstellt und die primären Endpunkte zurückgegeben:

@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

Wenn die Eigenschaft als Modul verwendet wird, können Sie diesen Ausgabewert abrufen:

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

Mit Bicep Version 0.35.1 und höher, kann der @secure()-Decorator auf Modulausgaben angewendet werden, um sie als vertraulich zu kennzeichnen und so sicherzustellen, dass ihre Werte nicht in Protokollen oder im Bereitstellungsverlauf verfügbar gemacht werden. Dies ist nützlich, wenn ein Modul vertrauliche Daten, z. B. einen generierten Schlüssel oder eine Verbindungszeichenfolge, an die übergeordnete Bicep-Datei zurückgeben muss, ohne das Risiko einer Offenlegung einzugehen. Weitere Informationen finden Sie unter Sichere Ausgaben.

Verwandte Inhalte

• Ein Lernprogramm finden Sie unter Erstellen Ihrer ersten Bicep-Datei.
• Verwenden Sie die getSecret Funktion, um einen vertraulichen Wert an ein Modul zu übergeben.