AzAPI データ プレーン フレームワークについて

ほとんどのAzure リソースは、Azure Resource Manager (ARM) コントロール プレーン (management.azure.com の単一の統合 API サーフェス) を介して管理されます。 azapi_resource、azapi_update_resource、およびazapi_resource_actionリソースの種類はすべて、このコントロール プレーンを対象とします。

一部のAzure サービスでは、個別の data プレーン API が公開されます。これは、ARM を介してではなく、サービスと直接やり取りするサービス固有の HTTPS エンドポイントです。 たとえば、{vaultName}.vault.azure.net の Key Vault シークレット API、{searchServiceName}.search.windows.net の Azure AI 検索 インデックス API、{workspaceName}.dev.azuresynapse.net の Synapse ワークスペース パイプライン API などです。

azapi_data_plane_resource は、Terraform が同じ AzAPI プロバイダー認証とライフサイクル モデルを使用してこれらのデータ プレーン エンドポイント上のリソースを管理できるようにすることで、このギャップを埋めます。

キュレーションされたリソースの種類のセットのみがサポートされる理由

azapi_resourceとは異なり、azapi_data_plane_resourceは登録済みの特定リソースタイプのリストでのみ機能します。

この制約は、データ プレーンの拡張性に AzAPI プロバイダーのデータ プレーン フレームワークへの明示的な登録が必要であるために存在します。 フレームワークは次のことを認識している必要があります。

  • サービスの基本エンドポイント パターン (たとえば、 {vaultName}.vault.azure.net)
  • サポートされている各リソースの種類の REST パス (たとえば、 /secrets/{secret-name})
  • このエンドポイントに対する認証方法 (一部のサービスでは、 https://management.azure.comの既定の ARM 対象ユーザーではなく、サービス固有のトークン 対象ユーザーが必要です)

登録されているリソースの種類ごとに、このマッピングがフレームワークに追加されます。 未登録のリソースの種類は、プロバイダーが正しいエンドポイントまたは認証スコープを決定する方法がないため、 azapi_data_plane_resourceを使用してターゲットにすることはできません。

ヒント

必要なデータ プレーン リソースの種類がサポートされていない場合は、問題を開くか、 teraform-provider-azapi GitHub リポジトリで登録を投稿できます。

データ プレーン リソース parent_id のしくみ

コントロール プレーン リソース (azapi_resource) の場合、 parent_id は常に ARM リソース ID ( /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}形式のパス) です。

データ プレーン リソースの場合、 parent_id は サービスのデータ プレーンホスト名であり、 https:// スキームと末尾のスラッシュが削除されます。 通常、このエンドポイントは、作成後に ARM コントロール プレーン リソースで公開されるプロパティです。

パターンはサービスによって異なります。

Service ARM 出力プロパティ parent_id パターン
Key Vault properties.vaultUri {vaultName}.vault.azure.net
Azure App Configuration properties.endpoint {storeName}.azconfig.io
Azure AI 検索 (名前から構築) {searchServiceName}.search.windows.net
Synapse ワークスペース connectivityEndpoints.dev {workspaceName}.dev.azuresynapse.net
IoT Central アプリ properties.subdomain {appSubdomain}.azureiotcentral.com
Microsoft Purview (名前から構築) {accountName}.purview.azure.com

ARM 出力からの parent_id の抽出

親 ARM リソースの response_export_values を使用してデータ プレーン エンドポイントを抽出し、 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、サービス プリンシパル、マネージド ID、または OpenID Connect (OIDC) で構成したのと同じ資格情報が使用されますが、ARM 対象ユーザーではなく、各サービスのデータ プレーン対象ユーザーにスコープが設定されたトークンが自動的に要求されます。

たとえば、データ プレーン操作Key Vaultには、https://vault.azure.net ではなく、https://management.azure.com のトークン対象ユーザーが必要です。 AzAPI プロバイダーは、リソースの種類ごとに登録されたエンドポイントに基づいて適切な対象ユーザーを選択します。

開業医として、異なる構成を行う必要はありません。 サービスの標準的なロールベースのアクセス制御 (RBAC) アクセス許可が適用されます。たとえば、Key Vault シークレットを管理するには Key Vault Secrets Officer、App Configuration キー値を管理するには App Configuration Data Owner が適用されます。

Note

一部のサービス (Azure App ConfigurationやAzure AI 検索など) の場合、呼び出し元にはコントロール プレーン所有者ロールだけでなく、適切なデータ プレーン ロールの割り当てが必要です。 azapi_data_plane_resourceを使用する構成を適用する前に、Terraform を実行している ID に正しいデータ プレーン ロールベースのアクセス制御 (RBAC) の割り当てが割り当てられていることを確認します。

インポートのリソース ID 形式

データ プレーン リソース ID は、ARM リソース ID とは異なる形式を使用します。 既存のデータ プレーン リソースをインポートする場合は、 {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 App Configuration — キー値
  • Azure AI Foundry — エージェント
  • Azure Device Update - グループ、展開
  • Azure Digital Twins - デジタル ツイン、リレーションシップ、イベント ルート、インポート ジョブ
  • Azure IoT Central - 組織、ユーザー、スケジュールされたジョブ、API トークン、ダッシュボード、デバイス グループ、デバイス テンプレート、デバイス、登録グループ、データエクスポート、配置マニフェスト
  • Azure Key Vault - 証明書の連絡先、証明書の発行者、キー、シークレット、ストレージ アカウント、SAS 定義
  • Microsoft Purview - コレクション、リソース セットルールの構成、キー コンテナー、分類規則、資格情報、データ ソース、スキャン、スキャン トリガー、統合ランタイム、マネージド プライベート エンドポイント、ワークフロー
  • Azure AI 検索 - データ ソース、インデクサー、インデックス、スキルセット、シノニム マップ
  • Azure Synapse Analytics - データベース、データフロー、データセット、Kusto クエリ言語 (KQL) スクリプト、ライブラリ、リンク接続、リンクされたサービス、マネージド プライベート エンドポイント、ノートブック、パイプライン、ロールの割り当て、Spark ジョブ定義、Spark 構成、SQL スクリプト、トリガー

API のバージョンとエンドポイント パターンの完全な一覧については、Terraform レジストリの available resources reference を参照してください。

次のステップ

AzAPI を使用して Azure のデータ プレーン リソースを管理する (クイック スタート)

Terraform AzAPI プロバイダーの概要

  • Last updated on