Informazioni sul framework del piano dati AzAPI

La maggior parte delle risorse Azure viene gestita tramite il piano di controllo Azure Resource Manager (ARM), una singola superficie API unificata in management.azure.com. Tutti i tipi di risorse azapi_resource, azapi_update_resource e azapi_resource_action sono destinati a questo piano di controllo.

Alcuni servizi Azure espongono un'API del "data plane"—un endpoint HTTPS specifico del servizio in cui si interagisce direttamente con il servizio invece che tramite ARM. Gli esempi includono l'API dei segreti Key Vault in {vaultName}.vault.azure.net, l'API dell'indice Azure AI Search in {searchServiceName}.search.windows.net e l'API della pipeline dell'area di lavoro Synapse in {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource colmare questo divario consentendo a Terraform di gestire le risorse in questi endpoint del piano dati usando lo stesso modello di ciclo di vita e l'autenticazione del provider AzAPI.

Perché è supportato solo un set curato di tipi di risorse

A differenza di azapi_resource, che può essere usato per qualsiasi tipo di risorsa ARM, azapi_data_plane_resource funziona solo con un elenco specifico dei tipi di risorse registrati.

Questo vincolo esiste perché l'estendibilità del piano dati richiede la registrazione esplicita nel framework del piano dati del provider AzAPI. Il framework deve conoscere:

  • Modello di endpoint di base per un servizio (ad esempio, {vaultName}.vault.azure.net)
  • Percorso REST per ogni tipo di risorsa supportato (ad esempio, /secrets/{secret-name})
  • Come eseguire l'autenticazione a questo endpoint (alcuni servizi richiedono gruppi di destinatari di token specifici del servizio anziché il gruppo di destinatari arm predefinito in https://management.azure.com)

Ogni tipo di risorsa registrata aggiunge questo mapping al framework. I tipi di risorse non registrati non possono essere assegnati tramite azapi_data_plane_resource, perché il provider non è in grado di determinare l'endpoint o l'ambito di autenticazione corretto.

Tip

Se un tipo di risorsa del piano dati di cui hai bisogno non è supportato, puoi segnalare un problema o contribuire con una richiesta nel repository GitHub terraform-provider-azapi.

Come funziona parent_id per le risorse del piano dati

Per le risorse del piano di controllo (azapi_resource), parent_id è sempre un ID risorsa ARM, ovvero un percorso nel formato /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}.

Per le risorse del piano dati, parent_id è il nome host del piano dati del servizio, rimosso dallo https:// schema e qualsiasi barra finale. Questo endpoint è in genere una proprietà esposta nella risorsa del piano di controllo ARM dopo la creazione.

Il modello varia in base al servizio:

Service Proprietà di output ARM modello parent_id
Key Vault properties.vaultUri {vaultName}.vault.azure.net
Configurazione app di Azure properties.endpoint {storeName}.azconfig.io
Ricerca di intelligenza artificiale di Azure (costruito dal nome) {searchServiceName}.search.windows.net
Area di lavoro Synapse connectivityEndpoints.dev {workspaceName}.dev.azuresynapse.net
App IoT Central properties.subdomain {appSubdomain}.azureiotcentral.com
Microsoft Purview (costruito dal nome) {accountName}.purview.azure.com

Estrazione di parent_id dall'output ARM

Usare response_export_values nella risorsa ARM padre per estrarre l'endpoint del piano dati, quindi rimuovere lo schema con trimprefix o 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 }
  }
}

Quando si usa azapi_resource per creare l'elemento padre anziché AzureRM, usare response_export_values per acquisire l'endpoint:

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

Per i servizi in cui l'endpoint è derivato dal nome della risorsa anziché da una proprietà URI, crearlo direttamente:

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

Autenticazione agli endpoint del piano di dati

Il provider AzAPI gestisce l'autenticazione in modo trasparente. Usa le stesse credenziali configurate nel blocco provider "azapi" (interfaccia della riga di comando di Azure, entità servizio, identità gestita o OpenID Connect (OIDC)), ma richiede automaticamente token con ambito per i destinatari del piano dati di ogni servizio anziché per i destinatari dell'audience ARM.

Ad esempio, Key Vault operazioni del piano dati richiedono un gruppo di destinatari del token di https://vault.azure.net, non https://management.azure.com. Il provider AzAPI seleziona il gruppo di destinatari corretto in base all'endpoint registrato per ogni tipo di risorsa.

Come professionista, non è necessario configurare nulla in modo diverso. Le autorizzazioni standard di controllo degli accessi in base al ruolo (RBAC) per il servizio si applicano, ad esempio Key Vault Secrets Officer per gestire i segreti Key Vault o App Configuration Data Owner per gestire i valori delle chiavi di Configurazione app.

Note

Per alcuni servizi , ad esempio Configurazione app di Azure e Azure AI Search, il chiamante deve avere l'assegnazione di ruolo del piano dati appropriata, non solo il ruolo di proprietario del piano di controllo. Verificare che l'identità che esegue Terraform disponga dell'assegnazione corretta del controllo degli accessi in base al ruolo del piano dati prima di applicare le configurazioni che usano azapi_data_plane_resource.

Formato ID risorsa per l'importazione

Gli ID risorsa del piano dati usano un formato diverso rispetto agli ID risorsa ARM. Quando si importa una risorsa del piano dati esistente, usare il formato {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"
}

Oppure con terraform import:

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

Servizi del piano dati supportati

Il provider AzAPI supporta azapi_data_plane_resource attualmente per i tipi di risorse in questi servizi:

  • Configurazione app di Azure- valori chiave
  • Azure AI Foundry—agenti
  • Azure Aggiornamento dispositivi: gruppi, distribuzioni
  • Gemelli digitali di Azure: gemelli digitali, relazioni, percorsi di eventi, processi di importazione
  • Azure IoT Central: organizzazioni, utenti, processi pianificati, token API, dashboard, gruppi di dispositivi, modelli di dispositivo, dispositivi, gruppi di registrazione, esportazioni di dati, manifesti di distribuzione
  • Azure Key Vault: contatti per i certificati, autorità di certificazione, chiavi, segreti, account di archiviazione, definizioni di SAS (firma di accesso condiviso)
  • Microsoft Purview: raccolte, configurazioni delle regole del set di risorse, vault di chiavi, regole di classificazione, credenziali, sorgenti dati, scansioni, trigger di scansione, runtime di integrazione, endpoint privati gestiti, flussi di lavoro
  • Azure AI Search: origini dati, indicizzatori, indici, set di competenze, mappe sinonimiche
  • Azure Synapse Analytics: database, flussi di dati, set di dati, script KQL (Kusto Query Language), librerie, connessioni di collegamento, servizi collegati, endpoint privati gestiti, notebook, pipeline, assegnazioni di ruolo, definizioni di processi Spark, configurazioni spark, script SQL, trigger

Per l'elenco completo con le versioni dell'API e i modelli di endpoint, vedere le informazioni di riferimento sulle risorse disponibili nel Registro Terraform.

Passaggi successivi

Gestire le risorse del piano dati di Azure con AzAPI (guida rapida)

Panoramica del provider AzAPI di Terraform

  • Last updated on