Terraform AzAPI sağlayıcısına genel bakış

AzAPI sağlayıcısı, Azure ARM REST API'lerinin üzerinde ince bir katmandır. Herhangi bir API sürümünü kullanarak herhangi bir Azure kaynak türünü yönetmenize olanak tanıyarak Azure içinde en son işlevleri kullanmanıza olanak tanır. AzAPI, kendi başına veya AzureRM sağlayıcısıyla birlikte kullanılmak üzere tasarlanmış birinci sınıf bir sağlayıcıdır.

AzAPI sağlayıcısını kullanmanın avantajları

AzAPI sağlayıcısı aşağıdaki avantajları sunar:

• Tüm Azure denetim düzlemi hizmetlerini destekler:
  • Önizleme hizmetleri ve özellikleri
  • Tüm API sürümleri
• Tam Terraform durum dosyası uygunluğu
  • Özellikler ve değerler duruma kaydedilir
• Swagger bağımlılığı yok
• Yaygın ve tutarlı Azure kimlik doğrulaması
• Yerleşik ön kontrol doğrulaması
• Altyapı geliştirme üzerinde ayrıntılı denetim
• Microsoft Terraform Visual Studio Code uzantısı

Kaynaklar

Güncelleştirme gerektirmeden tüm Azure kaynaklarını ve özelliklerini yönetmenize olanak sağlamak için AzAPI sağlayıcısı aşağıdaki genel kaynakları içerir:

Kaynak Adı	Açıklama
azapi_resource	Tüm Azure (denetim düzlemi) kaynaklarını (API) tam CRUD ile tam olarak yönetmek için kullanılır.    Örnek Kullanım Örnekleri:       Yeni önizleme hizmeti       Mevcut hizmete yeni özellik eklendi       ARM API aracılığıyla erişilebilen tüm Azure kaynakları
azapi_update_resource	Tam CRUD'a sahip olmayan kaynakları veya kaynakların bölümlerini yönetmek için kullanılır    Örnek Kullanım Örnekleri:       Mevcut bir hizmette yeni özellikleri güncelleştirme       DNS SOA kaydı gibi önceden oluşturulmuş alt kaynağı güncelleştirin.
azapi_resource_action	Bir kaynak üzerinde yaşam döngüsünü yönetmeden tek bir işlem gerçekleştirmek için kullanılır    Örnek Kullanım Örnekleri:       Sanal Makineyi Kapatma       Key Vault'a bir gizli eklemek
azapi_data_plane_resource	Azure veri düzlemi kaynaklarının belirli bir alt kümesini yönetmek için kullanılır    Örnek Kullanım Örnekleri:       KeyVault Sertifika İrtibatları       Synapse Çalışma Alanı Kitaplıkları

Veri düzlemi çerçevesinin nasıl çalıştığı ve denetim düzlemi kaynaklarından ne kadar parent_id farklı olduğu hakkında ayrıntılı bir açıklama için bkz. AzAPI veri düzlemi çerçevesini anlama.

Kullanım hiyerarşisi

Genel olarak, kullanım şu adımları izlemelidir:

1. içinde azapi_resourcemümkün olduğunca çok işlem gerçekleştirerek başlayın.
2. Kaynak türü azapi_resource içinde mevcut değilse ancak azapi_data_plane_resource tarafından desteklenen türlerden birine giriyorsa, bunun yerine o türü kullanın.
3. Kaynak AzureRM'de zaten varsa veya azapi_resource içinde erişilemeyen bir özelliği varsa, bu özelliklere erişmek için azapi_update_resource kullanın. azapi_resource veya azapi_data_plane_resource tarafından desteklenmeyen kaynaklar bu kaynak aracılığıyla güncellenemez.
4. Azure CRUD dostu bir kaynağı temel almayan bir eylem gerçekleştirmeye çalışıyorsanız, azapi_resource_action kadar basit değil, ama azapi_update_resource'den daha esnektir.

Kaynak yapılandırma örnekleri

Aşağıdaki kod parçacığı bir Azure kaynağını doğrudan ARM API aracılığıyla yapılandırıyor:

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

Aşağıdaki kod parçacığı, AzureRM'den var olan bir kaynak için önizleme özelliğini yapılandırmaktadır:

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

Aşağıdaki kod parçacığı, mevcut bir AzureRM kaynağında bir kaynak eylemi yapılandırıyor:

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

Aşağıdaki kod parçacığı, veri düzleminde sağlandığı için şu anda AzureRM sağlayıcısında mevcut olmayan bir kaynağı yapılandırıyor:

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

Uçuş öncesi kullanım örneği

AzAPI'nin yerleşik denetim öncesi doğrulaması nedeniyle aşağıdaki kod parçacığı, terraform plan sırasında hatalara neden oluyor.

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

Etkinleştirildiğinde, ön kontrol işlemleri terraform plan sırasında yapılandırma hatalarını ortaya çıkarır, uygulama zamanında değil.

Veri Kaynakları

AzAPI sağlayıcısı çeşitli yararlı veri kaynaklarını destekler:

Veri Kaynağı Adı	Açıklama
azapi_resource	Herhangi bir Azure (denetim düzlemi) kaynağından (API) bilgi okumak için kullanılır.    Örnek Kullanım Örnekleri:       Yeni önizleme hizmeti       Mevcut hizmete yeni özellik eklendi       ARM API aracılığıyla erişilebilen tüm Azure kaynakları
azapi_client_config	Abonelik kimliği ve kiracı kimliği gibi istemci bilgilerine erişin.
azapi_resource_action	Bir kaynakta yaşam döngüsünü yönetmeden tek bir okuma işlemi gerçekleştirmek için kullanılır    Örnek Kullanım Örnekleri:       Liste Anahtarları       VM'nin durumunu okuma
azapi_data_plane_resource	Azure veri düzlemi kaynaklarının belirli bir alt kümesine erişmek için kullanılır    Örnek Kullanım Örnekleri:       KeyVault Sertifika İrtibatları       Synapse Çalışma Alanı Kitaplıkları
azapi_resource_id	Bir kaynağın kaynak kimliğine erişerek abonelik kimliği, üst kimlik, kaynak grubu adı ve kaynak adı gibi bilgileri çıkartma yeteneğine sahipsiniz.
azapi_resource_list	Belirli bir üst kaynak kimliği altındaki tüm kaynakları listeleyin.    Örnek Kullanım Örnekleri:       Abonelik/ kaynak grubu altındaki kaynaklar       Sanal ağ altındaki alt ağlar

JMESPath filtrelemesi ile azapi_resource_list kullanan uygulamalı bir örnek için AzAPI Terraform sağlayıcısı ile Azure kaynaklarını listeleme'ye bakın.

Mevcut bir kaynağı azapi_resource veri kaynağıyla okuma

azapi_resource veri kaynağı herhangi bir Azure kaynağının geçerli durumunu okur ve özelliklerini output özniteliği aracılığıyla kullanıma sunar. AzureRM sağlayıcısının kullanıma sunmadığı bir özelliğe ihtiyacınız olduğunda bu özelliği kullanın:

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
}

response_export_values ve JMESPath kullanın

response_export_values ham ARM API yanıtından ayıklanan ve özniteliğinde output kullanılabilir duruma gelen özellikleri denetler. Bir liste veya harita kabul eder:

• Liste: Ayıklanması gereken JSON özellik yollarını belirtin. Tam yanıt gövdesini dışarı aktarmak için kullanın ["*"] .
• Harita: Yanıtı filtrelemek ve yeniden şekillendirmek için JMESPath ifadelerinden yararlanın. Anahtar, çıkış alanı adıdır; değeri JMESPath sorgusudur.

Harita formu, çıktıyı dönüştürmeniz gereken liste yanıtları ve durumlar için tercih edilir.

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

Detaylı bir kılavuz için bkz. AzAPI Terraform sağlayıcısıyla Azure kaynaklarını listele.

AzAPI sağlayıcısını kullanarak kimlik doğrulaması

AzAPI sağlayıcısı, AzureRM sağlayıcısıyla aynı kimlik doğrulama yöntemlerini etkinleştirir. Kimlik doğrulama seçenekleri hakkında daha fazla bilgi için bkz . Terraform'un Azure'da kimliğini doğrulama.

AzAPI sağlayıcısının deneyimi ve yaşam döngüsü

Bu bölümde, AzAPI sağlayıcısını kullanmanıza yardımcı olacak bazı araçlar açıklanmaktadır.

VS Code uzantısı ve Dil Sunucusu

Microsoft Terraform VS Code uzantısı hem AzureRM hem de AzAPI sağlayıcıları için zengin bir yazma deneyimi sağlar, örneğin:

• Kullanılabilir tüm kaynak türlerini ve API sürümlerini listeleyin.
• Herhangi bir kaynak için izin verilen özelliklerin ve değerlerin otomatik olarak derlemesi.
• Bir özelliğin üzerine gelindiğinde ipuçlarını gösterin.
• Söz dizimi doğrulama
• Kod örnekleriyle otomatik tamamlama.

Uzantı ayrıca AzAPI olarak yapıştır (ARM JSON'yi azapi_resource bloklarına dönüştürür), Azure aztfexport aracılığıyla kaynak dışarı aktarmayı, AzureRM-AzAPI geçişini ve denetim öncesi doğrulamayı destekler. Tam kılavuz için bkz. Microsoft Terraform VS Code uzantısını kullanma.

aztfmigrate geçiş aracı

aztfmigrate aracı, mevcut kaynakları AzAPI ve AzureRM sağlayıcıları arasında geçirmeye yardımcı olmak için tasarlanmıştır.

aztfmigrate iki modu mevcuttur: planlama ve geçiş.

• Plan, geçirilebilen AzAPI kaynaklarını görüntüler.
• AzAPI kaynaklarını, hem HCL dosyalarında hem de durum bilgisinde AzureRM kaynaklarına geçirir.

aztfmigrate, geçiş sonrasında Terraform yapılandırmanızın ve durumunuzun gerçek durumunuzla uyumlu olmasını sağlar. Hiçbir değişiklik yapılmadığını onaylamak için geçişi tamamladıktan sonra çalıştırarak terraform plan durum güncelleştirmesini doğrulayabilirsiniz.

Adım adım izlenecek yol için bkz. Kaynakları AzAPI'den AzureRM'ye geçirme.

Mevcut Azure kaynaklarını içeri aktarma

Var olan bir Azure kaynağını yeniden oluşturmadan AzAPI yönetimi altına getirmek için import bloğunu (Terraform 1.5 ve üzeri) veya terraform import komutunu kullanın. Kaynak kimliği api sürümünü sorgu parametresi olarak içermelidir:

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

Mevcut Azure altyapısından aynı anda birden çok kaynağı içeri aktarmak için, hem HCL yapılandırmasını hem de içeri aktarma bloklarını otomatik olarak oluşturan Azure Export for Terraform (aztfexport) kullanın.

Altyapı üzerinde ayrıntılı kontroller

AzAPI'nin en önemli avantajlarından biri, yapılandırmanızı doğru tasarım desenlerine uyacak şekilde hassas bir şekilde ayarlama özelliğidir. Bunu yapmanın birkaç yolu vardır:

Sağlayıcı yapılandırma seçenekleri

AzAPI sağlayıcı bloğu, yapılandırmadaki tüm kaynaklara genel olarak uygulanan çeşitli ayarları kabul eder:

Option	Açıklama
enable_preflight	Planlama aşamasında ön kontrol doğrulamasını etkinleştirir. Varsayılan olarak false değerini alır. Ayrıntılar için bkz. AzAPI Terraform sağlayıcısında denetim öncesi doğrulamayı etkinleştirme .
ignore_no_op_changes	Yapılandırma ve normalleştirilmiş API yanıtları arasındaki no-op farklardan kaynaklanan plan süresi gürültüsünü bastırır. Varsayılan olarak true değerini alır.
disable_default_output	Eğer true olarak ayarlanırsa ve response_export_values belirtilmemişse, salt okunur özelliklerin otomatik çıkışı devre dışı bırakılır. Varsayılan olarak false değerini alır.
default_location	Açıkça belirtmeyen tüm kaynaklar için bir varsayılan location ayarlar.
default_tags	Tüm kaynaklara uygulanan varsayılan etiketleri ayarlar. Kaynak düzeyi tags bu varsayılanları geçersiz kılar.
skip_provider_registration	Otomatik kaynak sağlayıcı kaydını atlar. Kısıtlı ortamlarda true olarak ayarlayın.

Sağlayıcı yapılandırma seçeneklerinin tam listesi için bkz. AzAPI sağlayıcı şeması.

Ön denetimi etkinleştirmeye yönelik bir kılavuz için bkz. AzAPI Terraform sağlayıcısında denetim öncesi doğrulamayı etkinleştirme.

Sağlayıcı işlevleri

AzAPI v2.0 ve üzeri birkaç sağlayıcı işlevi içerir:

İşlev Adı	Açıklama
build_resource_id	Verilen üst kimlik, kaynak türü ve kaynak adına göre bir Azure kaynak kimliği oluşturur. Belirli bir kapsamda üst düzey ve iç içe yerleştirilmiş kaynaklar için kaynak kimlikleri oluşturmak için kullanışlıdır.
extension_resource_id	Temel kaynak kimliği, kaynak türü ve daha fazla kaynak ismiyle bir Azure uzantısı kaynak kimliği oluşturur.
management_group_resource_id	Azure yönetim grubu adı, kaynak türü ve kaynak adları verilerek bir yönetim grubu kapsamı kaynak kimliği oluşturur.
parse_resource_id	Bu işlev bir Azure kaynak kimliğini ve kaynak türünü alır ve kimliği abonelik kimliği, kaynak grubu adı, sağlayıcı ad alanı ve diğer bölümler gibi tek tek bileşenlerine ayrıştırır.
resource_group_resource_id	Verilen abonelik kimliği, kaynak grubu adı, kaynak türü ve kaynak isimleri ile bir Azure kaynak grubu kapsamı kaynak kimliği oluşturur.
subscription_resource_id	Abonelik kimliği, kaynak türü ve kaynak adları verilen bir Azure abonelik kapsamı kaynak kimliği oluşturur.
tenant_resource_id	Kaynak türü ve kaynak adlarına göre bir Azure kiracı kapsamı kaynak kimliği oluşturur.

Kullanıcı tanımlı retry blok ile yeniden denenebilir hatalar

AzAPI sağlayıcısı beklenen hataları retry bloğu içinden işler. Örneğin, bir kaynak oluşturma zaman aşımıyla karşılaştığında yeniden denemek için aşağıdaki yapılandırmayı kullanın:

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 şu retry öznitelikleri kabul eder:

Attribute	Açıklama
error_message_regex	Gerekli. Hata iletileriyle eşleşen normal ifadelerin listesi. herhangi bir ifade eşleştiğinde istek yeniden denenir.
interval_seconds	Yeniden denemeler arasında temel bekleme süresi. Varsayılan olarak 10 değerini alır.
max_interval_seconds	Yeniden denemeler arasındaki en uzun bekleme süresi. Varsayılan olarak 180 değerini alır.
multiplier	Her başarısız denemeden sonra aralığa uygulanan çarpan. Varsayılan olarak 1.5 değerini alır.
randomization_factor	Gök gürültüsü sürü desenlerini önlemek için yeniden deneme aralığına titreme ekler. Varsayılan olarak 0.5 değerini alır.

retry ile timeouts bloğunu birleştirerek toplam yeniden deneme süresi için bir üst sınır belirleyin.

timeouts {
  create = "10m"
}

Kısa ömürlü kaynaklar ve salt yazma özellikleri

AzAPI v2.x, sensitive_body özniteliği aracılığıyla azapi_resource üzerinden salt yazma bağımsız değişkenlerini (Terraform 1.11 ve üzeri) destekler. Sadece yazılabilir özellikler ARM API’sine gönderilir ancak Terraform durumunda depolanmaz; bu da gizli bilgiler ve kimlik bilgileri için faydalıdır.

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

Yalnızca yazma özelliklerinin API'ye ne zaman yeniden gönderileceğini kontrol etmek için sensitive_body_version kullanın (örneğin, kimlik bilgilerini döndürürken).

Kaynak değiştirme tetikleyicileri

AzAPI sağlayıcısı, kaynak değişimi için parametreleri yapılandırmanıza olanak tanır:

replace_triggers_external_values

Bir değer değişirse kaynağı değiştirir. Örneğin, SKU veya bölge değişkenleri değiştirilecekse, bu kaynak yeniden oluşturulur:

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

Bu tetikleyici, tanımın özellikleri değiştiğinde ilke ataması gibi geniş bir kaynak kümesinde çalışır.

replace_triggers_refs

Başvuruda bulunan değer değişirse kaynağın yerini alır. Örneğin, SKU adı veya katmanı değiştirilmişse bu kaynak yeniden oluşturulur:

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

Bu, farklı bir kaynağın SKU'su değişirse bir değiştirme tetiklemez.

Sonraki adımlar

• AzureRM ve AzAPI Terraform sağlayıcıları arasında seçim yapma
• AzAPI veri düzlemi çerçevesini anlama
• İlk kaynağınızı AzAPI sağlayıcısıyla dağıtma
• İlk Güncelleştirme Kaynağınızı AzAPI sağlayıcısıyla dağıtma
• İlk kaynak eyleminizi AzAPI sağlayıcısıyla dağıtma
• AzAPI sağlayıcısıyla kaynak eylemleri gerçekleştirme
• AzAPI
• AzAPI sağlayıcısını kullanarak Azure kaynaklarını listele
• Denetim öncesi doğrulamayı etkinleştirme
• AzAPI sağlayıcı işlevlerini kullanma
• Azure, AzureRM ve AzAPI arasındaki göç yolları
• Sağlayıcı kayıt defteri ziyaret edin