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 ワークスペース ライブラリ |
使用階層
全体として、使用するには次の手順に従う必要があります。
- まず、
azapi_resource
内でできる限り多くの操作を実行することをお勧めします。 - リソース タイプが
azapi_resource
内に存在せず、azapi_data_plane_resource
でサポートされているタイプのいずれかに該当する場合は、代わりにそれを使用します。 - リソースが既に AzureRM に存在する場合、または
azapi_resource
内でアクセスできないプロパティがある場合は、azapi_update_resource
を使用してこれらの特定のプロパティにアクセスします。azapi_resource
またはazapi_data_plane_resource
でサポートされていないリソースは、このリソースを使用して更新することはできません。 - 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_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 が変更された場合、置き換えがトリガーされません。