Общие сведения о платформе плоскости данных AzAPI

Большинство ресурсов Azure управляются с помощью плоскости управления Azure Resource Manager (ARM) — единой единой области API в management.azure.com. Типы ресурсов azapi_resource, azapi_update_resource и azapi_resource_action предназначены для этого уровня управления.

Некоторые службы Azure предоставляют отдельный API уровня плоскости данных — это HTTPS конечная точка, специфичная для службы, где вы взаимодействуете с ней напрямую, а не через ARM. Примерами являются API секретов Key Vault в {vaultName}.vault.azure.net, API индекса Поиск с использованием ИИ Azure по адресу {searchServiceName}.search.windows.net и API конвейера рабочей области Synapse в {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource устраняет этот разрыв, позволяя Terraform управлять ресурсами на этих конечных точках уровня данных, используя проверенную модель аутентификации и жизненного цикла поставщика AzAPI.

Почему поддерживается только курированный набор типов ресурсов

В отличие от azapi_resource, который может нацелиться на любой тип ресурса ARM, azapi_data_plane_resource работает только с специфическим списком зарегистрированных типов ресурсов .

Это ограничение существует, так как расширяемость плоскости данных требует явной регистрации в платформе плоскости данных поставщика AzAPI. Платформа должна знать следующее:

  • Шаблон базовой конечной точки для службы (например, {vaultName}.vault.azure.net)
  • Путь REST для каждого поддерживаемого типа ресурса (например, /secrets/{secret-name})
  • Как авторизоваться в этой конечной точке доступа (для некоторых служб требуются целевые аудитории токенов, специфичных для службы, а не аудитория ARM по умолчанию)https://management.azure.com

Каждый зарегистрированный тип ресурса добавляет это сопоставление в платформу. Незарегистрированные типы ресурсов не могут быть нацелены через azapi_data_plane_resource, поскольку у поставщика нет возможности определить правильную конечную точку или область проверки подлинности.

Tip

Если нужный тип ресурса плоскости данных не поддерживается, можно открыть проблему или внести регистрацию в репозитории terraform-provider-azapi GitHub.

Как parent_id работает для ресурсов плоскости данных

Для ресурсов управляющей плоскости (azapi_resource) parent_id всегда является идентификатором ресурса ARM — представляется в виде пути /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}.

Для ресурсов плоскости данных используется имя узла этой плоскости данных службы, очищенное от схемы https:// и завершающей косой черты. Эта конечная точка обычно является свойством, предоставляемым ресурсом уровня управления ARM после создания.

Шаблон зависит от услуги:

Service Свойство вывода ARM шаблон parent_id
Key Vault (Хранилище ключей) properties.vaultUri {vaultName}.vault.azure.net
Конфигурация приложений Azure properties.endpoint {storeName}.azconfig.io
Поиск с использованием ИИ Azure (сформировано из имени) {searchServiceName}.search.windows.net
Рабочая область Synapse connectivityEndpoints.dev {workspaceName}.dev.azuresynapse.net
Приложение IoT Central properties.subdomain {appSubdomain}.azureiotcentral.com
Microsoft Purview (сформировано из названия) {accountName}.purview.azure.com

Извлечение parent_id из выходных данных ARM

Используйте response_export_values родительский ресурс ARM для извлечения конечной точки уровня данных, а затем удалите схему с помощью trimprefix или 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 }
  }
}

При использовании azapi_resource для создания родительского элемента вместо AzureRM используйте response_export_values для записи конечной точки:

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

Для служб, где конечная точка является производным от имени ресурса, а не свойства URI, создайте его напрямую:

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

Аутентификация в конечных точках плоскости передачи данных

Поставщик AzAPI прозрачно обрабатывает проверку подлинности. В нем используются те же учетные данные, которые вы настраиваете в блоке provider "azapi" (Azure CLI, служебный принципал, управляемое удостоверение или OpenID Connect (OIDC)), но автоматически запрашивает токены для аудитории канала данных каждой службы, а не аудитории ARM.

Например, для операций плоскости данных Key Vault требуется целевой адрес https://vault.azure.net, а не https://management.azure.com. Поставщик AzAPI выбирает правильную аудиторию на основе зарегистрированной конечной точки для каждого типа ресурса.

Как практикующий, вам не нужно ничего иначе настраивать. Стандартные разрешения управления доступом на основе ролей (RBAC) для службы применяются, например, Key Vault Secrets Officer для управления секретами Key Vault или App Configuration Data Owner для управления значениями ключей конфигурации приложений.

Note

Для некоторых служб (таких как Конфигурация приложений Azure и Поиск с использованием ИИ Azure) пользователь должен иметь соответствующее назначение роли на уровне данных, а не только роль владельца на управляющем уровне. Убедитесь, что идентификатор, с которого запускается Terraform, имеет корректное назначение роли управления доступом (RBAC) до применения конфигураций, использующих azapi_data_plane_resource.

Формат идентификатора ресурса для импорта

Идентификаторы ресурсов плоскости данных используют другой формат, чем идентификаторы ресурсов ARM. При импорте существующего ресурса плоскости данных используйте формат {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"
}

Или с:terraform import

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

Поддерживаемые службы плоскости данных

Поставщик AzAPI в настоящее время поддерживает azapi_data_plane_resource типы ресурсов в этих службах:

  • Конфигурация приложений Azure — ключи и значения
  • Azure AI Foundry— агенты
  • Azure Device Update — группы, развертывания
  • Azure Digital Twins — цифровые двойники, связи, маршруты событий, задания импорта
  • Azure IoT Central—организации, пользователи, запланированные задания, маркеры API, панели мониторинга, группы устройств, шаблоны устройств, группы регистрации, группы предварительной регистрации, экспорт данных, манифесты развертывания
  • Azure Key Vault— контакты сертификатов, издатели сертификатов, ключи, секреты, учетные записи хранения, определения SAS
  • Microsoft Purview— коллекции, конфигурации правил набора ресурсов, хранилища ключей, правила классификации, учетные данные, источники данных, сканирование, триггеры сканирования, среды выполнения интеграции, управляемые частные конечные точки, рабочие процессы
  • Поиск с использованием ИИ Azure— источники данных, индексаторы, индексы, наборы навыков, карты синонимов
  • Azure Synapse Analytics — базы данных, потоки данных, наборы данных, скрипты языка запросов Kusto (KQL), библиотеки, соединения, связанные службы, управляемые частные конечные точки, записные книжки, конвейеры, назначения ролей, определения заданий Spark, конфигурации Spark, скрипты SQL, триггеры

Полный список версий API и шаблонов конечных точек см. в справочнике по ресурсам available resources в реестре Terraform.

Дальнейшие действия

Управление ресурсами уровня данных Azure с помощью AzAPI (краткое руководство)

Обзор поставщика Terraform AzAPI

  • Последнее обновление: