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. Durch die Verwendung von 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.

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 eine GUID als Name der geschachtelten Bereitstellungsressource generiert.

Wenn Sie ein Modul mit einem statischen Namen gleichzeitig für denselben Bereich bereitstellen, kann eine Bereitstellung die Ausgabe der anderen Bereitstellung beeinträchtigen. 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, eindeutige Modulnamen sicherzustellen, besteht darin, die Eigenschaft name wegzulassen; ein eindeutiger Modulname wird dann automatisch generiert. Die no-module-name linter-Regel wurde entwickelt, um diese sauberere Codierungspraxis zu erzwingen, indem jedes Modul gekennzeichnet wird, das weiterhin eine explizite name Eigenschaft enthält.

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

Sie können entweder eine lokale Datei oder eine externe Datei für das Modul verwenden. Sie finden die externe Datei in einer Vorlagenspezifikation oder einer Bicep Modulregistrierung.

Lokale Datei

Wenn das Modul eine lokale Datei ist, geben Sie einen relativen Pfad zu dieser Datei an. In Bicep müssen Sie das Schrägstrichtrennzeichen (/) für alle Pfade verwenden, um eine konsistente Kompilierung auf allen Plattformen sicherzustellen. Der umgekehrte Schrägstrich von Windows (\) wird nicht unterstützt. Pfade können Leerzeichen enthalten.

Verwenden Sie das folgende Beispiel, um eine Datei bereitzustellen, die sich eine Verzeichnisebene über Ihrer Hauptdatei befindet:

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 vereinfachen und beschleunigen den Bereitstellungsprozess für allgemeine Azure Ressourcen und Konfigurationen. 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 anzuzeigen. 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.
• tag: Gibt eine Version für das Modul an.

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: Gibt eine Version für das Modul an.

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 werden im Alias mit dem Namen ContosoSpecsdefiniert.

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

Dekoratoren verwenden

Schreiben Sie Dekoratoren im Format @expression und platzieren Sie sie oberhalb von Moduldeklarationen. Die folgende Tabelle zeigt die verfügbaren Dekoratoren für Module:

Decorators befinden sich im sys-Namespace. Wenn Sie einen Decorator von einem anderen Element mit demselben Namen unterscheiden müssen, stellen Sie dem Decorator 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.

BatchSize

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

Standardmäßig stellt das Bereitstellungsmodul Module parallel bereit. 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.

Description

Um eine Erklärung hinzuzufügen, fügen Sie Moduldeklarationen eine Beschreibung hinzu. 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.

Parameters

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@2025-06-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@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

Festlegen des Modulbereichs

Wenn Sie ein Modul deklarieren, legen Sie einen Bereich für das Modul fest, das sich vom 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 Sie die Eigenschaft scope nicht angeben, wird das Modul im Zielbereich des übergeordneten Elements 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@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

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

Legen Sie die scope Eigenschaft auf ein gültiges Bereichsobjekt fest. Wenn Ihre Bicep-Datei eine Ressourcengruppe, ein Abonnement oder eine Verwaltungsgruppe bereitstellt, legen Sie den Bereich für ein Modul auf den symbolischen Namen für diese Ressource fest. Oder verwenden Sie die Bereichsfunktionen, um einen gültigen Gültigkeitsbereich zu ermitteln.

Dabei handelt es sich um die folgenden Funktionen:

• resourceGroup
• subscription
• managementGroup
• tenant

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

param managementGroupName string

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

Output

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

output storageEndpoint object = stg.properties.primaryEndpoints

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

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

Mit Bicep-Version 0.35.1 oder höher können Sie den @secure()-Decorator auf Modulausgaben anwenden, um sie als sensibel zu kennzeichnen, sodass ihre Werte nicht in Logs oder im Bereitstellungsverlauf offengelegt werden. Dieser Ansatz 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 eine Offenlegung zu riskieren. Weitere Informationen finden Sie unter Sichere Ausgaben.

Modulidentität

Ab Bicep Version 0.36.1 können Sie einem Modul eine vom Benutzer zugewiesene verwaltete Identität zuweisen. Diese Identität ist innerhalb des Moduls verfügbar , z. B. für den Zugriff auf eine Key Vault. Back-End-Dienste unterstützen diese Funktion jedoch noch nicht.

param identityId string

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

Verwandte Inhalte

• Verwenden Sie die getSecret Funktion, um einen vertraulichen Wert an ein Modul zu übergeben.