Terraform AzAPI 공급자 개요

AzAPI 공급자는 Azure ARM REST API 위에 있는 얇은 계층입니다. API 버전을 사용하여 모든 Azure 리소스 유형을 관리할 수 있으므로 Azure 내에서 최신 기능을 활용할 수 있습니다. AzAPI는 자체적으로 또는 AzureRM 공급자와 함께 사용하도록 설계된 일류 공급자입니다.

AzAPI 공급자 사용의 이점

AzAPI 공급자는 다음과 같은 이점을 제공합니다.

• 모든 Azure 컨트롤 플레인 서비스를 지원합니다.
  • 서비스 및 기능 미리 보기
  • 모든 API 버전
• 전체 Terraform 상태 파일 충실도
  • 속성과 값이 상태에 저장됩니다
• Swagger에 대한 종속성 없음
• 일반적이고 일관된 Azure 인증
• 기본 제공 프리플라이트 유효성 검사
• 인프라 개발에 대한 세부적인 제어
• 강력한 VS Code 확장

리소스

업데이트를 요구하지 않고 모든 Azure 리소스 및 기능을 관리할 수 있도록 AzAPI 공급자는 다음과 같은 일반 리소스를 포함합니다.

사용 계층 구조

전반적으로 사용량은 다음 단계를 따라야 합니다.

1. 가능한 많은 작업을 azapi_resource 내에서 수행하는 것으로 시작하는 것이 항상 좋습니다.
2. 리소스 타입이 azapi_resource 에 존재하지 않지만 azapi_data_plane_resource에서 지원하는 타입 중 하나에 속하는 경우, 그렇다면 그것을 대신 사용합니다.
3. 리소스가 이미 AzureRM에 있거나 내에서 azapi_resource액세스할 수 없는 속성이 있는 경우 이러한 특정 속성에 액세스하는 데 사용합니다 azapi_update_resource . azapi_resource 또는 azapi_data_plane_resource이 지원하지 않는 리소스는 이 리소스를 통해 업데이트할 수 없습니다.
4. Azure CRUD 친화적인 리소스에 기반하지 않은 작업을 수행하려는 경우, azapi_resource_action는 azapi_update_resource보다 덜 간단하지만 더 유연합니다.

리소스 구성 예제

다음 코드 조각은 AzureRM 공급자에 현재 존재하지 않는 리소스를 구성합니다.

resource "azapi_resource" "publicip" {
  type      = "Microsoft.Network/Customipprefixes@2021-03-01"
  name      = "exfullrange"
  parent_id = azurerm_resource_group.example.id
  location  = "westus2"

  body = {
    properties = {
      cidr          = "10.0.0.0/24"
      signedMessage = "Sample Message for WAN"
    }
  }
}

다음 코드 조각은 AzureRM의 기존 리소스에 대한 미리 보기 속성을 구성합니다.

resource "azapi_update_resource" "test" {
  type        = "Microsoft.ContainerRegistry/registries@2020-11-01-preview"
  resource_id = azurerm_container_registry.acr.id

  body = {
    properties = {
      anonymousPullEnabled = var.bool_anonymous_pull
    }
  }
}

다음 코드 조각은 기존 AzureRM 리소스에 대한 리소스 작업을 구성합니다.

resource "azapi_resource_action" "vm_shutdown" {
  type = "Microsoft.Compute/virtualMachines@2023-07-01"
  resource_id = azurerm_linux_virtual_machine.example.id
  action = "powerOff”
}

다음 코드 조각은 데이터 평면에서 프로비전되어 AzureRM 공급자에 현재 존재하지 않는 리소스를 구성합니다.

resource "azapi_data_plane_resource" "dataset" {
  type      = "Microsoft.Synapse/workspaces/datasets@2020-12-01"
  parent_id = trimprefix(data.azurerm_synapse_workspace.example.connectivity_endpoints.dev, "https://")
  name      = "example-dataset"
  body = {
    properties = {
      type = "AzureBlob",
      typeProperties = {
        folderPath = {
          value = "@dataset().MyFolderPath"
          type  = "Expression"
        }
        fileName = {
          value = "@dataset().MyFileName"
          type  = "Expression"
        }
        format = {
          type = "TextFormat"
        }
      }
      parameters = {
        MyFolderPath = {
          type = "String"
        }
        MyFileName = {
          type = "String"
        }
      }
    }
  }
}

실행 전 사용 예제

AzAPI의 기본 제공 실행 전 유효성 검사로 인해 terraform plan 동안 다음 코드 조각 오류가 발생합니다.

provider "azapi" {
  enable_preflight = true
}
resource "azapi_resource" "vnet" {
  type      = "Microsoft.Network/virtualNetworks@2024-01-01"
  parent_id = azapi_resource.resourceGroup.id
  name      = "example-vnet"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = [
          "10.0.0.0/160", # preflight will throw an error here
        ]
      }
    }
  }
}

Preflight는 공급자 플래그 뒤에 숨겨져 있지만, plan 단계에서 오류를 발생시키는 데 도움이 됩니다.

데이터 원본

AzAPI 공급자는 다음과 같은 다양한 유용한 데이터 원본을 지원합니다.

AzAPI 공급자를 사용한 인증

AzAPI 공급자는 AzureRM 공급자와 동일한 인증 방법을 사용하도록 설정합니다. 인증 옵션에 대한 자세한 내용은 Azure에 Terraform 인증을 참조하세요.

AzAPI 공급자의 환경 및 수명 주기

이 섹션에서는 AzAPI 공급자를 사용하는 데 도움이 되는 몇 가지 도구에 대해 설명합니다.

VS Code 확장 및 언어 서버

AzAPI VS Code 확장은 다음과 같은 이점을 통해 풍부한 제작 환경을 제공합니다.

• 사용 가능한 모든 리소스 종류 및 API 버전을 나열합니다.
• 모든 리소스에 대해 허용되는 속성 및 값의 자동 완성입니다.
• 속성을 마우스로 가리킬 때 힌트를 표시합니다.
• 구문 유효성 검사
• 코드 샘플을 사용하여 자동 완성

aztfmigrate 마이그레이션 도구

aztfmigrate 도구 AzAPI와 AzureRM 공급자 간에 기존 리소스를 마이그레이션할 수 있도록 설계되었습니다.

aztfmigrate 계획 및 마이그레이션의 두 가지 모드가 있습니다.

• 계획은 마이그레이션할 수 있는 AzAPI 리소스를 표시합니다.
• AzAPI 리소스를 HCL 파일과 상태 모두에서 AzureRM 리소스로 마이그레이션합니다.

aztfmigrate 마이그레이션 후에 Terraform 구성 및 상태가 실제 상태에 맞춰지도록 합니다. 마이그레이션을 완료한 후 실행 terraform plan 하여 상태 업데이트의 유효성을 검사하여 변경된 내용이 없는지 확인할 수 있습니다.

인프라에 대한 세분화된 컨트롤

AzAPI의 주요 이점 중 하나는 올바른 디자인 패턴에 맞게 구성을 미세 조정하는 기능입니다. 이 작업을 수행할 수 있는 방법에는 여러 가지가 있습니다.

공급자 함수

AzAPI(v2.0 이상)에는 다음과 같은 다양한 공급자 함수가있습니다.

retry 블록을 사용하여 사용자 정의 다시 시도 가능한 오류

AzAPI 공급자는 retry 블록을 통해 예상되는 경우에 오류를 처리할 수 있습니다. 예를 들어 리소스 만들기 시간 제한 문제가 발생할 수 있는 경우 다음 코드 블록이 도움이 될 수 있습니다.

resource "azapi_resource" "example" {
    # usual properties
    retry {
        interval_seconds     = 5
        randomization_factor = 0.5 # adds randomization to retry pattern
        multiplier           = 2 # if try fails, multiplies time between next try by this much
        error_message_regex  = ["ResourceNotFound"]
    }
    timeouts {
        create = "10m"
}

리소스 교체를 위한 트리거

AzAPI 공급자를 사용하면 리소스 교체를 위한 매개 변수를 구성할 수 있습니다.

replace_triggers_external_values

값이 변경되면 리소스를 바꿉니다. 예를 들어 SKU 또는 영역 변수를 수정해야 하는 경우 이 리소스가 다시 만들어집니다.

resource "azapi_resource" "example" {
  name      = var.name
  type      = "Microsoft.Network/publicIPAddresses@2023-11-01"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example"
  body      = properties = {
    sku   = var.sku
    zones = var.zones
  }
  replace_triggers_external_values = [
    var.sku,
    var.zones,
  ]
}

이 작업은 정의의 속성이 변경되는 경우 정책 할당과 같은 광범위한 리소스 집합에서 작동할 수 있습니다.

replace_triggers_refs

참조된 값이 변경되면 리소스를 바꿉니다. 예를 들어 SKU 이름 또는 계층이 수정된 경우 이 리소스가 다시 만들어집니다.

resource "azapi_resource" "example" {
  type      = "Microsoft.Relay/namespaces@2021-11-01"
  parent_id = azurerm_resource_group.example.id
  name      = "xxx"
  location  = "westus"
  body = {
    properties = {
    }
    sku = {
      name = "Standard"
      tier = "Standard"
    }
  }

  replace_triggers_refs = ["sku"]
}

다른 리소스의 SKU가 변경될 경우 교체가 트리거되지 않습니다.

다음 단계

• AzAPI 공급자를 사용하여 첫 번째 리소스 배포
• AzAPI 공급자를 사용하여 첫 번째 업데이트 리소스 배포
• AzAPI 공급자를 사용하여 첫 번째 리소스 작업 배포
• 공급자 레지스트리 방문