次の方法で共有


Terraform AzAPI プロバイダーの概要

AzAPI プロバイダーは、 Azure ARM REST API の上にある薄いレイヤーです。 任意の API バージョンを使用して任意の Azure リソース タイプを管理できるため、Azure 内で最新の機能を利用できます。 AzAPI は、単独でも AzureRM プロバイダーとの連携でも使用できるように設計されている、優秀なプロバイダーです。

AzAPI プロバイダーを使用する利点

AzAPI プロバイダーには、次のような利点があります。

  • すべての Azure コントロール プレーン サービスをサポートします。
    • プレビュー サービスと機能
    • すべての API のバージョン
  • 完全な Terraform 状態ファイルの忠実性
    • プロパティと値はステートに保存される
  • Swagger への依存関係なし
  • 一般的で一貫性のある Azure 認証
  • 組み込みのプレフライト検証
  • インフラストラクチャ開発をきめ細かく制御する
  • 堅牢な VS Code 拡張機能

リソース

更新を必要とせずにすべての Azure リソースと機能を管理できるようにするために、AzAPI プロバイダーには次の汎用リソースが含まれています。

リソース名 説明
azapi_resource 完全な CRUD を使用して Azure (コントロール プレーン) リソース (API) を完全に管理するために使用されます。
   利用事例の例
      新しいプレビュー サービス
      既存のサービスに追加された新機能
      現在対象外の既存の機能とサービス
azapi_update_resource 完全な CRUD を持たないリソースまたはリソースの一部を管理するために使用される
   ユース ケースの例:
      既存のサービスの新しいプロパティを更新する
      DNS SOA レコードなど、事前に作成された子リソースを更新します。
azapi_resource_action リソースのライフサイクルを管理せずに、リソースに対して単一の操作を実行するために使用されます
   使用例:
      仮想マシンをシャットダウンする
      Key Vault にシークレットを追加する
azapi_data_plane_resource Azure データ プレーン リソースの特定のサブセットを管理するために使用されます
   ユースケースの例
      KeyVault 証明書の連絡先
      Synapse ワークスペース ライブラリ

使用階層

全体として、使用するには次の手順に従う必要があります。

  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_actionazapi_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_resource 任意の Azure (コントロール プレーン) リソース (API) から情報を読み取るために使用されます。
   使用例:
      新しいプレビュー サービス
      既存のサービスに追加された新機能
      現在対象外の既存の機能とサービス
azapi_client_config サブスクリプション ID やテナント ID などのクライアント情報にアクセスします。
azapi_resource_action リソースのライフサイクルを管理せずに、リソースに対して単一の読み取り操作を実行するために使用されます
   使用例:
      キーの一覧表示
      VM の状態を読み取る
azapi_data_plane_resource Azure データ プレーン リソースの 特定のサブセット にアクセスするために使用されます
   ユースケースの具体例:
      KeyVault 証明書の連絡先
      Synapse ワークスペース ライブラリ
azapi_resource_id サブスクリプション ID、親 ID、リソース グループ名、リソース名などの情報を出力する機能を使用して、リソースのリソース ID にアクセスします。
azapi_resource_list 特定の親リソース ID の下にあるすべてのリソースを一覧表示します。
   使用例
      サブスクリプション/リソース グループの下のリソース
      仮想ネットワークの下のサブネット

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 以降) には、多くのプロバイダー関数が用意されています。

関数名 説明
build_resource_id 親 ID、リソースの種類、およびリソース名を指定して、Azure リソース ID を構築します。
特定のスコープ内で最上位レベルおよび入れ子になったリソースのリソース ID を作成する場合に便利です。
extension_resource_id 基本リソース ID、リソースの種類、および追加のリソース名を指定して、Azure 拡張機能リソース ID を構築します。
management_group_resource_id 管理グループ名、リソースの種類、およびリソース名を指定して、Azure 管理グループ スコープ リソース ID を構築します。
parse_resource_id この関数は、Azure リソース ID とリソースの種類を受け取り、その ID をサブスクリプション ID、リソース グループ名、プロバイダー名前空間、その他の部分などの個々のコンポーネントに解析します。
resource_group_resource_id サブスクリプション ID、リソース グループ名、リソースの種類、およびリソース名を指定して、Azure リソース グループ スコープリソース ID を構築します。
subscription_resource_id サブスクリプション ID、リソースの種類、およびリソース名を指定して、Azure サブスクリプション スコープのリソース ID を構築します。
tenant_resource_id リソースの種類とリソース名を指定して、Azure テナント スコープのリソース ID を構築します。

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 が変更された場合、置き換えがトリガーされません。

次のステップ