Linten und Überprüfen des Bicep-Codes

  • 5 Minuten

Nachdem Sie den Zweck der einzelnen Workflowaufträge kennengelernt haben, erhalten Sie nun Informationen zu den ersten Überprüfungsschritten, die Sie Ihrem Bicep-Bereitstellungsworkflow hinzufügen können. In dieser Lerneinheit erfahren Sie, wie Sie Bicep-Vorlagen überprüfen. Außerdem erfahren Sie mehr über die beiden gängigsten Überprüfungsaktivitäten: Linting und Preflightvalidierung.

Wie sieht eine gültige Bicep-Datei aus?

Eine gültige Bicep-Datei darf keine Syntaxfehler enthalten. Außerdem sind die Definitionen für die Azure-Ressourcen gültig, die Sie bereitstellen möchten. Wenn die in der Datei definierten Ressourcen bereitgestellt werden, bleiben sie innerhalb der Kontingente und Grenzwerte Ihres Azure-Abonnements.

Einige der Überprüfungen werden für Ihre Bicep-Datei isoliert ausgeführt, wie etwa die Überprüfungen auf Syntaxfehler, gültige Azure-Ressourcendefinitionen und Codequalität. Diese Schritte sind Teil des sogenannten Linting-Prozesses. Für die Suche nach weiteren Problemen müssen Sie die Überprüfung Ihrer Vorlage unter Berücksichtigung Ihrer Azure-Umgebung durch den Azure Resource Manager-Dienst anfordern.

Für eine gültige Bicep-Vorlage ist die Wahrscheinlichkeit einer erfolgreichen Bereitstellung höher. Sie erhalten Feedback, ohne Ihre Bicep-Vorlage tatsächlich bereitstellen zu müssen. Überprüfen ist eine bewährte Methode, da Azure beim Bereitstellen einer ungültigen Bicep-Datei möglicherweise nur eine Teilmenge der in Ihrer Vorlage beschriebenen Ressourcen bereitstellt oder ändert. Durch eine teilweise Bereitstellung könnte Ihre Umgebung inkonsistent werden und sich eventuell anders verhalten, als erwartet.

Erstellen und Linten des Bicep-Codes

Wenn Sie eine Bicep-Datei bereitstellen, führen die Bicep-Tools zunächst einige grundlegende Überprüfungsschritte aus. Dabei handelt es sich um dieselben Schritte, die auch bei einer Änderung der Datei mithilfe von Visual Studio Code ausgeführt werden. Es wird überprüft, ob Sie die Schlüsselwörter der Bicep-Sprache richtig verwendet und Ihre Azure-Ressourcen gemäß den Anforderungen für die einzelnen Ressourcentypen definiert haben.

Darüber hinaus führt Bicep für Ihre Dateien einen Linter aus. Dieser überprüft Ihren Code anhand einer Reihe von Empfehlungen. Der Bicep-Linter überprüft, ob Sie für Ihre Datei die bewährten Methoden bezüglich der Wartbarkeit, Richtigkeit, Flexibilität und Erweiterbarkeit befolgt haben.

Ein Linter enthält vordefinierte Regeln für jede dieser Kategorien. Beispiele für Linterregeln:

  • Nicht verwendete Parameter: Der Linter sucht nach Parametern, die in der gesamten Bicep-Datei nicht verwendet werden. Durch das Entfernen nicht verwendeter Parameter vereinfachen Sie die Bereitstellung Ihrer Vorlage, da Sie keine unnötigen Werte angeben müssen. Zudem vermeiden Sie Verwirrung, wenn andere Personen mit Ihrer Bicep-Datei arbeiten möchten.
  • Zeichenfolgeninterpolation: Der Linter überprüft, ob Ihre Datei die Funktion concat() anstelle der Bicep-Zeichenfolgeninterpolation verwendet. Die Zeichenfolgeninterpolation erhöht die Lesbarkeit Ihrer Bicep-Dateien.
  • Standardwerte für sichere Parameter: Der Linter warnt Sie, wenn Sie Standardwerte für Parameter festlegen, die mit dem Decorator @secure() markiert sind. Standardwerte für einen sicheren Parameter festzulegen ist deshalb nicht empfehlenswert, da der sichere Parameter dadurch einen für Menschen lesbaren Wert erhält, und Benutzer*innen ihn möglicherweise vor der Bereitstellung nicht ändern.

Der Bicep-Linter wird automatisch ausgeführt, wenn Sie die Bicep-Tools verwenden. Jede Bicep-Datei, die Sie erstellen, wird vom Linter anhand der bewährten Methoden überprüft. Diese Überprüfung läuft beim Bereitstellen einer Bicep-Datei in Azure automatisch ab.

In einem Workflow sollten jedoch die Überprüfungs- und Lintingschritte in der Regel vor der Bereitstellung der Datei ausgeführt werden. Sie können die Datei von Bicep überprüfen lassen, indem Sie die Bicep-Datei manuell über die Bicep-CLI erstellen:

az bicep build --file main.bicep

bicep build main.bicep

Hinweis

Wenn Sie den Befehl build ausführen, transpiliert Bicep Ihren Bicep-Code auch in eine JSON-ARM-Vorlage. Sie können die dabei ausgegebene Datei ignorieren, da Sie sie in der Regel nicht benötigen.

Da Ihre Bicep-Vorlagen bei jedem Einchecken von Code in Ihr Repository gelintet werden sollen, können Sie Ihrem Workflow einen Lintingauftrag hinzufügen:

Diagramm eines Workflows mit einem Lintingauftrag, der einen einzelnen Auftrag zum Ausführen des Linters für die Datei enthält

Sie können diese Ergänzung in Ihrer YAML-Workflowdatei auf folgende Weise ausdrücken:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - script: |
        az bicep build --file deploy/main.bicep

Linterwarnungen und -fehler

Standardmäßig gibt der Linter eine Warnung aus, wenn er in einer Bicep-Datei einen Regelverstoß feststellt. Warnungen, die vom Bicep-Linter ausgegeben werden, werden nicht als Fehler behandelt, sodass die Ausführung des Workflows oder nachfolgender Aufträge nicht beendet wird.

Wenn Sie möchten, dass Verstöße gegen Linterregeln als Fehler und nicht als Warnungen behandelt werden, können Sie dieses Verhalten ändern. Fügen Sie für diese Konfiguration dem Ordner, der Ihre Bicep-Datei enthält, die Datei bicepconfig.json hinzu. Sie können entscheiden, welche Linterprobleme als Fehler behandelt und welche weiterhin als Warnungen ausgegeben werden sollen. Sie konfigurieren den Linter später in diesem Modul.

Tipp

Mit der Datei bicepconfig.json wird auch gesteuert, wie Visual Studio Code-Fehler und -Warnungen im Editor angezeigt werden. Falsch konfigurierte Teile in Ihrer Bicep-Vorlage werden mit roten und gelben Wellenlinien markiert. Durch diese Indikatoren erhalten Sie beim Schreiben des Bicep-Codes noch schnelleres Feedback, wodurch die Fehlerwahrscheinlichkeit weiter verringert wird.

Nachdem Sie den Linter für die Ausgabe von Fehlern neu konfiguriert haben, wird Ihr Workflow bei jedem vom Linter erkannten Problem beendet, und nachfolgende Aufträge werden nicht ausgeführt. Mit dieser Konfiguration stellen Sie sicher, dass kein problematischer Bicep-Code bereitgestellt wird.

Preflight-Überprüfung

Sie sollten auch überprüfen, ob eine erfolgreiche Bereitstellung der Bicep-Vorlage in Ihrer Azure-Umgebung wahrscheinlich ist. Dieser Prozess wird Preflightüberprüfung genannt. Dabei werden Überprüfungen ausgeführt, für die Azure Informationen bereitstellen muss. Dazu zählen folgende Überprüfungen:

  • Sind die Namen gültig, die Sie für Ihre Bicep-Ressourcen angegeben haben?
  • Sind die Namen, die Sie für Ihre Bicep-Ressourcen angegeben haben, bereits vergeben?
  • Sind die Regionen gültig, in denen Sie Ihre Ressourcen bereitstellen?

Für die Preflight-Überprüfung ist eine Kommunikation mit Azure erforderlich, doch es werden keine Ressourcen bereitgestellt.

Diagramm: Workflow mit Linting- und Überprüfungsaufträgen, die jeweils einen Auftrag enthalten Der überprüfte Auftrag kommuniziert mit Azure.

Verwenden Sie die Aktion arm-deploy, und legen Sie deploymentMode auf Validate fest, um eine Bicep-Datei für die Preflightvalidierung zu übermitteln:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      name: Run preflight validation
      with:
        resourceGroupName: ${{ env.AZURE_RESOURCEGROUP_NAME }}
        template: ./deploy/main.bicep
        deploymentMode: Validate

Sie können auch den Befehl az deployment group validate an der Azure-Befehlszeilenschnittstelle verwenden.

Die Preflightvalidierung ähnelt einer normalen Bereitstellung, ohne dass tatsächlich Ressourcen bereitgestellt werden. Es werden zusätzliche Überprüfungen der Ressourcen durchgeführt, die in Ihrer Vorlage verwendet werden.

Angenommen, Ihre Bicep-Datei enthält ein Speicherkonto. In der Vorabüberprüfung wird geprüft, ob der von Ihnen gewählte Namen bereits von einem anderen Speicherkonto verwendet wird. Es wird außerdem überprüft, ob der von Ihnen für das Speicherkonto gewählte Name den Namenskonventionen entspricht.

Mit dem Befehl für die Preflight-Überprüfung wird auch der Bicep-Linter ausgeführt. Es ist jedoch in der Regel ratsam, den Linter separat auszuführen. Auf diese Weise werden mögliche Linterfehler schnell erkannt, und Sie müssen nicht auf den Abschluss des Überprüfungsvorgangs warten. Die Überprüfung dauert länger.

Wichtig

Bei einer Preflightüberprüfung führt jeder Azure-Ressourcenanbieter eigene Überprüfungen durch. Einige Ressourcenanbieter führen nicht viele Überprüfungen durch, andere hingegen schon. Sie können sich also nicht nur auf die Preflightvalidierung verlassen, um sicherzugehen, dass Ihre Datei gültig ist. Trotzdem stellt sie ein nützliches Tool dar und sollte in Ihren Workflow eingeschlossen werden.

Wenn Sie Ihrem Workflow Überprüfungsaufträge hinzufügen, um den Linter auszuführen und eine Preflightvalidierung durchzuführen, können Sie Ihre Bicep-Datei unbesorgter bereitstellen.