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 untuk 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 Visual Studio Code yang Kuat

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
      Fitur/layanan yang ada saat ini tidak tercakup
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 telah 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

Hierarki penggunaan

Secara keseluruhan, penggunaan harus mengikuti langkah-langkah berikut:

  1. Selalu disarankan untuk mulai 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 yang saat ini tidak ada di penyedia 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"
    }
  }
}

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

Preflight disembunyikan di balik fitur penyedia tetapi akan membantu menghasilkan kesalahan pada tahap plan.

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
      Fitur/layanan yang ada saat ini tidak tercakup
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 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

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 AzAPI VS Code memberikan pengalaman penulisan yang kaya dengan manfaat berikut:

  • Mencantumkan semua jenis sumber daya dan versi API yang tersedia. Mencantumkan semua jenis sumber daya yang tersedia
  • Penyelesaian otomatis properti dan nilai yang diizinkan untuk sumber daya apa pun. Mencantumkan properti yang diizinkan
  • Perlihatkan petunjuk saat menggerakkan kursor ke properti. Perlihatkan petunjuk saat mengarahkan kursor ke properti
  • Validasi sintaks Validasi sintaks
  • Pelengkapan otomatis dengan sampel kode. Penyelesaian otomatis dengan sampel kode

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 melihat bahwa tidak ada yang berubah.

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 di mana Anda dapat melakukan ini:

Fungsi penyedia

AzAPI (v2.0 dan yang lebih baru) memiliki banyak 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 Membuat ID sumber daya ekstensi Azure yang diberi ID sumber daya dasar, jenis sumber daya, dan nama sumber daya tambahan.
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 pada blok retry

Penyedia AzAPI dapat menangani kesalahan jika diperlukan melalui blok retry. Misalnya, jika sumber daya mungkin mengalami masalah waktu habis buat, blok kode berikut dapat membantu:

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

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

Ini dapat bekerja di serangkaian sumber daya yang luas, yaitu penetapan kebijakan saat 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

  • Last updated on