Übersicht über den Terraform AzAPI-Anbieter

Der AzAPI-Anbieter ist eine dünne Schicht über den Azure ARM REST-APIs. Sie können jeden Azure Ressourcentyp mithilfe einer beliebigen API-Version verwalten, sodass Sie die neuesten Funktionen innerhalb Azure verwenden können. AzAPI ist ein erstklassiger Anbieter, der eigenständig oder zusammen mit dem AzureRM-Anbieter verwendet werden soll.

Vorteile der Verwendung des AzAPI-Anbieters

Der AzAPI-Anbieter bietet die folgenden Vorteile:

• Unterstützt alle Azure-Steuerungsebenendienste:
  • Vorschau der Dienste und Funktionen
  • Alle API-Versionen
• Terraform-Zustandsdatei mit vollständiger Genauigkeit
  • Eigenschaften und Werte werden im Zustand gespeichert
• Keine Abhängigkeit von Swagger
• Allgemeine und konsistente Azure-Authentifizierung
• Integrierte Preflight-Überprüfung
• Detaillierte Kontrolle über die Infrastrukturentwicklung
• Microsoft Terraform Visual Studio Code Erweiterung

Ressourcen

Damit Sie alle Azure-Ressourcen und -Features verwalten können, ohne dass Updates erforderlich sind, enthält der AzAPI-Anbieter die folgenden generischen Ressourcen:

Eine ausführliche Erläuterung der Funktionsweise des Datenebenenframeworks und wie parent_id sich von Steuerungsebenenressourcen unterscheidet, finden Sie unter das AzAPI-Datenebenenframework verstehen.

Verwendungshierarchie

Insgesamt sollte die Nutzung anhand der folgenden Schritte erfolgen:

1. Beginnen Sie mit der Durchführung so vieler Vorgänge wie möglich innerhalb azapi_resource.
2. Wenn der Ressourcentyp nicht in azapi_resource vorhanden ist, aber zu einem der von azapi_data_plane_resource unterstützten Typen gehört, verwenden Sie stattdessen diesen.
3. Wenn die Ressource bereits in AzureRM vorhanden ist oder über eine Eigenschaft verfügt, auf die in azapi_resource nicht zugegriffen werden kann, verwenden Sie azapi_update_resource, um auf diese spezifischen Eigenschaften zuzugreifen. Ressourcen, die azapi_resource oder azapi_data_plane_resource nicht unterstützen, können nicht über diese Ressource aktualisiert werden.
4. Wenn Sie versuchen, eine Aktion auszuführen, die nicht auf einer Azure CRUD-freundlichen Ressource basiert, ist azapi_resource_action weniger direkt als azapi_update_resource, aber flexibler.

Beispiele für die Ressourcenkonfiguration

Der folgende Codeausschnitt konfiguriert eine Azure Ressource direkt über die ARM-API:

resource "azapi_resource" "publicip" {
  type      = "Microsoft.Network/Customipprefixes@2021-03-01"
  name      = "exfullrange"
  parent_id = azurerm_resource_group.example.id
  location  = "westus2"

  body = {
    properties = {
      cidr          = "10.0.0.0/24"
      signedMessage = "Sample Message for WAN"
    }
  }
}

Der folgende Codeausschnitt konfiguriert eine Vorschaueigenschaft für eine vorhandene Ressource aus AzureRM:

resource "azapi_update_resource" "test" {
  type        = "Microsoft.ContainerRegistry/registries@2020-11-01-preview"
  resource_id = azurerm_container_registry.acr.id

  body = {
    properties = {
      anonymousPullEnabled = var.bool_anonymous_pull
    }
  }
}

Der folgende Codeausschnitt konfiguriert eine Ressourcenaktion für eine vorhandene AzureRM-Ressource:

resource "azapi_resource_action" "vm_shutdown" {
  type = "Microsoft.Compute/virtualMachines@2023-07-01"
  resource_id = azurerm_linux_virtual_machine.example.id
  action = "powerOff”
}

Der folgende Codeausschnitt konfiguriert eine Ressource, die derzeit nicht im AzureRM-Anbieter vorhanden ist, da sie auf der Datenebene bereitgestellt wird:

resource "azapi_data_plane_resource" "dataset" {
  type      = "Microsoft.Synapse/workspaces/datasets@2020-12-01"
  parent_id = trimprefix(data.azurerm_synapse_workspace.example.connectivity_endpoints.dev, "https://")
  name      = "example-dataset"
  body = {
    properties = {
      type = "AzureBlob",
      typeProperties = {
        folderPath = {
          value = "@dataset().MyFolderPath"
          type  = "Expression"
        }
        fileName = {
          value = "@dataset().MyFileName"
          type  = "Expression"
        }
        format = {
          type = "TextFormat"
        }
      }
      parameters = {
        MyFolderPath = {
          type = "String"
        }
        MyFileName = {
          type = "String"
        }
      }
    }
  }
}

Beispiel für die Preflight-Verwendung

Der folgende Codeausschnitt verursacht während terraform plan einen Fehler aufgrund der integrierten Vorabüberprüfung von AzAPI.

provider "azapi" {
  enable_preflight = true
}
resource "azapi_resource" "vnet" {
  type      = "Microsoft.Network/virtualNetworks@2024-01-01"
  parent_id = azapi_resource.resourceGroup.id
  name      = "example-vnet"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = [
          "10.0.0.0/160", # preflight will throw an error here
        ]
      }
    }
  }
}

Wenn diese Option aktiviert ist, werden Konfigurationsfehler während des Preflight statt zum Zeitpunkt der Anwendung angezeigt.

Datenquellen

Der AzAPI-Anbieter unterstützt verschiedene nützliche Datenquellen:

Ein praktisches Beispiel zur Verwendung von azapi_resource_list mit JMESPath-Filterung finden Sie in Azure-Ressourcen mit dem AzAPI Terraform-Anbieter auflisten.

Lesen einer vorhandenen Ressource mit azapi_resource Datenquelle

Die azapi_resource-Datenquelle liest den aktuellen Status einer beliebigen Azure Ressource und macht ihre Eigenschaften über das Attribut output verfügbar. Verwenden Sie sie, wenn Sie eine Eigenschaft benötigen, die der AzureRM-Anbieter nicht verfügbar macht:

data "azapi_resource" "aks" {
  type      = "Microsoft.ContainerService/managedClusters@2024-02-01"
  resource_id = azurerm_kubernetes_cluster.example.id

  # Extract the OIDC issuer URL, not exposed by azurerm_kubernetes_cluster
  response_export_values = ["properties.oidcIssuerProfile.issuerURL"]
}

output "oidc_issuer_url" {
  value = data.azapi_resource.aks.output.properties.oidcIssuerProfile.issuerURL
}

Verwenden Sie response_export_values und JMESPath

response_export_values steuert, welche Eigenschaften aus der unformatierten ARM-API-Antwort extrahiert und im output Attribut verfügbar gemacht werden. Sie akzeptiert eine Liste oder eine Karte:

• Liste: Geben Sie json-Eigenschaftspfade an, die extrahiert werden sollen. Wird ["*"] verwendet, um den vollständigen Antworttext zu exportieren.
• Map: Verwenden Sie JMESPath-Ausdrücke, um die Antwort zu filtern und neu zu gestalten. Der Schlüssel ist der Name des Ausgabefelds; der Wert ist die JMESPath-Abfrage.

Das Kartenformular wird für Listenantworten und Fälle bevorzugt, in denen Sie die Ausgabe transformieren müssen:

data "azapi_resource_list" "storage_accounts" {
  type      = "Microsoft.Storage/storageAccounts@2023-01-01"
  parent_id = azurerm_resource_group.example.id

  response_export_values = {
    "names"     = "value[].name"
    "locations" = "value[].location"
  }
}

Für eine vollständige exemplarische Vorgehensweise lesen Sie „Azure-Ressourcen mit dem AzAPI Terraform-Anbieter auflisten“.

Authentifizierung mithilfe des AzAPI-Anbieters

Der AzAPI-Anbieter ermöglicht die gleichen Authentifizierungsmethoden wie der AzureRM-Anbieter. Weitere Informationen zu Authentifizierungsoptionen finden Sie unter Authentifizieren von Terraform in Azure.

Erfahrung und Lebenszyklus des AzAPI-Anbieters

In diesem Abschnitt werden einige Tools beschrieben, die Ihnen bei der Verwendung des AzAPI-Anbieters helfen.

VS Code-Erweiterung und Sprachserver

Die Microsoft Terraform VS Code-Erweiterung bietet eine umfassende Erstellungserfahrung für azureRM- und AzAPI-Anbieter, darunter:

• Auflisten aller verfügbaren Ressourcentypen und API-Versionen
• Autovervollständigung der zulässigen Eigenschaften und Werte für eine Ressource.
• Anzeigen von Hinweisen beim Bewegen der Maus über eine Eigenschaft
• Syntaxüberprüfung
• AutoVervollständigen mit Codebeispielen.

Die Erweiterung unterstützt auch Paste-as-AzAPI (konvertiert ARM JSON in azapi_resource-Blöcke), Azure Ressourcenexport über aztfexport, AzureRM-to-AzAPI-Migration und Preflight-Validierung. Eine vollständige Anleitung finden Sie unter Use the Microsoft Terraform VS Code extension.

aztfmigrate Migrationstool

Das Tool aztfmigrate dient zum Migrieren vorhandener Ressourcen zwischen azAPI- und AzureRM-Anbietern.

aztfmigrate verfügt über zwei Modi: Planen und Migrieren:

• Plan zeigt die AzAPI-Ressourcen an, die migriert werden können.
• Migriert die AzAPI-Ressourcen sowohl in den HCL-Dateien als auch im Status zu AzureRM-Ressourcen

aztfmigrate stellt nach der Migration sicher, dass Ihre Terraform-Konfiguration und Ihr Zustand mit Ihrem tatsächlichen Zustand ausgerichtet sind. Sie können den Zustand des Updates überprüfen, indem Sie terraform plan ausführen, nachdem die Migration abgeschlossen ist, um zu bestätigen, dass keine Änderungen aufgetreten sind.

Eine schrittweise exemplarische Vorgehensweise finden Sie unter Migrieren von Ressourcen von AzAPI zu AzureRM.

Importieren vorhandener Azure-Ressourcen

Um eine vorhandene Azure Ressource ohne erneute Erstellung unter AzAPI-Verwaltung zu bringen, verwenden Sie den import-Block (Terraform 1.5 und höher) oder den Befehl terraform import. Die Ressourcen-ID muss die API-Version als Abfrageparameter enthalten:

import {
  to = azapi_resource.example
  id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Network/virtualNetworks/example-vnet?api-version=2023-11-01"
}

resource "azapi_resource" "example" {
  type      = "Microsoft.Network/virtualNetworks@2023-11-01"
  name      = "example-vnet"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = ["10.0.0.0/16"]
      }
    }
  }
}

Verwenden Sie Azure Export for Terraform (aztfexport), die sowohl die HCL-Konfiguration als auch die Importblöcke automatisch generiert, um mehrere Ressourcen gleichzeitig aus der vorhandenen Azure-Infrastruktur zu importieren.

Granulare Steuerungen über Infrastruktur

Ein großer Vorteil von AzAPI ist die Möglichkeit, Ihre Konfiguration so zu optimieren, dass sie den richtigen Entwurfsmustern entspricht. Dafür stehen verschiedene Möglichkeiten zur Verfügung:

Anbieterkonfigurationsoptionen

Der AzAPI-Anbieterblock akzeptiert mehrere Einstellungen, die global für alle Ressourcen in der Konfiguration gelten:

Eine vollständige Liste der Anbieterkonfigurationsoptionen finden Sie im AzAPI-Anbieterschema.

Eine exemplarische Vorgehensweise zum Aktivieren von Preflight finden Sie unter Aktivieren der Preflight-Validierung im AzAPI Terraform-Anbieter.

Anbieterfunktionen

AzAPI v2.0 und höher umfasst mehrere Anbieterfunktionen:

Benutzerdefinierte wiederholbare Fehler mit dem retry Block

Der AzAPI-Anbieter behandelt erwartete Fehler über den retry Block. Verwenden Sie z. B. die folgende Konfiguration, um es erneut zu versuchen, falls eine Ressource auf ein Timeout beim Erstellen stößt.

resource "azapi_resource" "example" {
    # usual properties
    retry {
        interval_seconds     = 5
        randomization_factor = 0.5 # adds randomization to retry pattern
        multiplier           = 2 # if try fails, multiplies time between next try by this much
        error_message_regex  = ["ResourceNotFound"]
    }
    timeouts {
        create = "10m"
}

Der retry Block akzeptiert diese Attribute:

Kombinieren Sie retry mit dem timeouts Block, um eine obere Grenze für die Gesamtdauer der Wiederholung festzulegen:

timeouts {
  create = "10m"
}

Kurzlebige Ressourcen und nur-schreibbare Eigenschaften

AzAPI v2.x unterstützt schreibgeschützte Argumente (Terraform 1.11 und höher) durch das sensitive_body Attribut für azapi_resource. Schreibgeschützte Eigenschaften werden an die ARM-API gesendet, werden aber nicht im Terraform-Zustand gespeichert, was für geheime Schlüssel und Anmeldeinformationen nützlich ist:

resource "azapi_resource" "example" {
  type      = "Microsoft.SomeService/resources@2024-01-01"
  name      = "example"
  parent_id = azurerm_resource_group.example.id

  body = {
    properties = {
      name = "example"
    }
  }

  # Write-only — not stored in state
  sensitive_body = {
    properties = {
      adminPassword = var.admin_password
    }
  }
}

Wird sensitive_body_version verwendet, um zu steuern, wann Schreib-Eigenschaften an die API erneut gesendet werden (z. B. beim Rotieren von Anmeldeinformationen).

Trigger für Ressourcen-Ersetzung

Mit dem AzAPI Anbieter können Sie Parameter für den Ressourcenaustausch konfigurieren.

replace_triggers_external_values

Ersetzt die Ressource, wenn sich ein Wert ändert. Wenn beispielsweise die SKU- oder Zonenvariablen geändert werden sollen, würde diese Ressource neu erstellt werden:

resource "azapi_resource" "example" {
  name      = var.name
  type      = "Microsoft.Network/publicIPAddresses@2023-11-01"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example"
  body      = properties = {
    sku   = var.sku
    zones = var.zones
  }
  replace_triggers_external_values = [
    var.sku,
    var.zones,
  ]
}

Dieser Auslöser funktioniert über einen breiten Satz von Ressourcen, z. B. eine Richtlinienzuweisung, wenn sich die Eigenschaften der Definition ändern.

replace_triggers_refs

Ersetzt die Ressource, wenn sich der referenzierte Wert ändert. Wenn beispielsweise der SKU-Name oder die Stufe geändert wurde, würde diese Ressource neu erstellt.

resource "azapi_resource" "example" {
  type      = "Microsoft.Relay/namespaces@2021-11-01"
  parent_id = azurerm_resource_group.example.id
  name      = "xxx"
  location  = "westus"
  body = {
    properties = {
    }
    sku = {
      name = "Standard"
      tier = "Standard"
    }
  }

  replace_triggers_refs = ["sku"]
}

Dies würde keine Ersetzung auslösen, wenn sich die SKU einer anderen Ressource ändert.

Nächste Schritte

• Wählen Sie zwischen AzureRM- und AzAPI Terraform-Anbietern
• Grundlegendes zum AzAPI-Datenebenenframework
• Bereitstellen Ihrer ersten Ressource mit dem AzAPI-Anbieter
• Bereitstellen Ihrer ersten Aktualisierungsressource mit dem AzAPI-Anbieter
• Bereitstellen Ihrer ersten Ressourcen-Aktion mit dem AzAPI-Anbieter
• Ausführen von Ressourcenaktionen mit dem AzAPI-Anbieter
• Manage Azure Datenebenenressourcen mit AzAPI
• Azure-Ressourcen mit dem AzAPI-Provider auflisten
• Aktivieren der Preflight-Überprüfung
• Verwenden von AzAPI-Anbieterfunktionen
• Migrationspfade zwischen Azure, AzureRM und AzAPI
• Besuchen Sie das Anbieterregister