Förstå Ramverket för AzAPI-dataplan

De flesta Azure resurser hanteras via kontrollplanet Azure Resource Manager (ARM) – en enda enhetlig API-yta på management.azure.com. Resurstyperna azapi_resource, azapi_update_resourceoch azapi_resource_action är alla mål för det här kontrollplanet.

Vissa Azure tjänster exponerar ett separat dataplans-API – en tjänstspecifik HTTPS-slutpunkt där du interagerar direkt med tjänsten i stället för via ARM. Exempel inkluderar API:et för Key Vault-hemligheter på {vaultName}.vault.azure.net, API:et för Azure AI-sökning-index på {searchServiceName}.search.windows.net och API:et för Synapse-arbetsytans pipeline på {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource överbryggar det här gapet genom att göra det möjligt för Terraform att hantera resurser på dessa dataplansslutpunkter med samma AzAPI-providerautentisering och livscykelmodell.

Därför stöds bara en kurerad uppsättning resurstyper

Till skillnad från azapi_resource, som kan riktas mot alla ARM-resurstyper, fungerar azapi_data_plane_resource bara med en specifik lista över registrerade resurstyper.

Den här begränsningen finns eftersom utökningsbarhet för dataplan kräver explicit registrering i AzAPI-providerns dataplansramverk. Ramverket måste känna till följande:

  • Basslutpunktsmönstret för en tjänst (till exempel {vaultName}.vault.azure.net)
  • REST-sökvägen för varje resurstyp som stöds (till exempel /secrets/{secret-name})
  • Så här autentiserar du till den här slutpunkten (vissa tjänster kräver tjänstspecifika tokenmål i stället för standard-ARM-målgruppen på https://management.azure.com)

Varje registrerad resurstyp lägger till den här mappningen i ramverket. Oregistrerade resurstyper kan inte målinriktas genom azapi_data_plane_resource, eftersom leverantören inte har något sätt att fastställa rätt slutpunkt eller autentiseringsomfång.

Tip

Om en dataplansresurstyp som du behöver inte stöds kan du öppna ett problem eller bidra med en registrering i terraform-provider-azapi GitHub lagringsplats.

Hur parent_id fungerar för data-plane-resurser

För kontrollplansresurser (azapi_resource) är parent_id alltid ett ARM-resurs-ID – en sökväg i formatet /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}.

För dataplansresurser parent_id är tjänstens värdnamn för dataplanet, borttaget https:// från schemat och eventuella avslutande snedstreck. Den här slutpunkten är vanligtvis en egenskap som exponeras på ARM-kontrollplansresursen när den har skapats.

Mönstret varierar beroende på tjänst:

Service ARM-utdataegenskap parent_id mönster
Key Vault properties.vaultUri {vaultName}.vault.azure.net
Azure App Configuration (programkonfiguration för appar) properties.endpoint {storeName}.azconfig.io
Azure AI-sökning genererat från namn {searchServiceName}.search.windows.net
Synapse-arbetsyta connectivityEndpoints.dev {workspaceName}.dev.azuresynapse.net
IoT Central-app properties.subdomain {appSubdomain}.azureiotcentral.com
Microsoft Purview (konstruerad från namn) {accountName}.purview.azure.com

Extrahera parent_id från ARM-utdata

Använd response_export_values på den överordnade ARM-resursen för att extrahera dataplanets slutpunkt och ta sedan bort schemat med trimprefix eller 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 }
  }
}

När du använder azapi_resource för att skapa överordnaden i stället för AzureRM, ska du använda response_export_values för att fånga slutpunkten.

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

För tjänster där slutpunkten härleds från resursnamnet i stället för en URI-egenskap skapar du den 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 = [ /* ... */ ] }
}

Autentisering till dataplanets slutpunkter

AzAPI-providern hanterar autentisering transparent. Den använder samma autentiseringsuppgifter som du konfigurerar på blocket provider "azapi" (Azure CLI, tjänstens huvudnamn, hanterad identitet eller OpenID Connect (OIDC)), men begär automatiskt token som är begränsade till varje tjänsts dataplanspublik i stället för ARM-målgruppen.

Till exempel kräver dataplansåtgärder i Key Vault en tokenmålgrupp på https://vault.azure.net, inte https://management.azure.com. AzAPI-providern väljer rätt målgrupp baserat på den registrerade slutpunkten för varje resurstyp.

Som utövare behöver du inte konfigurera något annat. Standardbehörigheterna för rollbaserad åtkomstkontroll (RBAC) för tjänsten gäller, till exempel Key Vault Secrets Officer för att hantera Key Vault hemligheter eller App Configuration Data Owner för att hantera nyckelvärden för appkonfiguration.

Anmärkning

För vissa tjänster (till exempel Azure App Configuration och Azure AI-sökning) måste anroparen ha rätt rolltilldelning för dataplanet, inte bara kontrollplanets ägarroll. Kontrollera att den identitet som kör Terraform har rätt rollbaserad åtkomstkontroll för dataplanet (RBAC) innan du tillämpar konfigurationer som använder azapi_data_plane_resource.

Resurs-ID-format för import

Resurs-ID för dataplan använder ett annat format än ARM-resurs-ID:t. När du importerar en befintlig dataplansresurs använder du formatet {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"
}

Eller med terraform import:

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

Dataplanstjänster som stöds

AzAPI-providern har för närvarande stöd azapi_data_plane_resource för resurstyper i dessa tjänster:

  • Azure App Configuration – nyckelvärden
  • Azure AI Foundry – agenttjänster
  • Azure Enhetsuppdatering – grupper, distributioner
  • Azure Digital Twins – digitala tvillingar, relationer, händelsevägar, importjobb
  • Azure IoT Central – organisationer, användare, schemalagda jobb, API-token, instrumentpaneler, enhetsgrupper, enhetsmallar, enheter, registreringsgrupper, dataexporter, distributionsmanifest
  • Azure Key Vault – certifikatkontakter, certifikatutfärdare, nycklar, hemligheter, lagringskonton, SAS-definitioner
  • Microsoft Purview – samlingar, regelkonfigurationer för resursuppsättningar, nyckelvalv, klassificeringsregler, autentiseringsuppgifter, datakällor, genomsökningar, genomsökningsutlösare, integreringskörningar, hanterade privata slutpunkter, arbetsflöden
  • Azure AI-sökning – datakällor, indexerare, index, kompetensuppsättningar, synonymkartor
  • Azure Synapse Analytics – databaser, dataflöden, datauppsättningar, KQL-skript (Kusto Query Language), bibliotek, länkanslutningar, länkade tjänster, hanterade privata slutpunkter, notebook-filer, pipelines, rolltilldelningar, Spark-jobbdefinitioner, Spark-konfigurationer, SQL-skript, utlösare

Den fullständiga listan med API-versioner och slutpunktsmönster finns i referensen tillgängliga resurser i Terraform Registry.

Nästa steg

Hantera Azure dataplansresurser med AzAPI (snabbstart)

Översikt över Terraform AzAPI-provider

  • Last updated on