Gambaran umum penyedia Terraform AzAPI

Penyedia AzAPI adalah lapisan tipis di atas AZURE ARM REST API. Ini memungkinkan Anda mengelola jenis sumber daya Azure apa pun menggunakan versi API apa pun, memungkinkan Anda menggunakan fungsionalitas terbaru dalam Azure. AzAPI adalah penyedia kelas satu yang dirancang untuk digunakan sendiri atau bersama dengan penyedia AzureRM.

Manfaat menggunakan penyedia AzAPI

Penyedia AzAPI menampilkan manfaat berikut:

• Mendukung semua layanan sarana kontrol Azure:
  • Pratinjau layanan dan fitur
  • Semua versi API
• Keakuratan file status Terraform penuh
  • Properti dan nilai disimpan ke status
• Tidak ada dependensi pada Swagger
• Autentikasi Azure umum dan konsisten
• Validasi pra-terbang terintegrasi
• Pengendalian terperinci atas pengembangan infrastruktur
• Ekstensi Microsoft Terraform Visual Studio Code

Sumber

Untuk memungkinkan Anda mengelola semua sumber daya dan fitur Azure tanpa memerlukan pembaruan, penyedia AzAPI menyertakan sumber daya generik berikut:

Nama Sumber Daya	Deskripsi
azapi_resource	Digunakan untuk sepenuhnya mengelola sumber daya (API) Azure (sarana kontrol) dengan CRUD penuh.    Contoh Kasus Penggunaan:       Layanan pratinjau baru       Fitur baru ditambahkan ke layanan yang sudah ada       Sumber daya Azure apa pun yang dapat diakses melalui ARM API
azapi_update_resource	Digunakan untuk mengelola sumber daya atau bagian sumber daya yang tidak memiliki CRUD penuh    Contoh Kasus Penggunaan:       Memperbarui properti baru pada layanan yang sudah ada       Perbarui sumber daya anak yang dibuat sebelumnya - seperti catatan DNS SOA.
azapi_resource_action	Digunakan untuk melakukan satu operasi pada sumber daya tanpa mengelola siklus hidupnya    Contoh Kasus Penggunaan:       Mematikan Mesin Virtual       Menambahkan rahasia ke Key Vault
azapi_data_plane_resource	Digunakan untuk mengelola subset sumber daya sarana data Azure tertentu    Contoh Kasus Penggunaan:       Kontak Sertifikat di KeyVault       Pustaka Ruang Kerja Synapse

Untuk penjelasan terperinci tentang cara kerja kerangka kerja sarana data dan perbedaannya parent_id dengan sumber daya sarana kontrol, lihat Memahami kerangka kerja sarana data AzAPI.

Hierarki penggunaan

Secara keseluruhan, penggunaan harus mengikuti langkah-langkah berikut:

1. Mulailah dengan melakukan operasi sebanyak mungkin dalam azapi_resource.
2. Jika jenis sumber daya tidak ada di dalam azapi_resource tetapi berada di bawah salah satu jenis yang didukung oleh azapi_data_plane_resource, gunakan sebagai gantinya.
3. Jika sumber daya sudah ada di AzureRM atau memiliki properti yang tidak dapat diakses dalam azapi_resource, gunakan azapi_update_resource untuk mengakses properti tertentu ini. Sumber daya yang azapi_resource atau azapi_data_plane_resource tidak mendukung tidak dapat diperbarui melalui sumber daya ini.
4. Jika Anda mencoba melakukan tindakan yang tidak didasarkan pada sumber daya ramah Azure CRUD, azapi_resource_action kurang mudah daripada azapi_update_resource tetapi lebih fleksibel.

Contoh konfigurasi sumber daya

Cuplikan kode berikut mengonfigurasi sumber daya Azure langsung melalui ARM API:

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

Cuplikan kode berikut mengonfigurasi properti pratinjau untuk sumber daya yang ada dari 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
    }
  }
}

Cuplikan kode berikut mengonfigurasi tindakan sumber daya pada sumber daya AzureRM yang ada:

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

Cuplikan kode berikut mengonfigurasi sumber daya yang saat ini tidak ada di penyedia AzureRM karena disediakan di bidang data:

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

Contoh penggunaan preflight

Kesalahan cuplikan kode di bawah ini terjadi pada tahap terraform plan karena validasi preflight bawaan AzAPI:

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
        ]
      }
    }
  }
}

Saat diaktifkan, preflight mengidentifikasi kesalahan konfigurasi selama terraform plan bukan pada saat penerapan.

Sumber Data

Penyedia AzAPI mendukung berbagai sumber data yang berguna:

Nama Sumber Data	Deskripsi
azapi_resource	Digunakan untuk membaca informasi dari sumber daya (API) Azure (sarana kontrol) apa pun.    Contoh Kasus Penggunaan:       Layanan pratinjau baru       Fitur baru ditambahkan ke layanan yang sudah ada       Sumber daya Azure apa pun yang dapat diakses melalui ARM API
azapi_client_config	Akses informasi klien seperti ID langganan dan ID penyewa.
azapi_resource_action	Digunakan untuk melakukan operasi baca tunggal pada sumber daya tanpa mengelola siklus hidupnya    Contoh Kasus Penggunaan:       Daftar Kunci       Status VM terbaca
azapi_data_plane_resource	Digunakan untuk mengakses subset tertentu sarana data Azure    Contoh Kasus Penggunaan:       Kontak Sertifikat di KeyVault       Pustaka Ruang Kerja Synapse
azapi_resource_id	Akses ID sumber daya sumber daya, dengan kemampuan untuk menghasilkan informasi seperti ID langganan, ID induk, nama grup sumber daya, dan nama sumber daya.
azapi_resource_list	Cantumkan semua sumber daya di bawah ID sumber daya induk tertentu.    Contoh Kasus Penggunaan:       Sumber daya di bawah grup langganan/sumber daya       Subnet di bawah jaringan virtual

Untuk contoh langsung menggunakan azapi_resource_list dengan pemfilteran JMESPath, lihat daftar sumber daya Azure dengan penyedia AzAPI Terraform.

Membaca sumber daya yang sudah ada menggunakan sumber data azapi_resource

Sumber data azapi_resource membaca status sumber daya Azure saat ini dan mengekspos propertinya melalui atribut output. Gunakan saat Anda memerlukan properti yang tidak diekspos penyedia AzureRM:

data "azapi_resource" "aks" {
  type      = "Microsoft.ContainerService/managedClusters@2024-02-01"
  resource_id = azurerm_kubernetes_cluster.example.id

  # Extract the OIDC issuer URL, not exposed by azurerm_kubernetes_cluster
  response_export_values = ["properties.oidcIssuerProfile.issuerURL"]
}

output "oidc_issuer_url" {
  value = data.azapi_resource.aks.output.properties.oidcIssuerProfile.issuerURL
}

Gunakan response_export_values dan JMESPath

response_export_values mengontrol properti mana yang diekstrak dari respons ARM API mentah dan tersedia di output atribut . Ini menerima daftar atau peta:

• Daftar: Tentukan jalur properti JSON untuk diekstrak. Gunakan ["*"] untuk mengekspor isi respons penuh.
• Peta: Gunakan ekspresi JMESPath untuk memfilter dan membentuk ulang respons. Kuncinya adalah nama bidang output; nilainya adalah kueri JMESPath.

Formulir peta lebih disukai untuk respons daftar dan kasus di mana Anda perlu mengubah output:

data "azapi_resource_list" "storage_accounts" {
  type      = "Microsoft.Storage/storageAccounts@2023-01-01"
  parent_id = azurerm_resource_group.example.id

  response_export_values = {
    "names"     = "value[].name"
    "locations" = "value[].location"
  }
}

Untuk panduan lengkap, lihat Daftar sumber daya Azure dengan penyedia AzAPI Terraform.

Autentikasi menggunakan penyedia AzAPI

Penyedia AzAPI memungkinkan metode autentikasi yang sama dengan penyedia AzureRM. Untuk informasi selengkapnya tentang opsi autentikasi, lihat Mengautentikasi Terraform ke Azure.

Pengalaman dan siklus hidup penyedia AzAPI

Bagian ini menjelaskan beberapa alat untuk membantu Anda menggunakan penyedia AzAPI.

Ekstensi Visual Studio Code dan Server Bahasa

Ekstensi Microsoft Terraform VS Code memberikan pengalaman penulisan yang kaya untuk penyedia AzureRM dan AzAPI, termasuk:

• Mencantumkan semua jenis sumber daya dan versi API yang tersedia.
• Fitur pelengkapan otomatis untuk properti dan nilai yang diizinkan pada setiap sumber daya.
• Perlihatkan petunjuk saat menggerakkan kursor ke properti.
• Validasi sintaks
• Pelengkapan otomatis dengan sampel kode.

Ekstensi ini juga mendukung paste-as-AzAPI (mengonversi ARM JSON ke blok azapi_resource), Azure ekspor sumber daya melalui aztfexport, migrasi AzureRM-ke-AzAPI, dan validasi preflight. Untuk panduan lengkap, lihat Gunakan ekstensi Microsoft Terraform VS Code.

alat migrasi aztfmigrate

Alat aztfmigrate dirancang untuk membantu memigrasikan sumber daya yang ada antara penyedia AzAPI dan AzureRM.

aztfmigrate memiliki dua mode: merencanakan dan memigrasikan:

• Rencana menampilkan sumber daya AzAPI yang dapat dimigrasikan.
• Migrasi memigrasikan sumber daya AzAPI ke sumber daya AzureRM dalam file HCL dan state.

aztfmigrate memastikan setelah migrasi bahwa konfigurasi dan status Terraform Anda selaras dengan status Anda yang sebenarnya. Anda dapat memvalidasi pembaruan ke status dengan menjalankan terraform plan setelah menyelesaikan migrasi untuk mengonfirmasi tidak ada perubahan yang terjadi.

Untuk panduan langkah demi langkah, lihat Memigrasikan sumber daya dari AzAPI ke AzureRM.

Mengimpor sumber daya Azure yang ada

Untuk membawa sumber daya Azure yang ada di bawah manajemen AzAPI tanpa membuatnya kembali, gunakan blok import (Terraform 1.5 dan yang lebih baru) atau perintah terraform import. ID sumber daya harus menyertakan versi API sebagai parameter kueri:

import {
  to = azapi_resource.example
  id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Network/virtualNetworks/example-vnet?api-version=2023-11-01"
}

resource "azapi_resource" "example" {
  type      = "Microsoft.Network/virtualNetworks@2023-11-01"
  name      = "example-vnet"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = ["10.0.0.0/16"]
      }
    }
  }
}

Untuk mengimpor beberapa sumber daya sekaligus dari infrastruktur Azure yang ada, gunakan Azure Ekspor untuk Terraform (aztfexport), yang menghasilkan konfigurasi HCL dan blok impor secara otomatis.

Kontrol terperinci atas infrastruktur

Salah satu manfaat utama AzAPI adalah melalui kemampuannya untuk menyempurnakan konfigurasi Anda agar sesuai dengan pola desain yang tepat. Ada beberapa cara untuk melakukan ini:

Opsi konfigurasi penyedia

Blok penyedia AzAPI menerima beberapa pengaturan yang berlaku secara global di semua sumber daya dalam konfigurasi:

Option	Deskripsi
enable_preflight	Mengaktifkan validasi preflight pada waktu rencana. Secara default menjadi false. Lihat Mengaktifkan validasi preflight di penyedia AzAPI Terraform untuk detailnya.
ignore_no_op_changes	Mengurangi kebisingan waktu perencanaan dari perbedaan no-op antara konfigurasi dan respons API yang dinormalisasi. Secara default menjadi true.
disable_default_output	Saat diatur ke true, menonaktifkan keluaran otomatis properti baca-saja ketika response_export_values tidak ditentukan. Secara default menjadi false.
default_location	Mengatur default location untuk semua sumber daya yang tidak menentukan satu secara eksplisit.
default_tags	Mengatur tag default yang diterapkan ke semua sumber daya. Tingkat tags sumber daya menggantikan default ini.
skip_provider_registration	Melewatkan registrasi penyedia sumber daya secara otomatis. Atur ke true di lingkungan terbatas.

Untuk daftar lengkap opsi konfigurasi penyedia, lihat skema penyedia AzAPI.

Untuk panduan mengaktifkan preflight, lihat Mengaktifkan validasi preflight di penyedia AzAPI Terraform.

Fungsi penyedia

AzAPI v2.0 dan yang lebih baru mencakup beberapa fungsi penyedia:

Nama Fungsi	Deskripsi
build_resource_id	Membuat ID sumber daya Azure yang diberi ID induk, jenis sumber daya, dan nama sumber daya. Berguna untuk membuat ID sumber daya untuk sumber daya tingkat atas dan berlapis dalam cakupan tertentu.
extension_resource_id	Membangun ID sumber daya ekstensi Azure dengan menggunakan ID sumber daya dasar sebagai acuan, jenis sumber daya, serta nama-nama sumber daya lainnya.
management_group_resource_id	Membuat ID sumber daya cakupan grup manajemen Azure dengan nama grup manajemen, jenis sumber daya, dan nama sumber daya.
parse_resource_id	Fungsi ini mengambil ID sumber daya Azure dan jenis sumber daya dan mengurai ID ke dalam komponen individualnya seperti ID langganan, nama grup sumber daya, namespace layanan penyedia, dan bagian lainnya.
resource_group_resource_id	Membuat ID sumber daya cakupan grup sumber daya Azure yang diberi ID langganan, nama grup sumber daya, jenis sumber daya, dan nama sumber daya.
subscription_resource_id	Membuat ID sumber daya cakupan langganan Azure dengan id langganan, jenis sumber daya, dan nama sumber daya.
tenant_resource_id	Membuat ID sumber daya untuk cakupan penyewa Azure dengan jenis sumber daya dan nama sumber daya.

Kesalahan yang dapat diulang yang ditentukan pengguna dengan blok retry

Penyedia AzAPI menangani kesalahan yang diharapkan melalui blok retry. Misalnya, gunakan konfigurasi berikut untuk mencoba kembali saat sumber daya mengalami batas waktu pembuatan:

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

Blok retry menerima atribut-atribut berikut:

Attribute	Deskripsi
error_message_regex	Required. Daftar ekspresi reguler yang dicocokkan dengan pesan kesalahan. Permintaan dicoba kembali ketika ekspresi apa pun cocok.
interval_seconds	Waktu tunggu dasar antara percobaan ulang. Secara default menjadi 10.
max_interval_seconds	Waktu tunggu maksimum antara percobaan ulang. Secara default menjadi 180.
multiplier	Pengali diterapkan pada interval setelah setiap upaya yang gagal. Secara default menjadi 1.5.
randomization_factor	Menambahkan jitter ke interval pengulangan untuk menghindari pola stampede. Secara default menjadi 0.5.

Gabungkan retry dengan blok timeouts untuk menetapkan batas atas durasi total pengulangan:

timeouts {
  create = "10m"
}

Sumber daya sementara dan properti tulis-saja

AzAPI v2.x mendukung argumen tulis-saja (Terraform 1.11 dan yang lebih baru) melalui atribut sensitive_body di azapi_resource. Properti khusus tulis dikirim ke ARM API tetapi tidak disimpan dalam status Terraform, yang berguna untuk rahasia dan kredensial:

resource "azapi_resource" "example" {
  type      = "Microsoft.SomeService/resources@2024-01-01"
  name      = "example"
  parent_id = azurerm_resource_group.example.id

  body = {
    properties = {
      name = "example"
    }
  }

  # Write-only — not stored in state
  sensitive_body = {
    properties = {
      adminPassword = var.admin_password
    }
  }
}

Gunakan sensitive_body_version untuk mengontrol kapan properti hanya-tulis dikirim ulang ke API (misalnya, saat memutar kredensial).

Pemicu untuk penggantian sumber daya

Penyedia AzAPI memungkinkan Anda mengonfigurasi parameter untuk penggantian sumber daya:

replace_triggers_external_values

Mengganti sumber daya jika nilai berubah. Misalnya, jika variabel SKU atau zona akan dimodifikasi, sumber daya ini akan dibuat ulang:

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,
  ]
}

Pemicu ini berfungsi di serangkaian sumber daya yang luas—misalnya, penetapan kebijakan ketika properti definisi berubah.

replace_triggers_refs

Mengganti sumber daya jika nilai yang dirujuk berubah. Misalnya, jika nama atau tingkat SKU dimodifikasi, sumber daya ini akan dibuat ulang:

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

Ini tidak akan memicu penggantian jika SKU sumber daya yang berbeda berubah.

Langkah berikutnya

• Pilih antara penyedia AzureRM dan AzAPI Terraform
• Memahami kerangka kerja sarana data AzAPI
• Menyebarkan sumber daya pertama Anda dengan penyedia AzAPI
• Menyebarkan Sumber Daya Pembaruan pertama Anda dengan penyedia AzAPI
• Menyebarkan aksi sumber daya pertama Anda dengan penyedia AzAPI
• Melakukan tindakan sumber daya dengan penyedia AzAPI
• Kelola sumber daya sarana data Azure dengan AzAPI
• Daftar sumber daya Azure dengan penyedia AzAPI
• Aktifkan validasi pra-penerbangan
• Menggunakan fungsi penyedia AzAPI
• jalur migrasi antara Azure, AzureRM, dan AzAPI
• Kunjungi daftar penyedia