Übersicht über den Terraform AzAPI-Anbieter

Artikel
08/22/2024

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

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:

Ressourcenname	Beschreibung
azapi_resource	Wird verwendet, um alle Azure-Ressourcen (Steuerebene) (API) mit vollständigem CRUD vollständig zu verwalten. Beispiele für Anwendungsfälle: Neuer Vorschaudienst Neues Feature zum vorhandenen Dienst hinzugefügt Vorhandene Features/Dienste, die derzeit nicht abgedeckt sind
azapi_update_resource	Wird verwendet, um Ressourcen oder Teile von Ressourcen zu verwalten, die nicht über vollständiges CRUD verfügen Beispiele für Anwendungsfälle: Aktualisieren neuer Eigenschaften für einen vorhandenen Dienst Aktualisieren Sie die zuvor erstellte untergeordnete Ressource – z. B. DNS-SOA-Eintrag.
azapi_resource_action	Wird verwendet, um einen einzelnen Vorgang für eine Ressource auszuführen, ohne den Lebenszyklus zu verwalten Beispiele für Anwendungsfälle: Herunterfahren eines virtuellen Computers Hinzufügen eines Geheimnisses zu einem Key Vault
azapi_data_plane_resource	Dient zum Verwalten einer bestimmten Teilmenge von Azure-Datenebenenressourcen Beispiele für Anwendungsfälle: KeyVault-Zertifikatkontakte Synapse-Arbeitsbereichsbibliotheken

Verwendungshierarchie

Insgesamt sollte die Nutzung anhand der folgenden Schritte erfolgen:

Es wird immer empfohlen, mit der Ausführung möglichst vieler Vorgänge innerhalb von azapi_resource zu beginnen.
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.
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.
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 Ressource, die derzeit nicht im AzureRM-Anbieter vorhanden ist:

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"
        }
      }
    }
  }
}

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.

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
- Speicherung von Eigenschaften und Werten im Zustand
Keine Abhängigkeit von Swagger
Allgemeine und konsistente Azure-Authentifizierung
Robuste VS Code-Erweiterung

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 AzAPI VS Code-Erweiterung bietet eine umfangreiche Erstellungserfahrung mit den folgenden Vorteilen:

Auflisten aller verfügbaren Ressourcentypen und API-Versionen
Automatische Fertigstellung der zulässigen Eigenschaften und Werte für jede Ressource
Anzeigen von Hinweisen beim Bewegen der Maus über eine Eigenschaft
Syntaxüberprüfung
Automatische Fertigstellung mit Codebeispielen

AzAPI2AzureRM-Migrationstool

Der AzureRM-Anbieter bietet die am besten integrierte Terraform-Erfahrung für die Verwaltung von Azure-Ressourcen. Daher lautet die empfohlene Verwendung der AzAPI- und AzureRM-Anbieter wie folgt:

Verwenden Sie den AzAPI-Anbieter, während sich der Dienst oder die Funktion in der Vorschau befindet.
Nachdem der Dienst offiziell veröffentlicht wurde, verwenden Sie den AzureRM-Anbieter.

Das AzAPI2AzureRM-Tool wurde entwickelt, um die Migration vom AzAPI-Anbieter zum AzureRM-Anbieter zu unterstützen.

AzAPI2AzureRM ist ein Open-Source-Tool, das das Konvertieren von AzAPI-Ressourcen in AzureRM-Ressourcen automatisiert.

AzAPI2AzureRM 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

AzAPI2AzureRM stellt nach der Migration sicher, dass Ihre Terraform-Konfiguration und Ihr Status mit Ihrem tatsächlichen Status übereinstimmen. Sie können die Statusaktualisierung validieren, indem Sie nach Abschluss der Migration terraform plan ausführen, um zu sehen, dass sich nichts geändert hat.

Verwenden des AzAPI-Anbieters

Installieren der VS Code-Erweiterung

Fügen Sie den AzAPI-Anbieter zu Ihrer Terraform-Konfiguration hinzu.

terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
    }
  }
}

provider "azapi" {
  # More information on the authentication methods supported by
  # the AzureRM Provider can be found here:
  # https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs

  # subscription_id = "..."
  # client_id       = "..."
  # client_secret   = "..."
  # tenant_id       = "..."
}

Deklarieren Sie eine oder mehrere AzAPI-Ressourcen wie im folgenden Beispielcode dargestellt:

resource "azapi_resource" "example" {
  name = "example"
  parent_id = data.azurerm_machine_learning_workspace.existing.id
  type = "Microsoft.MachineLearningServices/workspaces/computes@2021-07-01"

  location = "eastus"
  body = {
    properties = {
      computeType      = "ComputeInstance"
      disableLocalAuth = true
      properties = {
        vmSize = "STANDARD_NC6"
      }
    }
  }
}

Freigeben über