Verwenden von ARM-Bereitstellungsvorlagen (Azure Resource Manager) mit der Azure CLI

  • Artikel

In diesem Artikel wird erläutert, wie Sie Ihre Ressourcen mithilfe der Azure CLI und Azure Resource Manager-Vorlagen (ARM) in Azure bereitstellen. Wenn Sie nicht mit den Konzepten der Bereitstellung und Verwaltung Ihrer Azure-Lösungen vertraut sind, informieren Sie sich unter Übersicht über die Vorlagenbereitstellung.

Die Bereitstellungsbefehle wurden in Version 2.2.0 der Azure CLI geändert. Die Beispiele in diesem Artikel erfordern Version 2.20.0 oder höher der Azure CLI.

Installieren Sie zum Ausführen dieses Beispiels die aktuelle Version der Azure-Befehlszeilenschnittstelle. Führen Sie zum Starten az login aus, um eine Verbindung mit Azure herzustellen.

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

Wenn die Azure-Befehlszeilenschnittstelle nicht installiert ist, können Sie Azure Cloud Shell verwenden. Weitere Informationen finden Sie unter Bereitstellen von ARM-Vorlagen über Azure Cloud Shell.

Tipp

Wir empfehlen Bicep, weil es dieselben Funktionen wie ARM-Vorlagen bietet und die Syntax einfacher zu verwenden ist. Weitere Informationen finden Sie unter Bereitstellen von Ressourcen mit Bicep und Azure CLI.

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 Azure-Bereitstellungsvorlage eine Ressourcengruppe, ein Abonnement, eine Verwaltungsgruppe oder einen Mandanten verwenden. Abhängig vom Umfang der Bereitstellung verwenden Sie unterschiedliche Befehle.

Der Benutzer, der die Vorlage bereitstellt, muss für jeden Bereich über die erforderlichen Berechtigungen zum Erstellen von Ressourcen verfügen.

Bereitstellen einer lokalen Vorlage

Sie können eine ARM-Vorlage bereitstellen, die auf Ihrem lokalen Computer oder extern gespeichert ist. In diesem Abschnitt wird die Bereitstellung einer lokalen Vorlage beschrieben.

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. Der Name kann bis zu 90 Zeichen umfassen. Der Name darf nicht mit einem Punkt enden.

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

Verwenden Sie zum Bereitstellen einer lokalen Vorlage im Bereitstellungsbefehl den Parameter --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-template> \
  --parameters storageAccountType=Standard_GRS

Der Wert des Parameters --template-file muss eine Bicep-Datei oder eine .json- oder eine .jsonc-Datei sein. Die Dateierweiterung .jsonc gibt an, dass die Datei Kommentare im //-Stil enthalten kann. Das ARM-System akzeptiert //-Kommentare in .json-Dateien. Die Dateierweiterung ist dabei nicht relevant. Weitere Informationen zu Kommentaren und Metadaten finden Sie unter Verstehen der Struktur und Syntax von ARM-Vorlagen.

Das Abschließen der Azure-Bereitstellungsvorlage kann einige Minuten dauern. Wenn sie abgeschlossen ist, wird eine Nachricht mit dem Ergebnis angezeigt:

"provisioningState": "Succeeded",

Bereitstellen einer Remotevorlage

Anstatt ARM-Vorlagen auf dem lokalen Computer zu speichern, können Sie sie auch an einem externen Speicherort speichern. Sie können Vorlagen in einem Quellcodeverwaltungs-Repository (z.B. GitHub) speichern. Für den gemeinsamen Zugriff in Ihrer Organisation können Sie sie auch in einem Azure-Speicherkonto speichern.

Hinweis

Um eine Vorlage bereitzustellen oder auf eine verknüpfte Vorlage zu verweisen, die in einem privaten GitHub-Repository gespeichert ist, können Sie eine der benutzerdefinierten Lösungen verwenden, die in Erstellen eines benutzerdefinierten und sicheren Azure Portal-Angebots dokumentiert sind. Sie können eine Azure-Funktion erstellen, die das GitHub-Token aus Azure Key Vault abruft.

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. Der Name kann bis zu 90 Zeichen umfassen. Der Name darf nicht mit einem Punkt enden.

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

Verwenden Sie zum Bereitstellen einer externen Vorlage den template-uri-Parameter.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

Das obige Beispiel erfordert einen URI mit öffentlichem Zugriff für die Vorlage, was in den meisten Szenarien funktioniert, da die Vorlage keine vertraulichen Daten enthalten sollte. Wenn Sie vertrauliche Daten (z.B. ein Administratorkennwort) angeben müssen, übergeben Sie diesen Wert als sicheren Parameter. Wenn Sie jedoch den Zugriff auf die Vorlage verwalten möchten, erwägen Sie den Einsatz von Vorlagenspezifikationen.

Wenn Sie remoteverknüpfte Vorlagen mit einem relativen Pfad bereitstellen möchten, die in einem Speicherkonto gespeichert sind, verwenden Sie query-string, um das SAS-Token anzugeben:

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

Weitere Informationen finden Sie unter Verwenden des relativen Pfads für verknüpfte Vorlagen.

Azure-Bereitstellungsvorlagenname

Wenn Sie eine ARM-Vorlage bereitstellen, können Sie der Azure-Bereitstellungsvorlage einen Namen geben. Dieser Name kann das Abrufen der Bereitstellung aus dem Bereitstellungsverlauf vereinfachen. Wenn Sie keinen Namen für die Bereitstellung angeben, wird der Name der Vorlagendatei verwendet. Wenn Sie beispielsweise eine Vorlage mit dem Namen azuredeploy.json bereitstellen und keinen Bereitstellungsnamen angeben, erhält die Bereitstellung den Namen azuredeploy.

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 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 namens newStorage1 ausführen, die ein Speicherkonto namens storage1 bereitstellt, und gleichzeitig eine andere Bereitstellung namens newStorage2 ausführen, die ein Speicherkonto namens storage2 bereitstellt, erhalten Sie zwei Speicherkonten und zwei Einträge im Bereitstellungsverlauf.

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

Bereitstellen der Vorlagenspezifikationen

Anstatt eine lokale oder Remotevorlage bereitzustellen, können Sie eine Vorlagenspezifikation erstellen. Bei der Vorlagenspezifikation handelt es sich um eine Ressource im Azure-Abonnement, die eine ARM-Vorlage enthält. Sie vereinfacht die sichere Freigabe der Vorlage für Benutzer in Ihrer Organisation. Mit der rollenbasierten Zugriffssteuerung von Azure (Role-Based Access Control, Azure RBAC) können Sie Zugriff auf die Vorlagenspezifikation gewähren. Diese Funktion steht derzeit als Vorschau zur Verfügung.

In den folgenden Beispielen wird das Erstellen und Bereitstellen einer Vorlagenspezifikation veranschaulicht.

Als Erstes erstellen Sie die Vorlagenspezifikation, indem Sie die ARM-Vorlage angeben.

az ts create \
  --name storageSpec \
  --version "1.0" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

Rufen Sie anschließend die ID der Vorlagenspezifikation ab, und stellen Sie sie bereit.

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

Weitere Informationen finden Sie unter Azure Resource Manager-Vorlagenspezifikationen.

Vorschau der Änderungen

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

Parameter

Zum Übergeben von Parameterwerten können Sie entweder Inlineparameter oder eine Parameterdatei verwenden. Die Parameterdatei kann eine Bicep- 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 an eine Vorlage in einer Bash-Shell übergeben möchten, verwenden Sie Folgendes:

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

Wenn Sie die Azure-Befehlszeilenschnittstelle mit der Windows-Eingabeaufforderung (CMD) oder PowerShell verwenden, übergeben Sie das Array in folgendem Format: exampleArray="['value1','value2']".

Sie können auch den Inhalt einer Datei abrufen und als Inlineparameter übergeben.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --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"
]

Verwenden Sie JSON, um ein Objekt zu übergeben, z. B. zum Festlegen von Tags. Ihre Vorlage kann z. B. einen Parameter wie den folgenden enthalten:

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

In diesem Fall können Sie eine JSON-Zeichenfolge übergeben, um den Parameter festzulegen, wie im folgenden Bash-Skript gezeigt:

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

Schließen Sie den JSON-Code, der an das Objekt übergeben werden soll, in doppelte Anführungszeichen ein.

Sie können eine Variable verwenden, um die Parameterwerte einzufügen. Legen Sie in Bash die Variable auf alle Parameterwerte 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-template> \
  --parameters $params

Wenn Sie jedoch die Azure-Befehlszeilenschnittstelle mit der Windows-Eingabeaufforderung (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\"} }'.

JSON-Parameterdateien

Anstatt Parameter als Inlinewerte in Ihrem Skript zu übergeben, ist es eventuell einfacher, eine Datei (eine .bicepparam-Datei oder eine JSON-Parameterdatei) zu verwenden, die die Parameterwerte enthält. Die Parameterdatei muss eine lokale Datei sein. Externe Parameterdateien werden mit der Azure CLI nicht unterstützt.

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

Weitere Informationen zur Parameterdatei finden Sie unter Erstellen einer Resource Manager-Parameterdatei.

Bicep-Parameterdateien

Mit Version 2.53.0 oder höher der Azure-Befehlszeilenschnittstelle und Version 0.22.6 oder höher der Bicep CLI können Sie eine Bicep-Datei mithilfe einer Bicep-Parameterdatei bereitstellen. Bei der using-Anweisung in der Bicep-Parameterdatei muss die Option --template-file nicht angegeben werden, wenn Sie eine Bicep-Parameterdatei für die Option --parameters angeben. Wenn Sie den Schalter --template-file einbeziehen, erhalten Sie die Fehlermeldung „Es ist nur eine .bicep-Vorlage mit einer .bicepparam-Datei zulässig“.

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

Die Parameterdatei muss eine lokale Datei sein. Externe Parameterdateien werden mit der Azure CLI nicht unterstützt. Weitere Informationen zur Parameterdatei finden Sie unter Erstellen einer Resource Manager-Parameterdatei.

Kommentare und das erweiterte JSON-Format

Sie können Kommentare im //-Stil in Ihre Parameterdatei einfügen, aber Sie müssen die Datei mit einer .jsonc-Erweiterung benennen.

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

Weitere Informationen zu Kommentaren und Metadaten finden Sie unter Verstehen der Struktur und Syntax von ARM-Vorlagen.

Wenn Sie die Azure CLI mit Version 2.3.0 oder früher verwenden, können Sie eine Vorlage mit mehrzeiligen Zeichenfolgen oder Kommentaren über die Option --handle-extended-json-format bereitstellen. Beispiel:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Nächste Schritte