Preflight-Validierung im AzAPI Terraform-Anbieter aktivieren

Terraform ermöglicht die Definition, Vorschau und Bereitstellung der Cloudinfrastruktur. Mithilfe von Terraform erstellen Sie Konfigurationsdateien mit der HCL-Syntax. Mit der HCL-Syntax können Sie den Cloudanbieter ( z. B. Azure ) und die Elemente angeben, aus denen Ihre Cloudinfrastruktur besteht. Nach der Erstellung Ihrer Konfigurationsdateien erstellen Sie einen Ausführungsplan, mit dem Sie eine Vorschau Ihrer Infrastrukturänderungen anzeigen können, bevor diese bereitgestellt werden. Nachdem Sie die Änderungen überprüft haben, wenden Sie den Ausführungsplan an, um die Infrastruktur bereitzustellen.

Der AzAPI Terraform-Anbieter enthält eine integrierte Preflight-Überprüfung, die Ihre Azure-Ressourcenkonfiguration während des terraform plan-Vorgangs gegen das ARM-API-Schema überprüft, bevor Ressourcen in Azure erstellt oder geändert werden. Preflight fängt Konfigurationsfehler frühzeitig ab – z. B. ungültige Adresspräfixe, nicht unterstützte Eigenschaftenkombinationen oder Kontingentverletzungen – ohne dass die Kosten für eine fehlgeschlagene Bereitstellung entstehen.

Die Preflight-Validierung ist einer der wichtigsten Unterscheidungsmerkmale von AzAPI und arbeitet nativ mit der Direct-to-ARM-API-Architektur des Anbieters zusammen. Sie können preflight auch über die Microsoft Terraform VS Code Extension ausführen, ohne die Anbieterkennzeichnung direkt festzulegen.

Voraussetzungen

• Azure-Abonnement: Wenn Sie nicht über ein Azure-Abonnement verfügen, erstellen Sie ein kostenloses Konto , bevor Sie beginnen.

• Terraform konfigurieren: Wenn Sie dies noch nicht getan haben, konfigurieren Sie Terraform mit einer der folgenden Optionen:

  • Konfigurieren von Terraform in Azure Cloud Shell mit Bash
  • Konfigurieren von Terraform in Azure Cloud Shell mit PowerShell
  • Konfigurieren von Terraform in Windows mit Bash
  • Terraform in Windows mit PowerShell konfigurieren

Wenn Sie sich mit einem Microsoft-Konto beim Azure-Portal anmelden, wird das Azure-Standardabonnement für dieses Konto verwendet.

Terraform authentifiziert sich automatisch mithilfe von Informationen aus dem Azure-Standardabonnement.

Führen Sie az account show aus , um das aktuelle Microsoft-Konto und das Azure-Abonnement zu überprüfen.

az account show

Alle Änderungen, die Sie über Terraform vornehmen, befinden sich im angezeigten Azure-Abonnement. Wenn Sie dies wünschen, überspringen Sie den Rest dieses Artikels.

Aktivieren der Preflight-Überprüfung

Legen Sie enable_preflight = true im provider "azapi" Bereich fest:

provider "azapi" {
  enable_preflight = true
}

Preflight ist standardmäßig deaktiviert, um die Abwärtskompatibilität beizubehalten. Aktivieren Sie sie in Umgebungen, in denen Sie eine frühe Überprüfung wünschen, z. B. CI-Pipelines und Pullanforderungsprüfungen.

Beispiel: Erfassen eines ungültigen Adresspräfixes zur Planzeit

Mit der folgenden Konfiguration wird ein virtuelles Netzwerk mit einem ungültigen CIDR-Block (Classless Inter-Domain Routing) erstellt. Wenn Preflight aktiviert ist, tritt der Fehler während terraform plan auf, statt während terraform apply.

terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

provider "azapi" {
  enable_preflight = true
}

resource "azurerm_resource_group" "example" {
  name     = "rg-preflight-demo"
  location = "eastus"
}

resource "azapi_resource" "vnet" {
  type      = "Microsoft.Network/virtualNetworks@2024-01-01"
  parent_id = azurerm_resource_group.example.id
  name      = "vnet-example"
  location  = "eastus"

  body = {
    properties = {
      addressSpace = {
        addressPrefixes = [
          "10.0.0.0/160"  # Invalid prefix length — preflight catches this at plan time
        ]
      }
    }
  }
}

Wenn Sie terraform plan mit dieser Konfiguration ausführen, gibt Preflight einen ähnlichen Fehler wie den folgenden zurück.

Error: preflight validation failed for resource "azapi_resource.vnet":
  The value '10.0.0.0/160' is not a valid CIDR block.

Durch korrigieren des Adresspräfixes auf einen gültigen Wert (z. B 10.0.0.0/16. ) wird der Fehler gelöscht.

Was Preflight validiert

Preflight sendet den Ressourcentext an den Preflight-Endpunkt der ARM-API, der Folgendes überprüft:

• Eigenschaftswerte für das ARM-Ressourcenschema (z. B. gültige CIDR(Classless Inter-Domain Routing)-Bereiche, zulässige SKU-Namen, Pflichtfelder).
• Kontingent und Kapazitätsbeschränkungen auf Abonnementebene für unterstützte Ressourcentypen.
• Richtlinienkonformität für Azure-Richtlinienzuweisungen, die im Preflight-Modus ausgeführt werden.

Preflight überprüft nicht :

• Ressourcenübergreifende Abhängigkeiten oder Sequenzierung.
• Ressourcen ohne ARM-Preflight-Endpunktunterstützung (der Anbieter überspringt stillschweigend die Überprüfung für diese Ressourcentypen).
• Authentifizierungs- oder Autorisierungsfehler (Identity and Access Management, IAM) – diese Fehler treten während terraform apply auf.

Verwendung von Preflight in CI-Pipelines

Das Hinzufügen von Preflight zu einer CI-Pipeline bietet einen schnellen, nicht destruktiven Überprüfungsschritt, der Konfigurationsfehler abfangen kann, bevor Code zusammengeführt wird. Aktivieren Sie enable_preflight = true im Anbieterblock Ihrer Terraform-Konfiguration, und führen Sie dann terraform plan aus:

provider "azapi" {
  enable_preflight = true
}

Da Preflight während terraform plan ohne Nebenwirkungen ausgeführt wird, können Sie es gefahrlos in Pull-Request-Workflows gegen Live-Azure-Abonnements ausführen.

Deaktivieren Sie das Ausgaberauschen mit ignore_no_op_changes

Wenn Sie Pläne wiederholt ausführen, erkennt AzAPI möglicherweise kleinere no-op Unterschiede zwischen der Konfiguration und dem ARM-Zustand (z. B. normalisierte Standardwerte, die von der API zurückgegeben werden). Um diese Planzeitunterschiede zu unterdrücken und sich auf echte Änderungen zu konzentrieren, setzen Sie ignore_no_op_changes = true im Provider-Block fest:

provider "azapi" {
  enable_preflight      = true
  ignore_no_op_changes  = true
}

Nächste Schritte