Descripción del marco del plano de datos de AzAPI

La mayoría de los recursos de Azure se administran a través del plano de control de Azure Resource Manager (ARM), una sola superficie de API unificada en management.azure.com. Los azapi_resourcetipos de recursos , azapi_update_resourcey azapi_resource_action tienen como destino este plano de control.

Algunos servicios Azure exponen un data plane API independiente: un punto de conexión HTTPS específico del servicio en el que interactúa directamente con el servicio en lugar de a través de ARM. Algunos ejemplos incluyen la API de secretos de Key Vault en {vaultName}.vault.azure.net, la API de índice de Búsqueda de Azure AI en {searchServiceName}.search.windows.net y la API de canalización del área de trabajo de Synapse en {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource cierra esta brecha al permitir que Terraform administre recursos en estos puntos de conexión del plano de datos mediante el mismo modelo de autenticación y ciclo de vida del proveedor de AzAPI.

¿Por qué solo se admite un conjunto mantenido de tipos de recursos?

A diferencia de azapi_resource, que puede tener como destino cualquier tipo de recurso arm, azapi_data_plane_resource solo funciona con una lista especific de tipos de recursos registrados.

Esta restricción existe porque la extensibilidad del plano de datos requiere un registro explícito en el marco del plano de datos del proveedor de AzAPI. El marco debe saber lo siguiente:

  • Patrón de punto de conexión base para un servicio (por ejemplo, {vaultName}.vault.azure.net)
  • Ruta de acceso de REST para cada tipo de recurso admitido (por ejemplo, /secrets/{secret-name})
  • Cómo autenticarse en este punto de conexión (algunos servicios requieren audiencias específicas de tokens del servicio en lugar de la audiencia de ARM predeterminada en https://management.azure.com)

Cada tipo de recurso registrado agrega esta asignación al marco de trabajo. Los tipos de recursos no registrados no se pueden destinar a través de azapi_data_plane_resource, ya que el proveedor no tiene forma de determinar el endpoint o el ámbito de autenticación correctos.

Tip

Si no se admite un tipo de recurso del plano de datos que necesita, puede abrir un problema o contribuir con un registro en el repositorio de GitHub terraform-provider-azapi.

Cómo funciona parent_id en los recursos del plano de datos

En el caso de los recursos del plano de control (azapi_resource), parent_id siempre es un identificador de recurso de ARM, una ruta de acceso con el formato /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}.

Para los recursos del plano de datos, parent_id es el nombre de host del plano de datos del servicio, sin el https:// esquema ni barra diagonal final. Este punto de conexión suele ser una propiedad expuesta en el recurso de la plataforma de control de Azure Resource Manager (ARM) después de la creación.

El patrón varía según el servicio:

Service Propiedad de salida de ARM parent_id patrón
Almacén de claves (Key Vault) properties.vaultUri {vaultName}.vault.azure.net
Configuración de aplicaciones de Azure properties.endpoint {storeName}.azconfig.io
Búsqueda de Azure AI (construido a partir del nombre) {searchServiceName}.search.windows.net
Área de trabajo de Synapse connectivityEndpoints.dev {workspaceName}.dev.azuresynapse.net
Aplicación de IoT Central properties.subdomain {appSubdomain}.azureiotcentral.com
Microsoft Purview (construido a partir del nombre) {accountName}.purview.azure.com

Extrayendo parent_id de la salida de ARM

Usa response_export_values en el recurso ARM principal para extraer el punto de conexión del plano de datos y, a continuación, quita el esquema 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 }
  }
}

Al usar azapi_resource para crear el elemento primario en lugar de AzureRM, use response_export_values para capturar el punto de conexión:

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

En el caso de los servicios en los que el punto de conexión se deriva del nombre del recurso en lugar de una propiedad URI, consígnelo directamente:

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

Autenticación en puntos de conexión del plano de datos

El proveedor de AzAPI controla la autenticación de forma transparente. Usa las mismas credenciales que configuras en el bloque provider "azapi" (CLI de Azure, entidad de servicio, identidad administrada o OpenID Connect (OIDC)), pero solicita automáticamente tokens con ámbito para la audiencia del plano de datos de cada servicio en lugar de para la audiencia de ARM.

Las operaciones del plano de datos de Key Vault requieren un destinatario del token de https://vault.azure.net, no https://management.azure.com. El proveedor de AzAPI selecciona la audiencia correcta en función del punto de conexión registrado para cada tipo de recurso.

Como profesional, no es necesario configurar nada de forma diferente. Se aplican los permisos estándar de control de acceso basado en rol (RBAC) para el servicio, por ejemplo, Key Vault Secrets Officer administrar secretos de Key Vault o App Configuration Data Owner para administrar los valores clave de configuración de aplicaciones.

Note

Para algunos servicios (como Azure App Configuration y Búsqueda de Azure AI), el autor de la llamada debe tener la asignación de roles del plano de datos adecuada, no solo el rol de propietario del plano de control. Asegúrese de que la identidad que ejecuta Terraform tiene la asignación correcta del control de acceso basado en rol (RBAC) del plano de datos antes de aplicar configuraciones que usan azapi_data_plane_resource.

Formato de identificador de recurso para la importación

Los identificadores de recursos del plano de datos usan un formato diferente al de los identificadores de recursos de ARM. Al importar un recurso de plano de datos existente, use el 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"
}

O con terraform import:

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

Servicios de plano de control de datos compatibles

Actualmente, el proveedor AzAPI admite azapi_data_plane_resource para tipos de recursos en estos servicios:

  • Azure App Configuration—claves y valores
  • Fundición de IA de Azure: agentes
  • Azure Device Update: grupos, implementaciones
  • Azure Digital Twins: gemelos digitales, relaciones, rutas de eventos, trabajos de importación
  • Azure IoT Central: organizaciones, usuarios, trabajos programados, tokens de API, paneles, grupos de dispositivos, plantillas de dispositivo, dispositivos, grupos de inscripción, exportaciones de datos, manifiestos de implementación
  • Azure Key Vault: contactos de certificados, emisores de certificados, claves, secretos, cuentas de almacenamiento, definiciones de SAS
  • Microsoft Purview: colecciones, configuraciones de reglas del conjunto de recursos, almacenes de claves, reglas de clasificación, credenciales, orígenes de datos, análisis, desencadenadores de análisis, runtimes de integración, puntos de conexión privada administrada, flujos de trabajo
  • Búsqueda de Azure AI: orígenes de datos, indexadores, índices, conjuntos de aptitudes, mapas de sinónimos
  • Azure Synapse Analytics: bases de datos, flujos de datos, conjuntos de datos, scripts de lenguaje de consulta kusto (KQL), bibliotecas, conexiones de vínculo, servicios vinculados, puntos de conexión privados administrados, cuadernos, canalizaciones, asignaciones de roles, definiciones de trabajos de Spark, configuraciones de Spark, scripts SQL, desencadenadores

Para obtener la lista completa con las versiones de API y los patrones de punto de conexión, consulte la referencia de recursos disponibles en el Registro de Terraform.

Pasos siguientes

Administrar recursos del plano de datos Azure con AzAPI (inicio rápido)

Introducción al proveedor de Terraform AzAPI

  • Last updated on