Hinzufügen von Parametern und Ausgaben zu Modulen

  • 7 Minuten

Jedes erstellte Modul sollte einen eindeutigen Zweck haben. Stellen Sie sich ein Modul als einen Vertrag vor. Es akzeptiert eine Gruppe von Parametern, erstellt mehrere Ressourcen und gibt möglicherweise einige Ausgaben an die übergeordnete Vorlage zurück. Jeder, der das Modul verwendet, soll sich keine Gedanken über die Funktionsweise machen, sondern nur darüber, ob es das macht, was es soll.

Berücksichtigen Sie beim Planen eines Moduls Folgendes:

  • Was müssen Sie wissen, um den Zweck des Moduls erfüllen zu können?
  • Welche Eingaben erwarten die Benutzer*innen Ihres Moduls?
  • Welche Ausgaben erwarten die Benutzer*innen Ihres Moduls?

Modulparameter

Machen Sie sich Gedanken über die Parameter, die Ihr Modul akzeptiert, und darüber, ob jeder Parameter optional oder erforderlich sein soll.

Wenn Sie Parameter für Vorlagen erstellen, ist es eine bewährte Methode, nach Möglichkeit Standardparameter hinzuzufügen. In Modulen ist es nicht immer so wichtig, Standardparameter hinzuzufügen, da Ihr Modul von einer übergeordneten Vorlage verwendet wird, die möglicherweise eigene Standardparameter nutzt. Wenn Sie in beiden Dateien über ähnliche Parameter verfügen (beide mit Standardwerten), kann es für die Benutzer*innen Ihrer Vorlage schwierig sein, herauszufinden, welcher Standardwert angewendet wird, und Konsistenz zu erzwingen. Häufig ist es besser, den Standardwert in der übergeordneten Vorlage zu übernehmen und aus dem Modul zu entfernen.

Sie sollten auch überlegen, wie Sie Parameter verwalten, die die SKUs für Ihre Ressourcen und andere wichtige Konfigurationseinstellungen steuern. Wenn Sie eine eigenständige Bicep-Vorlage erstellen, ist es üblich, Geschäftsregeln in Ihre Vorlage einzubetten. Beispiel: Wenn ich eine Produktionsumgebung bereitstelle, soll für das Speicherkonto die GRS-Ebene verwendet werden. Module stellen jedoch manchmal andere Probleme dar.

Wenn Sie ein Modul erstellen, das wiederverwendbar und flexibel sein muss, denken Sie daran, dass die Geschäftsregeln für jede übergeordnete Vorlage unterschiedlich sein können, sodass es möglicherweise nicht so sinnvoll ist, Geschäftsregeln in generische Module einzubetten. Erwägen Sie, die Geschäftsregeln in Ihrer übergeordneten Vorlage zu definieren, und übergeben Sie dann explizit die Modulkonfiguration über Parameter.

Wenn Sie jedoch ein Modul erstellen, das Ihrer eigenen Organisation das Bereitstellen von Ressourcen erleichtern soll, die Ihren spezifischen Anforderungen entsprechen, ist es sinnvoll, Geschäftsregeln einzuschließen, um die übergeordneten Vorlagen zu vereinfachen.

Unabhängig von den Parametern, die Sie in Ihr Modul einschließen, stellen Sie sicher, dass Sie mithilfe des @description-Attributs eine aussagekräftige Beschreibung hinzufügen:

@description('The name of the storage account to deploy.')
param storageAccountName string

Verwenden von Bedingungen

Eines der Ziele bei der Bereitstellung einer Infrastruktur mithilfe von Code wie Bicep besteht darin, eine doppelte Ausführung von Aufgaben oder sogar die Erstellung mehrerer Vorlagen für denselben oder einen ähnlichen Zweck zu vermeiden. Mit den Features von Bicep verfügen Sie über eine leistungsstarke Toolbox zur Erstellung wiederverwendbarer Module, die in einer Vielzahl von Situationen einsetzbar sind. Sie können Features wie Module, Ausdrücke, Standardparameterwerte und Bedingungen kombinieren, um wiederverwendbaren Code zu erstellen, der Ihnen die erforderliche Flexibilität bietet.

Angenommen, Sie erstellen ein Modul, das ein Azure Cosmos DB-Konto bereitstellt. Wenn das Konto in Ihrer Produktionsumgebung bereitgestellt wird, müssen Sie es so konfigurieren, dass die zugehörigen Protokolle an einen Log Analytics-Arbeitsbereich gesendet werden. Zum Konfigurieren von Protokollen, die an Log Analytics gesendet werden sollen, definieren Sie eine diagnosticSettings-Ressource.

Sie können Ihre Anforderung erfüllen, indem Sie der Ressourcendefinition eine Bedingung hinzufügen und den Parameter für die Arbeitsbereich-ID durch das Hinzufügen eines Standardwerts optional machen:

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

Wenn Sie dieses Modul in eine Bicep-Vorlage einschließen, können Sie es durch Festlegen einer Arbeitsbereichs-ID problemlos so konfigurieren, dass die Azure Cosmos DB-Kontoprotokolle an Log Analytics gesendet werden. Wenn Sie keine Protokolle für die bereitgestellte Umgebung benötigen, können Sie den Parameter auch weglassen. Die Umgebung verfügt über einen Standardwert. Das Modul kapselt die Logik, die erforderlich ist, damit Ihre Anforderungen erfüllt werden.

Tipp

Denken Sie daran, zu testen, ob Ihre Vorlage für beide Szenarios gültig ist, wenn die if-Anweisung entweder als true oder als false ausgewertet wird.

Modulausgaben

Module können Ausgaben definieren. Es empfiehlt sich, eine Ausgabe für die Informationen zu erstellen, die die übergeordnete Vorlage möglicherweise verwenden muss. Wenn Ihr Modul beispielsweise ein Speicherkonto definiert, sollten Sie eine Ausgabe für den Namen des Speicherkontos erstellen, damit die übergeordnete Vorlage darauf zugreifen kann.

Warnung

Verwenden Sie keine Ausgaben für Geheimniswerte. Ausgaben werden als Teil des Bereitstellungsverlaufs protokolliert, sodass sie nicht für sichere Werte geeignet sind. Sie können stattdessen eine der folgenden Optionen in Betracht ziehen:

  • Verwenden Sie eine Ausgabe, um den Namen der Ressource anzugeben. Anschließend kann die übergeordnete Vorlage eine existing-Ressource mit diesem Namen erstellen und den sicheren Wert dynamisch suchen.
  • Schreiben Sie den Wert in ein Azure Key Vault-Geheimnis. Lassen Sie die übergeordnete Vorlage das Geheimnis aus dem Tresor lesen, wenn sie es benötigt.

Eine übergeordnete Vorlage kann Modulausgaben in Variablen verwenden, Eigenschaften für andere Ressourcendefinitionen nutzen oder Variablen und Eigenschaften als Ausgaben selbst verfügbar machen. Wenn Sie Ausgaben in Ihren Bicep-Dateien verfügbar machen und verwenden, können Sie wiederverwendbare Gruppen von Bicep-Modulen erstellen, die für Ihr Team freigegeben und für mehrere Bereitstellungen wiederverwendet werden können. Es empfiehlt sich auch, Ausgaben mithilfe des @description-Attributs eine aussagekräftige Beschreibung hinzuzufügen:

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

Tipp

Sie können auch dedizierte Dienste verwenden, um die von Ihrer Bicep-Vorlage erstellten Einstellungen zu speichern, zu verwalten und darauf zuzugreifen. Key Vault dient zum Speichern sicherer Werte. Azure App Configuration ist ein Dienst zum Speichern anderer (nicht sicherer) Werte.

Verketten von Modulen

Es ist üblich, eine übergeordnete Bicep-Datei zu erstellen, die mehrere Module zusammensetzt. Stellen Sie sich beispielsweise vor, Sie erstellen eine neue Bicep-Vorlage, um virtuelle Computer bereitzustellen, die dedizierte virtuelle Netzwerke verwenden. Sie können ein Modul erstellen, um ein virtuelles Netzwerk zu definieren. Anschließend können Sie die Subnetzressourcen-ID des virtuellen Netzwerks als Ausgabe dieses Moduls verwenden und als Eingabe für das Modul des virtuellen Computers nutzen:

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

In diesem Beispiel werden symbolische Namen für den Verweis zwischen den Modulen verwendet. Dieser Verweis hilft Bicep, die Beziehungen zwischen den Modulen automatisch zu verstehen.

Da Bicep weiß, dass eine Abhängigkeit vorliegt, werden die Module nacheinander bereitgestellt:

  1. Bicep stellt alles im Modul virtualNetwork bereit.
  2. Wenn diese Bereitstellung erfolgreich ist, greift Bicep auf den Ausgabewert subnetResourceId zu und übergibt ihn als Parameter an das virtualMachine-Modul.
  3. Bicep stellt alles im Modul virtualMachine bereit.

Hinweis

Wenn Sie von einem Modul abhängig sind, wartet Bicep, bis die gesamte Modulbereitstellung abgeschlossen ist. Beachten Sie dies unbedingt, wenn Sie Ihre Module planen. Wenn Sie ein Modul erstellen, das eine Ressource definiert, deren Bereitstellung lange dauert, warten alle anderen Ressourcen, die von diesem Modul abhängen, auf den Abschluss der Bereitstellung des gesamten Moduls.