Bicep-Module

Artikel
02/02/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), 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, eine öffentliche Registrierung 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 benutzerdefinierte Konfigurationsdatei mit der Standardkonfigurationsdatei zusammenführen kann, 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.

Definitionssyntax

Die grundlegende Syntax zum Definieren eines Moduls ist:

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. Diese Optionen werden nachstehend vorgestellt.

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

Die öffentliche Modulregistrierung wird in einer Microsoft-Containerregistrierung (MCR) gehostet. Der Quellcode und die Module werden auf GitHub gespeichert. Informationen zum Anzeigen der verfügbaren Module und deren Versionen finden Sie unter Modulindex der Bicep-Registrierung.

The screenshot of public module registry.

Wählen Sie die Versionen aus, um die verfügbaren Versionen anzuzeigen. Sie können auch Quellcode auswählen, um den Modulquellcode anzuzeigen und die Infodateien zu öffnen.

Derzeit gibt es nur wenige veröffentlichte Module. Es werden weitere Module folgen. Wenn Sie zur Registrierung beitragen möchten, lesen Sie den Leitfaden für Mitwirkende an Beiträgen.

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

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

br/public ist der Alias für die Registrierung des öffentlichen Moduls. Dieser Alias ist in Ihrer Konfiguration vordefiniert.
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 hw 'br/public:samples/hello-world:1.0.2' = {
  name: 'helloWorld'
  params: {
    name: 'John Dole'
  }
}

Hinweis

br/public ist der Alias für die öffentliche Registrierung. 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 hw 'br/public:samples/hello-world:1.0.2' = {
  name: 'helloWorld'
  params: {
    name: 'John Dole'
  }
}

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

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

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

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

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

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.