Freigeben über

Bereitstellen von Bicep-Dateien mit der Azure CLI

  • Artikel

In diesem Artikel wird erläutert, wie Ihre Ressourcen mithilfe der Azure CLI und Bicep-Dateien in Azure bereitgestellt werden. Wenn Sie mit der Bereitstellung und Verwaltung Ihrer Azure-Lösungen nicht vertraut sind, lesen Sie Was ist Bicep?.

Voraussetzungen

Sie benötigen für die Bereitstellung eine Bicep-Datei, die lokal gespeichert sein muss. Sie müssen außerdem die Azure CLI besitzen und mit Azure verbunden sein:

  • Befehl zur Installation der Azure-Befehlszeilenschnittstelle auf Ihrem lokalen Computer. Um Bicep-Dateien bereitzustellen, benötigen Sie die Azure CLI-Version 2.20.0 oder höher.
  • Verwenden Sie az login, um eine Verbindung mit Azure herzustellen. Wenn Sie über mehrere Azure-Abonnements verfügen, müssen Sie möglicherweise auch az account set ausführen.

Beispiele für die Azure-Befehlszeilenschnittstelle sind für die bash-Shell geschrieben. Wenn Sie dieses Beispiel in Windows PowerShell oder an der Eingabeaufforderung (cmd) ausführen möchten, müssen Sie unter Umständen Elemente des Skripts ändern.

Wenn die Azure CLI nicht installiert ist, können Sie Azure Cloud Shell verwenden. Weitere Informationen finden Sie unter Bereitstellen von Bicep-Dateien mit Azure Cloud Shell.

Erforderliche Berechtigungen

Zum Bereitstellen einer Bicep-Datei oder ARM-Vorlage benötigen Sie Schreibzugriff auf die Ressourcen, die Sie bereitstellen, und Zugriff auf alle Vorgänge für den Ressourcentyp Microsoft.Resources/deployments. Um beispielsweise eine VM bereitstellen zu können, benötigen Sie die Berechtigungen Microsoft.Compute/virtualMachines/write und Microsoft.Resources/deployments/*. Für den Was-wäre-wenn-Vorgang gelten die gleichen Berechtigungsanforderungen.

Eine Liste der Rollen und Berechtigungen finden Sie unter Integrierte Azure-Rollen.

Bereitstellungsumfang

Sie können als Ziel für Ihre Bereitstellung eine Ressourcengruppe, ein Abonnement, eine Verwaltungsgruppe oder einen Mandanten verwenden. Je nach Umfang der Bereitstellung müssen Sie unterschiedliche Befehle verwenden. Der Benutzer, der die Bicep-Datei bereitstellt, muss über die erforderlichen Berechtigungen verfügen, um Ressourcen für jeden Bereich zu erstellen.

Bereitstellen einer lokalen Bicep-Datei

Sie können eine Bicep-Datei bereitstellen, die auf Ihrem lokalen Computer oder extern gespeichert ist. In diesem Abschnitt wird beschrieben, wie eine lokale Bicep-Datei bereitgestellt wird.

Wenn eine Bereitstellung in einer Ressourcengruppe erfolgen soll, die nicht vorhanden ist, erstellen Sie zunächst die Ressourcengruppe. Der Name einer Ressourcengruppe darf nur alphanumerische Zeichen, Punkte, Unterstriche, Bindestriche und Klammern enthalten. Maximal 90 Zeichen sind zulässig, von denen das letzte kein Punkt sein darf.

az group create --name ExampleGroup --location "Central US"

Verwenden Sie zum Bereitstellen einer lokalen Bicep-Datei im Bereitstellungsbefehl den Schalter „--template-file“. Das folgende Beispiel zeigt auch, wie ein Parameterwert festgelegt wird:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-bicep> \
  --parameters storageAccountType=Standard_GRS

Die Bereitstellung kann einige Minuten dauern. Bei Abschluss wird eine Nachricht mit dem folgenden Ergebnis angezeigt:

"provisioningState": "Succeeded",

Bereitstellen einer Bicep-Remotedatei

Derzeit wird die Bereitstellung von Bicep-Remotedateien von der Azure CLI nicht unterstützt. Sie können die Bicep-Datei mithilfe der Bicep CLI in eine JSON-Vorlage erstellen und dann die JSON-Datei an einen Remotespeicherort laden. Weitere Informationen finden Sie unter Bereitstellen einer Remotevorlage.

Parameter

Zum Übergeben von Parameterwerten können Sie entweder Inlineparameter oder eine Parameterdatei verwenden. Die Parameterdatei kann eine Bicep-Parameterdatei oder eine JSON-Parameterdatei sein.

Inlineparameter

Wenn Sie Inlineparameter übergeben möchten, geben Sie die Werte in parameters an. Wenn Sie beispielsweise eine Zeichenfolge und ein Array einer Bicep-Datei in einer Bash-Shell übergeben möchten, verwenden Sie Folgendes:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters exampleString='inline string' exampleArray='["value1", "value2"]'

Wenn Sie die Azure CLI mit der cmd oder PowerShell verwenden, übergeben Sie das Array in folgendem Format: exampleArray="['value1','value2']".

Sie können auch den Inhalt einer Datei abrufen, um ihn als Inlineparameter zu übergeben. Stellen Sie dem Dateinamen ein @ voran:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

Das Abrufen eines Parameterwerts aus einer Datei ist praktisch, wenn Sie Konfigurationswerte angeben müssen. Sie können beispielsweise cloud-init-Werte für einen virtuellen Linux-Computer angeben.

Das Format von arrayContent.json lautet:

[
  "value1",
  "value2"
]

Um ein Objekt zu übergeben, verwenden Sie JSON (z. B. beim Festlegen von Kategorien). Ihre Bicep-Datei kann einen Parameter wie den folgenden enthalten:

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

Sie können auch eine JSON-Zeichenfolge übergeben, um den Parameter festzulegen, wie im folgenden Bash-Skript gezeigt. Schließen Sie den JSON-Code, der an das Objekt übergeben werden soll, in doppelte Anführungszeichen ein:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

Wenn Sie die Azure CLI mit der cmd oder PowerShell verwenden, übergeben Sie das Objekt im folgenden Format:

$tags="{'Owner':'Contoso','Cost Center':'2345-324'}"
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags=$tags

Sie können eine Variable verwenden, um die Parameterwerte einzufügen. Legen Sie die Variable auf alle Parameterwerte in Ihrem Bash-Skript fest, und fügen Sie sie dem Bereitstellungsbefehl hinzu:

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters $params

Wenn Sie jedoch die Azure CLI mit der cmd oder PowerShell verwenden, legen Sie die Variable auf eine JSON-Zeichenfolge fest. Versehen Sie Anführungszeichen mit einem Escapezeichen: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

Die Auswertung von Parametern erfolgt anhand einer sequenziellen Reihenfolge, was bedeutet, dass bei mehrfacher Zuweisung eines Werts nur der zuletzt zugewiesene Wert verwendet wird. Um Parameter korrekt zuzuweisen, wird empfohlen, Ihre Parameterdatei zu Beginn bereitzustellen und dann bestimmte Parameter mithilfe der KEY=VALUE-Syntax selektiv zu überschreiben. Sie können dieses Argument nur einmal verwenden, wenn Sie eine .bicepparam-Parameterdatei übergeben.

Bicep-Parameterdateien

Anstatt Parameter als Inlinewerte in Ihrem Skript zu übergeben, ist es eventuell einfacher, eine Bicep-Parameterdatei oder eine JSON-Parameterdatei zu verwenden, die die Parameterwerte enthält. Die Parameterdatei muss lokal gespeichert sein, da die Azure CLI keine externen Parameterdateien unterstützt. Weitere Informationen zu Parameterdateien finden Sie unter Erstellen von Parameterdateien für die Bicep-Bereitstellung.

Ab der Azure CLI-Version 2.53.0 und der Bicep CLI-Version 0.22.X können Sie eine Bicep-Datei mithilfe einer Bicep-Parameterdatei bereitstellen. Mit der using-Anweisung in der Bicep-Parameterdatei müssen Sie den --template-file-Schalter nicht angeben, wenn Sie eine Bicep-Parameterdatei für den --parameters-Schalter festlegen. Das Einschließen des Schalters --template-file führt zum Fehler „Mit einer bicepparam-Datei ist nur eine Bicep-Vorlage zulässig“.

Das folgende Beispiel zeigt eine Parameterdatei namens storage.bicepparam. Die Datei befindet sich im selben Verzeichnis, in dem der Befehl ausgeführt wird:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

JSON-Parameterdateien

Das folgende Beispiel zeigt eine Parameterdatei namens storage.parameters.json. Die Datei befindet sich im selben Verzeichnis, in dem der Befehl ausgeführt wird:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters '@storage.parameters.json'

Sie können Inlineparameter und eine Standortparameterdatei im selben Bereitstellungsvorgang verwenden. Weitere Informationen finden Sie unter Parameterrangfolge.

Vorschau der Änderungen

Vor dem Bereitstellen der Bicep-Datei können Sie die Änderungen, die von der Bicep-Datei an Ihrer Umgebung vorgenommen werden, in der Vorschau anzeigen. Überprüfen Sie anhand des Was-wäre-wenn-Vorgangs, ob die Bicep-Datei die erwarteten Änderungen vornimmt. Mit „Was-wäre-wenn“ wird die Bicep-Datei auch auf Fehler überprüft.

Bereitstellen von Vorlagenspezifikationen

Derzeit stellt die Azure CLI keine Bicep-Dateien bereit, um Vorlagenspezifikationen zu erstellen. Sie können jedoch eine Bicep-Datei mit der Microsoft.Resources/templateSpecs-Ressource erstellen, um eine Vorlagenspezifikation bereitzustellen. Das Beispiel „Erstellen einer Vorlagenspezifikation“ zeigt, wie eine Vorlagenspezifikation in einer Bicep-Datei erstellt wird. Sie können Ihre Bicep-Datei auch über die Bicep CLI im JSON-Format erstellen und dann eine Vorlagenspezifikation mit der JSON-Vorlage erstellen.

„Deployment name“ (Bereitstellungsname)

Wenn Sie eine Bicep-Datei bereitstellen, können Sie der Bereitstellung einen Namen geben. Dieser Name kann das Abrufen der Bereitstellung aus dem Bereitstellungsverlauf vereinfachen. Wenn Sie keinen Namen für die Bereitstellung angeben, erhält sie den Namen der Bicep-Datei. Wenn Sie beispielsweise eine Bicep-Datei mit dem Namen main.bicep bereitstellen und keinen Bereitstellungsnamen angeben, erhält die Bereitstellung den Namen main.

Bei jeder Ausführung einer Bereitstellung wird dem Bereitstellungsverlauf der Ressourcengruppe ein Eintrag mit dem Bereitstellungsnamen hinzugefügt. Wenn Sie eine andere Bereitstellung ausführen und denselben Namen vergeben, wird der vorherige Eintrag durch die aktuelle Bereitstellung ersetzt. Wenn Sie eindeutige Einträge im Bereitstellungsverlauf beibehalten möchten, müssen Sie jeder Bereitstellung einen eindeutigen Namen geben.

Um einen eindeutigen Namen zu erstellen, können Sie eine Zufallszahl zuweisen:

deploymentName='ExampleDeployment'$RANDOM

Sie können auch einen Datumswert hinzufügen:

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

Wenn Sie gleichzeitige Bereitstellungen in derselben Ressourcengruppe mit dem gleichen Bereitstellungsnamen ausführen, wird nur die letzte Bereitstellung abgeschlossen. Alle Bereitstellungen mit dem gleichen Namen, die noch nicht abgeschlossen wurden, werden durch die letzte Bereitstellung ersetzt. Wenn Sie z. B. eine Bereitstellung mit dem Namen newStorage ausführen, die ein Speicherkonto mit dem Namen storage1 bereitstellt, und gleichzeitig eine andere Bereitstellung mit dem Namen newStorage ausführen, die ein Speicherkonto mit dem Namen storage2 bereitstellt, wird nur ein Speicherkonto bereitgestellt. Das resultierende Speicherkonto hat den Namen storage2.

Führen Sie jedoch eine Bereitstellung mit dem Namen newStorage aus, die ein Speicherkonto mit dem Namen storage1 bereitstellt, und führen Sie direkt nach dem Abschluss der ersten Bereitstellung eine andere Bereitstellung mit dem Namen newStorage aus, die ein Speicherkonto mit dem Namen storage2 bereitstellt, erhalten Sie zwei Speicherkonten. Eines hat den Namen storage1 und das andere den Namen storage2. Es ist jedoch nur ein Eintrag im Bereitstellungsverlauf vorhanden.

Wenn Sie für jede Bereitstellung einen eindeutigen Namen angeben, können Sie diese ohne Konflikt gleichzeitig ausführen. Wenn Sie eine Bereitstellung mit dem Namen newStorage1 ausführen, die ein Speicherkonto mit dem Namen storage1 bereitstellt, und gleichzeitig eine andere Bereitstellung mit dem Namen newStorage2 ausführen, die ein Speicherkonto mit dem Namen storage2 bereitstellt, erhalten Sie zwei Speicherkonten und zwei Einträge im Bereitstellungsverlauf.

Geben Sie jeder Bereitstellung einen eindeutigen Namen, um Konflikte mit gleichzeitigen Bereitstellungen zu vermeiden und eindeutige Einträge im Bereitstellungsverlauf zu gewährleisten.

Nächste Schritte

Um zu verstehen, wie Parameter in der Vorlage definiert werden, lesen Sie Verstehen der Struktur und Syntax von ARM-Vorlagen.