Vysvětlení architektury roviny dat AzAPI

Většina Azure prostředků se spravuje prostřednictvím řídicí roviny Azure Resource Manager (ARM) – jedno sjednocené rozhraní API na management.azure.com. Všechny typy prostředků azapi_resource, azapi_update_resource a azapi_resource_action cílí na tuto řídicí rovinu.

Některé služby Azure zpřístupňují samostatné rozhraní API roviny dat – koncový bod HTTPS specifický pro službu, ve kterém komunikujete přímo se službou místo prostřednictvím ARM. Mezi příklady patří rozhraní API tajemství Key Vault na adrese {vaultName}.vault.azure.net, rozhraní API indexu Azure AI Vyhledávač na adrese {searchServiceName}.search.windows.net a rozhraní API datového toku pracovního prostoru Synapse na adrese {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource tuto mezeru překlenuje tím, že umožňuje Terraformu spravovat prostředky na těchto koncových bodech datové roviny pomocí stejného modelu ověřování a životního cyklu poskytovatele AzAPI.

Proč se podporuje jenom kurátorovaná sada typů prostředků

Na rozdíl od azapi_resource, který může cílit na libovolný typ prostředku ARM, azapi_data_plane_resource funguje jen s konkrétním seznamem registrovaných typů prostředků.

Toto omezení existuje, protože rozšiřitelnost roviny dat vyžaduje explicitní registraci v rozhraní roviny dat zprostředkovatele AzAPI. Rámec musí vědět:

  • Vzor základního koncového bodu pro službu (například {vaultName}.vault.azure.net)
  • Cesta REST pro každý podporovaný typ prostředku (například /secrets/{secret-name})
  • Jak se ověřit u tohoto koncového bodu (některé služby vyžadují tokeny pro specifické cílové skupiny služeb místo výchozího cílového publika ARM)https://management.azure.com

Každý zaregistrovaný typ prostředku toto mapování přidá do architektury. Neregistrované typy prostředků nelze cílit prostřednictvím azapi_data_plane_resource, protože poskytovatel nemá žádný způsob, jak určit správný koncový bod nebo obor ověřování.

Tip

Pokud požadovaný typ prostředku roviny dat není podporovaný, můžete otevřít problém nebo přispět registrací v úložišti GitHub terraform-provider-azapi.

Jak parent_id funguje u prostředků datové roviny

Pro prostředky řídicí roviny (azapi_resource) je parent_id vždy ID prostředku ARM—cesta ve tvaru /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}.

U prostředků datové roviny je název hostitele datové roviny služby zbavený schématu https:// a veškerého koncového lomítka. Tento koncový bod je obvykle vlastnost dostupná na prostředku řídicí roviny ARM po vytvoření.

Model se liší podle služby:

Service Výstupní vlastnost ARM vzor parent_id
Key Vault properties.vaultUri {vaultName}.vault.azure.net
Azure App Configuration properties.endpoint {storeName}.azconfig.io
Azure AI Vyhledávač (sestaveno z názvu) {searchServiceName}.search.windows.net
Synapse pracovního prostoru connectivityEndpoints.dev {workspaceName}.dev.azuresynapse.net
Aplikace IoT Central properties.subdomain {appSubdomain}.azureiotcentral.com
Microsoft Purview (sestaveno z názvu) {accountName}.purview.azure.com

Extrahování parent_id z výstupu ARM

Použijte response_export_values na nadřazený prostředek ARM, abyste extrahovali koncový bod datové roviny, a potom odstraňte schéma příkazem trimprefix nebo 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 }
  }
}

Pokud používáte azapi_resource k vytvoření nadřazeného objektu místo AzureRM, použijte response_export_values k zachycení koncového bodu:

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

Pro služby, ve kterých je koncový bod odvozený z názvu prostředku místo vlastnosti URI, vytvořte ho přímo:

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 = [ /* ... */ ] }
}

Ověřování koncových bodů roviny dat

Zprostředkovatel AzAPI zpracovává ověřování transparentně. Používá stejné přihlašovací údaje, které nakonfigurujete na bloku provider "azapi" (Azure CLI, instanční objekt, spravovanou identitu nebo OpenID Connect (OIDC)), ale automaticky požaduje tokeny určené pro cílovou skupinu roviny dat jednotlivých služeb, nikoli pro publikum ARM.

Například operace datové roviny Key Vault vyžadují tokenového adresáta https://vault.azure.net, nikoli https://management.azure.com. Poskytovatel AzAPI vybere správnou cílovou skupinu na základě registrovaného koncového bodu pro každý typ prostředku.

Jako odborník nemusíte nic konfigurovat jinak. Pro službu platí standardní oprávnění řízení přístupu na základě role (RBAC), například Key Vault Secrets Officer pro správu Key Vault tajných kódů nebo App Configuration Data Owner ke správě hodnot klíčů služby App Configuration.

Note

U některých služeb (například Azure App Configuration a Azure AI Vyhledávač) musí volající mít odpovídající přiřazení role roviny dat, nejen roli vlastníka řídicí roviny. Před použitím konfigurací, které používají azapi_data_plane_resource, se ujistěte, že identita, na které běží Terraform, má správné přiřazení řízení přístupu na základě role (RBAC).

Formát ID prostředku pro import

ID prostředku v datové rovině používá jiný formát než ID prostředku ARM. Při importu existujícího prostředku roviny dat použijte formát {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"
}

Nebo s terraform import:

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

Podporované služby roviny dat

Poskytovatel AzAPI v současné době podporuje typy prostředků azapi_data_plane_resource v rámci těchto služeb:

  • Azure App Configuration – hodnoty klíče
  • Azure AI Foundry – agenti
  • Azure Aktualizace zařízení – skupiny, nasazení
  • Azure Digital Twins – digitální dvojčata, relace, trasy událostí, úlohy importu
  • Azure IoT Central – organizace, uživatelé, naplánované úlohy, tokeny rozhraní API, řídicí panely, skupiny zařízení, šablony zařízení, zařízení, skupiny registrací, exporty dat, manifesty nasazení
  • Azure Key Vault – kontakty certifikátů, vystavitele certifikátů, klíče, tajné kódy, účty úložiště, definice SAS
  • Microsoft Purview – kolekce, konfigurace pravidel sady prostředků, trezory klíčů, pravidla klasifikace, přihlašovací údaje, zdroje dat, kontroly, triggery prohledávání, prostředí Integration Runtime, spravované privátní koncové body, pracovní postupy
  • Azure AI Vyhledávač – zdroje dat, indexery, indexy, sady dovedností, mapy synonym
  • Azure Synapse Analytics – databáze, toky dat, datové sady, skripty jazyka Kusto Query Language (KQL), knihovny, propojení, propojené služby, spravované privátní koncové body, poznámkové bloky, kanály, přiřazení rolí, definice úloh Sparku, konfigurace Sparku, skripty SQL, triggery

Úplný seznam verzí rozhraní API a vzorů koncových bodů najdete v referenčních informacích k dostupným prostředkům v registru Terraformu.

Další kroky

Správa prostředků datové roviny Azure pomocí AzAPI (rychlý start)

Přehled zprostředkovatele Terraform AzAPI

  • Last updated on