Schnellstart: Fehlerbehebung bei der Bereitstellung von JSON-ARM-Vorlagen

Artikel
06/20/2024

Dieser Schnellstart beschreibt, wie Sie Fehler bei der Bereitstellung von JSON-Azure Resource Manager-Vorlagen (ARM-Vorlagen) beheben können. Sie richten eine Vorlage mit Fehlern ein und erfahren, wie Sie die Fehler beheben.

Eine Azure Resource Manager-Vorlage ist eine JSON (JavaScript Object Notation)-Datei, welche die Infrastruktur und die Konfiguration für Ihr Projekt definiert. Die Vorlage verwendet eine deklarative Syntax. Sie beschreiben Ihre geplante Bereitstellung, ohne die Abfolge der Programmierbefehle zu schreiben, mit denen die Bereitstellung erstellt wird.

Es gibt drei Arten von Fehlern, die mit einer Bereitstellung zusammenhängen:

Validierungsfehler treten auf, bevor ein Einsatz beginnt, und werden durch Syntaxfehler in Ihrer Datei verursacht. Mit einem Code-Editor wie Visual Studio Code können diese Fehler identifiziert werden.
Preflight-Validierungsfehler treten auf, wenn ein Bereitstellungsbefehl zwar ausgeführt wird, Ressourcen aber nicht bereitgestellt werden. Diese Fehler werden gefunden, ohne dass die Bereitstellung gestartet wird. Wenn zum Beispiel ein Parameterwert falsch ist, wird der Fehler bei der Preflight-Validierung gefunden.
Bereitstellungsfehler treten während des Bereitstellungsprozesses auf und können nur durch die Bewertung des Einrichtungsfortschritts in Ihrer Azure-Umgebung gefunden werden.

Alle Fehlertypen geben einen Fehlercode zurück, den Sie bei der Fehlersuche in der Bereitstellung verwenden können. Validierungs- und Preflight-Fehler werden im Aktivitätsprotokoll angezeigt, aber nicht im Bereitstellungsverlauf.

Voraussetzungen

Um diesen Schnellstart durchzuführen, benötigen Sie die folgenden Gegenstände:

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
Visual Studio Code mit der neuesten Azure Resource Manager Tools-Erweiterung.
Installieren Sie die aktuelle Version von Azure PowerShell oder der Azure CLI.

Eine Vorlage mit Fehlern erstellen

Kopieren Sie die folgende Vorlage, und speichern Sie sie lokal. Sie verwenden diese Datei, um einen Validierungsfehler, einen Preflight-Fehler und einen Bereitstellungsfehler zu beheben. In dieser Schnellstartanleitung wird davon ausgegangen, dass Sie die Datei troubleshoot.json genannt haben. Sie können aber auch einen anderen Namen verwenden.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameterss": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "prefixName": {
      "type": "string"
    }
  },
  "variables": {
    "storageAccountName": "[concat(parameters('prefixName'), uniquestring(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    },
    "vnetResult": {
      "type": "object",
      "value": "[reference(resourceId('Microsoft.Network/virtualNetworks', 'doesnotexist'), '2021-03-01', 'Full')]"
    }
  }
}

Validierungsfehler beheben

Öffnen Sie die Datei in Visual Studio Code. Die Wellenlinie unter parameterss: weist auf einen Fehler hin. Zeigen Sie auf den Fehler, um den Validierungsfehler anzuzeigen.

Screenshot von Visual Studio Code, der einen mit einer roten Wellenlinie hervorgehobenen Vorlagenvalidierungsfehler unter dem falsch geschriebenen 'parameterss:' im Code zeigt.

Wie Sie sehen, liegen für variables und resources Fehler aufgrund eines nicht definierten Parameterverweises (undefined parameter reference) vor. Wählen Sie zum Anzeigen der Validierungsfehler der Vorlage Ansicht>Probleme aus.

Screenshot von Visual Studio Code, der die Registerkarte „Probleme“ zeigt, die nicht definierte Parameterreferenzfehler für die Abschnitte 'variables' und 'resources' auflisten.

Alle Fehler werden durch einen falsch geschriebenen Elementnamen verursacht.

"parameterss": {

Die Fehlermeldung lautet: Fehler bei der Vorlagenüberprüfung: Member "parameterss" für Objekt vom Typ "Template" nicht gefunden. Pfad "parameterss", Zeile 4, Position 16.

Die ARM-Vorlagensyntax für parameters zeigt, dass parameters der korrekte Elementname ist.

Korrigieren Sie die Schreibweise, und speichern Sie die Datei, um den Validierungsfehler sowie die Fehler aufgrund eines nicht definierten Parameterverweises (undefined parameter reference) zu beheben.

"parameters": {

Preflight-Fehler beheben

Verwenden Sie einen falschen Wert für den Parameter prefixName, um einen Fehler bei der Preflightüberprüfung zu verursachen.

In dieser Schnellstartanleitung wird troubleshootRG als Ressourcengruppenname verwendet, Sie können aber auch einen anderen Namen verwenden.

Azure-Befehlszeilenschnittstelle
PowerShell

az group create --name troubleshootRG --location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.json \
  --parameters prefixName=long!!StoragePrefix

New-AzResourceGroup -Name troubleshootRG -Location westus
New-AzResourceGroupDeployment `
  -ResourceGroupName troubleshootRG `
  -TemplateFile troubleshoot.json `
  -prefixName long!!StoragePrefix

Die Preflightüberprüfung für die Vorlage ist nicht erfolgreich, und die Bereitstellung wird nicht ausgeführt. prefixName ist mehr als elf Zeichen lang und enthält Sonderzeichen und Großbuchstaben.

Speichernamen müssen zwischen drei und 24 Zeichen lang sein und dürfen nur Kleinbuchstaben und Ziffern enthalten. Durch den Präfixwert ist ein ungültiger Speichername entstanden. Weitere Informationen finden Sie unter Beheben von Fehlern bei Speicherkontonamen. Um den Preflightfehler zu beheben, verwenden Sie ein Präfix mit maximal elf Zeichen, das nur Kleinbuchstaben oder Zahlen enthält.

Da die Bereitstellung nicht ausgeführt wurde, gibt es auch keinen Bereitstellungsverlauf.

Screenshot der Übersichtsseite der Azure-Ressourcengruppe, die einen leeren Abschnitt des Bereitstellungsverlaufs aufgrund eines Preflightfehlers zeigt.

Das Aktivitätsprotokoll enthält den Preflightfehler. Wählen Sie das Protokoll aus, um die Details des Fehlers anzuzeigen.

Screenshot des Aktivitätsprotokolls der Azure-Ressourcengruppe, der einen Preflightfehlereintrag mit einem roten Ausrufezeichen zeigt.

Einsatzfehler beheben

Führen Sie die Bereitstellung mit einem gültigen Präfixwert (beispielsweise storage) aus.

Azure-Befehlszeilenschnittstelle
PowerShell

az group create --name troubleshootRG --location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.json \
  --parameters prefixName=storage

New-AzResourceGroup -Name troubleshootRG -Location westus
New-AzResourceGroupDeployment `
  -ResourceGroupName troubleshootRG `
  -TemplateFile troubleshoot.json `
  -prefixName storage

Die Bereitstellung beginnt und wird im Bereitstellungsverlauf angezeigt. Die Bereitstellung ist nicht erfolgreich, da von outputs auf ein virtuelles Netzwerk verwiesen wird, das in der Ressourcengruppe nicht vorhanden ist. Da jedoch keine Fehler für das Speicherkonto aufgetreten sind, wurde die Ressource bereitgestellt. Der Bereitstellungsverlauf enthält eine nicht erfolgreiche Bereitstellung.

Screenshot der Übersichtsseite der Azure-Ressourcengruppe, die eine fehlerhafte Bereitstellung mit einem roten Ausrufezeichen im Abschnitt für den Bereitstellungsverlauf zeigt.

Um den Bereitstellungsfehler zu beheben, ändern Sie die Verweisfunktion so, dass eine gültige Ressource verwendet wird. Weitere Informationen finden Sie unter Beheben von Fehlern des Typs „Ressource nicht gefunden“. Löschen Sie für diese Schnellstartanleitung das Komma vor vnetResult und den gesamten Code für vnetResult. Speichern Sie anschließend die Datei, und führen Sie die Bereitstellung erneut aus.

"vnetResult": {
  "type": "object",
  "value": "[reference(resourceId('Microsoft.Network/virtualNetworks', 'doesnotexist'), '2021-03-01', 'Full')]"
}

Nachdem die Überprüfungs-, Preflight- und Bereitstellungsfehler behoben wurden, stellt die folgende Vorlage ein Speicherkonto bereit. Bereitstellungsverlauf und Aktivitätsprotokoll enthalten jeweils eine erfolgreiche Bereitstellung.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "prefixName": {
      "type": "string"
    }
  },
  "variables": {
    "storageAccountName": "[concat(parameters('prefixName'), uniquestring(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    }
  }
}

Bereinigen von Ressourcen

Wenn die Azure-Ressourcen nicht mehr benötigt werden, löschen Sie die Ressourcengruppe.

Azure-Befehlszeilenschnittstelle
PowerShell

az group delete --name troubleshootRG

Remove-AzResourceGroup -Name troubleshootRG

Um die Ressourcengruppe aus dem Portal zu löschen, gehen Sie wie folgt vor:

Geben Sie im Azure-Portal im Suchfeld Ressourcengruppen ein.
Geben Sie den Namen der Ressourcengruppe in das Feld Nach Name filtern ein.
Klicken Sie auf den Namen der Ressourcengruppe.
Wählen Sie die Option Ressourcengruppe löschen.
Um den Löschvorgang zu bestätigen, geben Sie den Namen der Ressourcengruppe ein, und wählen Sie Löschen aus.

Nächste Schritte

In diesem Schnellstart haben Sie gelernt, wie Sie Fehler bei der Bereitstellung von ARM-Vorlagen beheben können.

Fehlerbehebung für häufige Azure-Bereitstellungsfehler

Freigeben über