Grundlegendes zum AzAPI-Datenebenenframework

Die meisten Azure Ressourcen werden über die Azure Resource Manager (ARM)-Steuerungsebene verwaltet – eine einzelne, einheitliche API-Oberfläche bei management.azure.com. Die Ressourcentypen azapi_resource, azapi_update_resource und azapi_resource_action zielen alle auf diese Steuerungsebene ab.

Einige Azure-Dienste stellen eine separate API für datenebene bereit– einen dienstspezifischen HTTPS-Endpunkt, in dem Sie direkt mit dem Dienst interagieren, anstatt über ARM. Beispiele sind die Key Vault Secrets-API unter {vaultName}.vault.azure.net, die Azure KI-Suche Index-API unter {searchServiceName}.search.windows.net und die Synapse-Arbeitsbereich-Pipeline-API unter {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource überbrücken diese Lücke, indem Terraform Ressourcen auf diesen Datenebenenendpunkten mithilfe desselben AzAPI-Anbieterauthentifizierungs- und Lebenszyklusmodells verwalten kann.

Warum nur ein kuratierter Satz von Ressourcentypen unterstützt wird

Im Gegensatz zu azapi_resource, die auf einen beliebigen ARM-Ressourcentyp abzielen können, funktioniert azapi_data_plane_resource nur mit einer specific-Liste der registrierten Ressourcentypen.

Diese Einschränkung besteht, da die Erweiterbarkeit von Datenebenen eine explizite Registrierung im Datenebenenframework des AzAPI-Anbieters erfordert. Das Framework muss folgendes wissen:

  • Das Basisendpunktmuster für einen Dienst (z. B {vaultName}.vault.azure.net. )
  • Der REST-Pfad für jeden unterstützten Ressourcentyp (z. B /secrets/{secret-name}. )
  • So authentifizieren Sie sich bei diesem Endpunkt (einige Dienste erfordern dienstspezifische Tokengruppen anstelle der Standard-ARM-Zielgruppe unter https://management.azure.com)

Jeder registrierte Ressourcentyp fügt diese Zuordnung dem Framework hinzu. Nicht registrierte Ressourcentypen können mit azapi_data_plane_resource nicht anvisiert werden, da der Anbieter keine Möglichkeit hat, den richtigen Endpunkt oder Authentifizierungsbereich zu ermitteln.

Tipp

Wenn ein benötigter Ressourcentyp für die Datenebene nicht unterstützt wird, können Sie ein Issue erstellen oder zu einer Registrierung im terraform-provider-azapi GitHub Repository beitragen.

Funktionsweise von parent_id für Datenebenenressourcen

Bei Steuerebene-Ressourcen (azapi_resource) handelt es sich bei parent_id immer um eine ARM-Ressourcen-ID – einen Pfad im Format /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}.

Für Datenebenenressourcen ist parent_id der Hostname der Datenebene des Dienstes, ohne das https://-Schema und nachfolgende Schrägstriche. Dieser Endpunkt ist in der Regel eine Eigenschaft, die nach der Erstellung auf der ARM-Steuerungsebene verfügbar gemacht wird.

Das Muster variiert je nach Dienst:

Service ARM-Ausgabeeigenschaft parent_id-Muster
Schlüsselspeicher (Key Vault) properties.vaultUri {vaultName}.vault.azure.net
Azure App-Konfiguration properties.endpoint {storeName}.azconfig.io
Azure KI-Suche abgeleitet aus dem Namen {searchServiceName}.search.windows.net
Synapse-Arbeitsbereich connectivityEndpoints.dev {workspaceName}.dev.azuresynapse.net
IoT Central-App properties.subdomain {appSubdomain}.azureiotcentral.com
Microsoft Purview (konstruiert aus dem Namen) {accountName}.purview.azure.com

Extrahieren von parent_id aus der ARM-Ausgabe

Verwenden Sie response_export_values auf der übergeordneten ARM-Ressource, um den Endpunkt des Datenverkehrs zu extrahieren, und entfernen Sie dann das Schema mit trimprefix oder replace:

resource "azurerm_key_vault" "example" {
  # ... configuration
}

resource "azapi_data_plane_resource" "secret" {
  type      = "Microsoft.KeyVault/vaults/secrets@7.4"
  # Strip "https://" and the trailing "/" from the vault URI
  parent_id = trimsuffix(trimprefix(azurerm_key_vault.example.vault_uri, "https://"), "/")
  name      = "my-secret"
  body = {
    value      = var.secret_value
    attributes = { enabled = true }
  }
}

Verwenden Sie azapi_resource anstelle von AzureRM, um das übergeordnete Element zu erstellen, und response_export_values um den Endpunkt zu erfassen.

resource "azapi_resource" "app_config" {
  type      = "Microsoft.AppConfiguration/configurationStores@2023-03-01"
  name      = "my-store"
  parent_id = azapi_resource.resource_group.id
  location  = "eastus"
  body      = { sku = { name = "standard" } }

  response_export_values = {
    endpoint = "properties.endpoint"
  }
}

resource "azapi_data_plane_resource" "key_value" {
  type      = "Microsoft.AppConfiguration/configurationStores/keyValues@1.0"
  parent_id = replace(azapi_resource.app_config.output.endpoint, "https://", "")
  name      = "mykey"
  body      = { value = "myvalue", content_type = "" }
}

Erstellen Sie für Dienste, bei denen der Endpunkt vom Ressourcennamen und nicht von einer URI-Eigenschaft abgeleitet wird, direkt:

resource "azurerm_search_service" "example" {
  name                = "my-search"
  # ... configuration
}

resource "azapi_data_plane_resource" "index" {
  type      = "Microsoft.Search/searchServices/indexes@2024-07-01"
  parent_id = "${azurerm_search_service.example.name}.search.windows.net"
  name      = "my-index"
  body      = { fields = [ /* ... */ ] }
}

Authentifizierung für Datenebenenendpunkte

Der AzAPI-Anbieter verarbeitet die Authentifizierung transparent. Es verwendet dieselben Anmeldeinformationen, die Sie im provider "azapi"-Block (Azure CLI, Dienstprinzipal, verwaltete Identität oder OpenID Connect (OIDC)) konfigurieren, und fordert automatisch Token an, die auf die Datenebene jedes Dienstes beschränkt sind, anstatt auf die Zielgruppe des ARM.

Beispielsweise erfordern Datenebenenvorgänge in Key Vault eine Token-Zielgruppe von https://vault.azure.net, nicht https://management.azure.com. Der AzAPI-Anbieter wählt die richtige Zielgruppe basierend auf dem registrierten Endpunkt für jeden Ressourcentyp aus.

Als Arzt müssen Sie nichts anderes konfigurieren. Die standardmäßigen rollenbasierten Zugriffssteuerungsberechtigungen (RBAC) für den Dienst gelten, z. B. Key Vault Secrets Officer zum Verwalten von Key Vault geheimen Schlüsseln oder App Configuration Data Owner zum Verwalten von App-Konfigurationsschlüsselwerten.

Note

Bei einigen Diensten (z. B. Azure App Configuration und Azure KI-Suche) muss der Anrufer über die entsprechende Rollenzuweisung für die Datenebene verfügen, nicht nur über die Rolle des Besitzers der Steuerungsebene. Stellen Sie sicher, dass die Identität, die Terraform ausführt, über die richtige rollenbasierte Zugriffssteuerungszuweisung (RBAC) für die Datenebene verfügt, bevor Konfigurationen angewendet werden, die azapi_data_plane_resource verwenden.

Ressourcen-ID-Format für den Import

Ressourcen-IDs der Datenebene verwenden ein anderes Format als ARM-Ressourcen-IDs. Verwenden Sie beim Importieren einer vorhandenen Datenebenenressource das Format {parent_id}/{path}|{resource-type}@{api-version}:

import {
  to = azapi_data_plane_resource.example
  id = "exampleappconf.azconfig.io/kv/mykey|Microsoft.AppConfiguration/configurationStores/keyValues@1.0"
}

Oder mit terraform import:

terraform import azapi_data_plane_resource.example 'exampleappconf.azconfig.io/kv/mykey|Microsoft.AppConfiguration/configurationStores/keyValues@1.0'

Unterstützte Datenebenendienste

Der AzAPI-Anbieter unterstützt derzeit Ressourcentypen für diese Dienste: azapi_data_plane_resource

  • Azure App Configuration – Schlüsselwerte
  • Azure AI Foundry —agents
  • Azure Device Update – Gruppen, Bereitstellungen
  • Azure Digital Twins – digitale Zwillinge, Beziehungen, Ereignisrouten, Importaufträge
  • Azure IoT Central – Organisationen, Benutzer, geplante Aufträge, API-Token, Dashboards, Gerätegruppen, Gerätevorlagen, Gerätevorlagen, Registrierungsgruppen, Datenexporte, Bereitstellungsmanifeste
  • Azure Key Vault – Zertifikate Kontakte, Zertifikataussteller, Schlüssel, Geheime Schlüssel, Speicherkonten, SAS-Definitionen
  • Microsoft Purview – Sammlungen, Ressourcensatzregelkonfigurationen, Schlüsseltresor, Klassifizierungsregeln, Anmeldeinformationen, Datenquellen, Scans, Scantrigger, Integrationslaufzeiten, verwaltete private Endpunkte, Workflows
  • Azure KI-Suche – Datenquellen, Indexer, Indizes, Fähigkeitensätze, Synonymkarten
  • Azure Synapse Analytics – Datenbanken, Datenflüsse, Datasets, Kusto Query Language (KQL)-Skripts, Bibliotheken, Verknüpfungsverbindungen, verknüpfte Dienste, verwaltete private Endpunkte, Notizbücher, Pipelines, Rollenzuweisungen, Spark-Auftragsdefinitionen, Spark-Konfigurationen, SQL-Skripts, Trigger

Die vollständige Liste mit API-Versionen und Endpunktmustern finden Sie in der verfügbaren Ressourcenreferenz in der Terraform-Registrierung.

Nächste Schritte

Manage Azure Datenebenenressourcen mit AzAPI (Schnellstart)

Übersicht über Terraform AzAPI-Anbieter

  • Last updated on