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

プレフライトはプロバイダー フラグの後ろに隠れていますが、plan ステージでエラーをスローするのに役立ちます。

データ ソース

AzAPI プロバイダーは、さまざまな便利なデータ ソースをサポートしています。

AzAPI プロバイダーを使用した認証

AzAPI プロバイダーは、AzureRM プロバイダーと同じ認証方法を有効にします。 認証オプションの詳細については、「Azure への Terraform の認証」を参照してください。

AzAPI プロバイダーのエクスペリエンスとライフサイクル

このセクションでは、AzAPI プロバイダーの使用に役立ついくつかのツールについて説明します。

VS Code 拡張機能と言語サーバー

AzAPI VS Code 拡張機能は、次の利点を備えた豊富なオーサリング エクスペリエンスを提供します。

• 使用可能なすべてのリソースの種類と API バージョンを一覧表示します。
• 任意のリソースで許可されるプロパティと値のオートコンプリート。
• プロパティの上にマウス ポインターを置くと、ヒントが表示されます。
• 構文検証
• コード サンプルを使用したオートコンプリート。

aztfmigrate 移行ツール

aztfmigrate ツール は、AzAPI プロバイダーと AzureRM プロバイダー間で既存のリソースを移行できるように設計されています。

aztfmigrate には、計画と移行の 2 つのモードがあります。

• プランでは、移行できる AzAPI リソースが表示されます。
• 移行では、HCL ファイルと状態の両方でAzAPI リソースを AzureRM リソースに移行します。

aztfmigrate、移行後に Terraform の構成と状態が実際の状態と一致することを保証します。 移行が完了したら、terraform plan を実行して状態の更新を検証し、何も変更されていないことを確認できます。

インフラストラクチャに対するきめ細かい制御

AzAPI の主な利点の 1 つは、適切な設計パターンに合わせて構成を微調整できることです。 これを行うには、いくつかの方法があります。

プロバイダー関数

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 プロバイダーを使用して最初のリソース アクションをデプロイする
• プロバイダー レジストリの にアクセスする