AzAPI 데이터 평면 프레임워크 이해

대부분의 Azure 리소스는 ARM(Azure Resource Manager) 컨트롤 플레인(management.azure.com 단일 통합 API 표면)을 통해 관리됩니다. azapi_resource, azapi_update_resource, 및 azapi_resource_action 리소스 종류 모두 이 컨트롤 플레인을 대상으로 합니다.

일부 Azure 서비스는 ARM이 아닌 서비스와 직접 상호 작용하는 서비스별 HTTPS 엔드포인트인 별도의 데이터 플레인 API를 노출합니다. 예를 들어 {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 공급자 인증 및 수명 주기 모델을 사용하여 이러한 데이터 평면 엔드포인트에서 리소스를 관리할 수 있도록 하여 이러한 격차를 해소합니다.

큐레이팅된 리소스 종류 집합만 지원되는 이유

ARM 리소스 유형을 대상으로 지정할 수 있는 azapi_resource와 달리, 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)의 경우, /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}은/는 항상 ARM 리소스 ID이며, parent_id 형식의 경로입니다.

데이터 평면 리소스를 위한 경우, parent_id는 스키마 및 후행 슬래시가 제거된 서비스의 데이터 평면 호스트 이름입니다. 이 엔드포인트는 일반적으로 만든 후 ARM 컨트롤 플레인 리소스에 노출되는 속성입니다.

패턴은 서비스에 따라 다릅니다.

Service ARM 출력 속성 parent_id 패턴
Key Vault (키 보관소) properties.vaultUri {vaultName}.vault.azure.net
Azure 애플리케이션 구성 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

parent_id ARM 출력에서 추출

부모 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 }
  }
}

AzureRM 대신 부모를 만드는 데 사용하는 azapi_resource 경우 엔드포인트를 캡처하는 데 사용합니다 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 또는 OIDC(OpenID Connect))에서 구성하는 것과 동일한 자격 증명을 사용하지만 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)이 적용됩니다.

참고

일부 서비스(예: Azure App Configuration 및 Azure AI 검색)의 경우 호출자에게 컨트롤 플레인 소유자 역할뿐만 아니라 적절한 데이터 평면 역할 할당이 있어야 합니다. Terraform을 실행하는 ID에 사용하는 azapi_data_plane_resource구성을 적용하기 전에 올바른 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 디바이스 업데이트 - 그룹, 배포
  • Azure Digital Twins - 디지털 트윈, 관계, 이벤트 경로, 가져오기 작업
  • Azure IoT Central - 조직, 사용자, 예약된 작업, API 토큰, 대시보드, 디바이스 그룹, 디바이스 템플릿, 디바이스, 등록 그룹, 데이터 내보내기, 배포 매니페스트
  • Azure Key Vault - 인증서 연락처, 인증서 발급자, 키, 비밀, 스토리지 계정, SAS 정의
  • Microsoft Purview - 컬렉션, 리소스 집합 규칙 구성, 키 자격 증명 모음, 분류 규칙, 자격 증명, 데이터 원본, 검사, 검사 트리거, 통합 런타임, 관리형 프라이빗 엔드포인트, 워크플로
  • Azure AI 검색 - 데이터 원본, 인덱서, 인덱스, 기술 세트, 동의어 맵
  • Azure Synapse Analytics - 데이터베이스, 데이터 흐름, 데이터 세트, KQL(Kusto Query Language) 스크립트, 라이브러리, 연결 연결, 연결된 서비스, 관리형 프라이빗 엔드포인트, Notebook, 파이프라인, 역할 할당, Spark 작업 정의, Spark 구성, SQL 스크립트, 트리거

API 버전 및 엔드포인트 패턴이 있는 전체 목록은 Terraform 레지스트리의 사용 가능한 리소스 참조 참조하세요.

다음 단계

AzAPI를 사용하여 데이터 평면 리소스를 Azure 관리(빠른 시작)

Terraform AzAPI 공급자 개요

  • Last updated on