Beheben von Fehlern aufgrund ungültiger Vorlagen

  • Artikel

In diesem Artikel wird beschrieben, wie Fehler aufgrund ungültiger Vorlagen für Bicep-Dateien und Azure Resource Manager-Vorlagen (ARM-Vorlagen) behoben werden. Der Fehler tritt aus mehreren Gründen auf, z. B. wegen eines Syntaxfehlers, eines ungültigen Parameterwerts oder einer Ringabhängigkeit.

Symptom

Wenn eine Vorlage bereitgestellt wird, erhalten Sie folgenden Fehler:

Code=InvalidTemplate
Message=<varies>

Die Fehlermeldung hängt vom Typ des Fehlers ab.

Ursache

Dieser Fehler kann aus verschiedenen Arten von Fehlern entstehen. Normalerweise handelt es sich um einen Syntax- oder Strukturfehler in der Vorlage.

Lösung 1: Syntaxfehler

Wenn Sie eine Fehlermeldung erhalten, die auf eine fehlerhafte Vorlagenüberprüfung hinweist, ist in Ihrer Vorlage möglicherweise ein Syntaxproblem vorhanden.

Code=InvalidTemplate
Message=Deployment template validation failed

Syntaxfehler können auftreten, da Vorlagenausdrücke viele Elemente enthalten. Die Namenszuweisung für ein Speicherkonto umfasst beispielsweise Paare aus einfachen oder doppelten Anführungszeichen, geschweiften Klammern, eckigen Klammern und runden Klammern. Ausdrücke enthalten auch Funktionen und Zeichen wie Dollarzeichen, Kommas und Punkte.

name: 'storage${uniqueString(resourceGroup().id)}'

Wenn Sie diese Art von Fehler erhalten, überprüfen Sie die Ausdruckssyntax. Verwenden Sie zum Identifizieren von Vorlagenfehlern Visual Studio Code mit der neuesten Bicep-Erweiterung oder Azure Resource Manager-Tools-Erweiterung.

Lösung 2: Falsche Segmentlängen

Ein weiterer Fehler vom Typ „Ungültige Vorlage“ tritt auf, wenn der Ressourcenname nicht im richtigen Format vorliegt. Informationen zum Beheben dieses Fehlers finden Sie unter Beheben von Fehlern bei nicht übereinstimmenden Namen und Typen.

Lösung 3: Parameter ungültig

Sie können die zulässigen Werte eines Parameters in einer Vorlage angeben. Wenn Sie bei der Bereitstellung einen Wert angeben, der keinem der zulässigen Werte entspricht, erhalten Sie eine Fehlermeldung der folgenden Art:

Code=InvalidTemplate;
Message=Deployment template validation failed: 'The provided value {parameter value}
for the template parameter {parameter name} is not valid. The parameter value is not
part of the allowed values

Überprüfen Sie die Vorlage auf die zulässigen Werte des Parameters, und verwenden Sie während der Bereitstellung einen zulässigen Wert. Weitere Informationen finden Sie unter zulässige Werte in Bicep oder ARM-Vorlagen.

Lösung 4: Zu viele Zielressourcengruppen

Dieser Fehler wird in früheren Bereitstellungen möglicherweise angezeigt, weil in einer einzigen Bereitstellung nur fünf Zielressourcengruppen vorhanden sein durften. Im Mai 2020 wurde dieses Limit auf 800 Ressourcengruppen erhöht. Weitere Informationen finden Sie unter Bereitstellen für mehrere Ressourcengruppen in Bicep oder ARM-Vorlagen.

Lösung 5: Ringabhängigkeit erkannt

Sie erhalten diesen Fehler, wenn Ressourcen auf eine Weise voneinander abhängig sind, die das Starten der Bereitstellung verhindert. Eine Kombination aus gegenseitigen Abhängigkeiten bewirkt, dass zwei oder mehr Ressourcen auf andere Ressourcen warten, die sich ebenfalls im Wartezustand befinden. Beispielsweise hängt resource1 von resource3 ab, resource2 hängt von resource1 ab, und resource3 hängt von resource2 ab. Dieses Problem lässt sich normalerweise beheben, indem nicht benötigte Abhängigkeiten entfernt werden.

Bicep erstellt eine implizite Abhängigkeit, wenn eine Ressource den symbolischen Namen einer anderen Ressource verwendet. Eine explizite Abhängigkeit mit dependsOn ist in der Regel nicht erforderlich. Weitere Informationen finden Sie unter Bicep-Abhängigkeiten.

So beheben Sie eine Ringabhängigkeit

  1. Suchen Sie in Ihrer Vorlage nach der Ressource, die in der Ringabhängigkeit angegeben ist.
  2. Untersuchen Sie für diese Ressource die dependsOn-Eigenschaft und alle Verwendungen der Funktionen reference und resourceId, um zu ermitteln, von welchen Ressourcen sie abhängig ist.
  3. Überprüfen Sie diese Ressourcen, um zu ermitteln, von welchen Ressourcen sie abhängig sind. Verfolgen Sie die Abhängigkeiten, bis Sie auf eine Ressource stoßen, die von der Originalressource abhängig ist.
  4. Überprüfen Sie für die an der Ringabhängigkeit beteiligten Ressourcen gründlich alle Vorkommen der dependsOn-Eigenschaft, um alle Abhängigkeiten zu identifizieren, die nicht benötigt werden. Entfernen Sie zur Problembehandlung der Bereitstellung die Ringabhängigkeiten. Anstatt den Code zu löschen, können Sie Kommentare verwenden, damit der Code während der nächsten Bereitstellung nicht ausgeführt wird. Sie können einzeilige Kommentare (//) oder mehrzeilige Kommentare (/* ... */) in ARM-Vorlagen oder Bicep-Dateien verwenden.
  5. Stellen Sie die Vorlage erneut bereit.

Das Entfernen von Werten aus der dependsOn-Eigenschaft kann zu Fehlern beim Bereitstellen der Vorlage führen. Fügen Sie die Abhängigkeit wieder in die Vorlage ein, wenn ein Fehler auftritt. Wenn Sie Kommentare verwendet haben, um Code in Ihrer Vorlage zu umgehen, können Sie die Kommentare entfernen, um den Code wiederherzustellen.

Falls sich die Ringabhängigkeit mit dieser Vorgehensweise nicht beseitigen lässt, können Sie erwägen, einen Teil Ihrer Bereitstellungslogik in untergeordnete Ressourcen zu verschieben (z.B. Erweiterungen oder Konfigurationseinstellungen). Konfigurieren Sie diese untergeordneten Ressourcen so, dass sie nach den an der Ringabhängigkeit beteiligten Ressourcen bereitgestellt werden. Nehmen wir beispielsweise an, Sie stellen zwei virtuelle Computer bereit, müssen aber Eigenschaften festlegen, die auf den jeweils anderen verweisen. Sie können diese in der folgenden Reihenfolge bereitstellen:

  1. VM1
  2. VM2
  3. Die Erweiterung auf VM1 hängt von VM1 und VM2 ab. Die Erweiterung legt Werte auf VM1 fest, die sie von VM2 abruft.
  4. Die Erweiterung auf VM2 hängt von VM1 und VM2 ab. Die Erweiterung legt Werte auf VM2 fest, die sie von VM1 abruft.

Diese Vorgehensweise funktioniert auch für App Service-Apps. Erwägen Sie, Konfigurationswerte in eine untergeordnete Ressource der App-Ressource zu verschieben. Sie können zwei Web-Apps in der folgenden Reihenfolge bereitstellen:

  1. webapp1
  2. webapp2
  3. Die Konfiguration für „webapp1“ ist von „webapp1“ und „webapp2“ abhängig. Sie enthält App-Einstellungen mit Werten aus „webapp2“.
  4. Die Konfiguration für „webapp2“ ist von „webapp1“ und „webapp2“ abhängig. Sie enthält App-Einstellungen mit Werten aus „webapp1“.

Lösung 6: Syntax für exportierte Vorlagen überprüfen

Nachdem Sie Ressourcen in Azure bereitgestellt haben, können Sie den JSON-Code der ARM-Vorlage exportieren und für andere Bereitstellungen ändern. Sie sollten die exportierte Vorlage auf die richtige Syntax überprüfen, bevor Sie sie zum Bereitstellen von Ressourcen verwenden.

Sie können eine Vorlage über das Portal, Azure CLI oder Azure PowerShell exportieren. Unabhängig davon, ob Sie die Vorlage aus der Ressource oder Ressourcengruppe oder aus dem Bereitstellungsverlauf exportiert haben, gibt es Empfehlungen.

Nachdem Sie eine ARM-Vorlage exportiert haben, können Sie die JSON-Vorlage in Bicep dekompilieren. Verwenden Sie dann die bewährten Methoden und den Linter, um Ihren Code zu überprüfen.

Weitere Informationen finden Sie in den folgenden Artikeln: