Bicep-Module

Artikel
10/16/2024

Mit Bicep können Sie Bereitstellungen in Modulen organisieren. Bei einem Modul handelt es sich um eine Bicep-Datei (oder eine ARM-JSON-Vorlage, Azure Resource Manager), die von einer anderen Bicep-Datei bereitgestellt wird. 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.

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

Tipp

Die Wahl zwischen Modulregistrierung und Vorlagenspezifikationen ist meist eine Frage der Präferenz. Es gibt einige Aspekte, die Sie beachten sollten, wenn Sie sich für eine Variante entscheiden:

Die Modulregistrierung wird nur von Bicep unterstützt. Wenn Sie Bicep noch nicht nutzen, verwenden Sie Vorlagenspezifikationen.
Inhalte in der Bicep-Modulregistrierung können nur aus einer anderen Bicep-Datei bereitgestellt werden. Vorlagenspezifikationen können direkt über die API, Azure PowerShell, Azure CLI und das Azure-Portal bereitgestellt werden. Sie können sogar UiFormDefinition verwenden, um die Bereitstellung über das Portal anzupassen.
Bicep verfügt über einige eingeschränkte Funktionen zum Einbetten anderer Projektartefakte (einschließlich Nicht-Bicep- und Nicht-ARM-Vorlagendateien, beispielsweise PowerShell-Skripts, CLI-Skripts und andere Binärdateien) mithilfe der Funktionen loadTextContent und loadFileAsBase64. Diese Artefakte können nicht in Vorlagenspezifikationen gepackt werden.

Bicep-Module werden in eine einzelne ARM-Vorlage (Azure Resource Manager) mit geschachtelten Vorlagen konvertiert. Weitere Informationen dazu, wie Bicep Konfigurationsdateien auflöst und eine benutzerdefinierte Konfigurationsdatei mit der Standardkonfigurationsdatei zusammenführt, finden Sie unter Prozess der Konfigurationsdateiauflösung und Prozess zum Zusammenführen von Konfigurationsdateien.

Schulungsangebote

Wenn Sie mehr über Module durch Schritt-für-Schritt-Anleitungen erfahren möchten, lesen Sie Composable Bicep-Dateien mithilfe von Modulen erstellen.

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 würde also folgendermaßen aussehen:

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

Sie können eine ARM-JSON-Vorlage auch als ein 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-JSON-Vorlage sein. Weitere Informationen finden Sie unter Pfad zum Modul.

Die Eigenschaft Name ist erforderlich. Sie wird zum Namen der geschachtelten Bereitstellungsressource in der generierten Vorlage.

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) und derselben Zielressourcengruppe verwenden, wird in einer Bereitstellung möglicherweise die falsche Ausgabe angezeigt. Wenn Sie sich wegen gleichzeitiger Bereitstellungen im selben Bereich Sorgen machen, geben Sie Ihrem Modul einen eindeutigen Namen.

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

Wenn Sie einen Bereich angeben müssen, der sich vom Bereich für die Hauptdatei unterscheiden soll, 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. Die Verwendung ä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. Sie können den Decorator batchSize verwenden, um anzugeben, ob die Instanzen nacheinander oder parallel bereitgestellt werden sollen. Weitere Informationen finden Sie unter 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 Sie keine Abhängigkeiten festlegen, da sie implizit bestimmt werden. Wenn Sie eine explizite Abhängigkeit festlegen müssen, können Sie dependsOn der Moduldefinition hinzufügen. Weitere Informationen zu Abhängigkeiten finden Sie unter Ressourcenabhängigkeiten.

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

Pfad zum 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 in einer Vorlagenspezifikation oder einer Bicep-Modulregistrierung enthalten sein.

Lokale Datei

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

Verwenden Sie beispielsweise Folgendes, um eine Datei bereitzustellen, die sich im Verzeichnis eine Ebene über Ihrer Hauptdatei befindet:

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

Datei in der Registrierung

Öffentliche Modulregistrierung

Hinweis

Nicht-AVM-Module (Azure Verified Modules) werden aus der öffentlichen Modulregistrierung zurückgezogen.

Azure Verified Modules sind vorgefertigte, vorab getestete und verifizierte Module für die Bereitstellung von Ressourcen in Azure. Diese Module werden von Microsoft-Mitarbeitern erstellt und verwaltet, um den Bereitstellungsprozess für allgemeine Azure-Ressourcen und -Konfigurationen zu vereinfachen und zu beschleunigen und gleichzeitig bewährten Methoden zu folgen. Ein Beispiel ist das Well-Architected Framework.

Navigieren Sie zum Azure Verified Modules Bicep Index, um die Liste der verfügbaren Module anzuzeigen, und wählen Sie die hervorgehobenen Zahlen im folgenden Screenshot aus, um direkt zu dieser gefilterten Ansicht zu gelangen.

Screenshot: Azure Verified Modules (AVM).

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

Screenshot: Versionen von Azure Verified Modules (AVM).

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 ist der Alias für die öffentlichen Module. Sie können diesen Alias in der Bicep-Konfigurationsdatei anpassen.
Der Dateipfad kann Segmente enthalten, die durch das Zeichen / getrennt werden können.
tag wird verwendet, um eine Version für das Modul anzugeben.

Zum Beispiel:

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

Hinweis

br/public ist der Alias für die öffentlichen Module. Er kann auch wie folgt geschrieben werden:

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 einen Link zu diesem Modul erstellen. 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 ist der Schemaname für eine Bicep-Registrierung.
Der Dateipfad wird in der Azure Container Registry mit repository bezeichnet. 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 bicep restore auf, 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 bei jeder Verwendung des Moduls den vollständigen Pfad anzugeben, können Sie Aliase in der Datei „bicepconfig.json“ konfigurieren. 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'
  }
}

Ein Alias für die öffentliche Modulregistrierung wurde vordefiniert:

module storage 'br/public:avm/res/storage/storage-account:0.9.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

Nach dem Erstellen einer Vorlagenspezifikation, können Sie diese Vorlagenspezifikation in einem Modul verknüpfen. Geben Sie die Vorlagenspezifikation im folgenden Format an:

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

Sie können Ihre Bicep-Datei jedoch vereinfachen, indem Sie einen Alias für die Ressourcengruppe erstellen, 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. Das Abonnement und die Ressourcengruppe für die Vorlagenspezifikation sind im Alias ContosoSpecs definiert.

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

Verwenden von Decorator-Elementen

Decorator-Elemente werden im Format @expression geschrieben und oberhalb von Moduldeklarationen platziert. In der folgenden Tabelle werden die für Module verfügbaren Decorator-Elemente gezeigt.

Decorator	Argument	Beschreibung
batchSize	none	Richten Sie Instanzen so ein, dass sie sequenziell bereitgestellt werden.
Beschreibung	string	Geben Sie Beschreibungen für das Modul an.

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

BatchSize

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)Decorator 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.9.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 enthält drei Parameter: storagePrefix, storageSKU und location. Der storageSKU-Parameter hat einen Standardwert, 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

Beim Deklarieren eines Moduls können Sie für das Modul einen Bereich festlegen, der sich vom Bereich für die enthaltene Bicep-Datei unterscheidet. 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 für die Bereichseigenschaft 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:

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

Bei Verwendung als Modul können Sie diesen Ausgabewert erhalten.

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

Nächste Schritte

Ein Tutorial finden Sie unter Erstellen Ihrer ersten Bicep-Vorlage.
Mithilfe der Funktion getSecret können Sie einen vertraulichen Wert an ein Modul übergeben.

Freigeben über