Infrastructure as Code のインポート (Azure → Terraform と AVM)

検出データと Azure Verified Modules を使用して既存の Azure インフラストラクチャを保守可能な Terraform コードに変換します。

このスキルを使用する場合

ユーザーが次のことを要求する場合にこのスキルを使用してください:

• 既存の Azure リソースを Terraform にインポートする
• ライブ Azure 環境から IaC を生成する
• AVM でサポートされている任意の Azure リソースタイプを処理する (正当な AVM 以外のフォールバックを文書化)
• サブスクリプションまたはリソースグループからインフラストラクチャを再作成する
• 検出された Azure リソース間の依存関係をマッピングする
• ハンドライトされた azurerm_* リソースの代わりに AVM モジュールを使用する

前提条件

• Azure CLI がインストール認証されている (az login)
• ターゲットのサブスクリプションまたはリソースグループへのアクセス
• Terraform CLI がインストール済み
• Terraform Registry と AVM インデックスソースへのネットワークアクセス

入力

パラメーター	必須	デフォルト	説明
subscription-id	いいえ	アクティブな CLI コンテキスト	サブスクリプションスコープの検出とコンテキスト設定に使用される Azure サブスクリプション
resource-group-name	いいえ	なし	リソースグループスコープの検出に使用される Azure リソースグループ
resource-id	いいえ	なし	特定のリソーススコープの検出に使用される 1 つ以上の Azure ARM リソース ID

subscription-id、resource-group-name、または resource-id の少なくとも 1 つが必須です。

ステップバイステップワークフロー

1) 必要なスコープを収集 (必須)

検出コマンドを実行する前に、以下のスコープのいずれかをリクエストしてください:

• サブスクリプションスコープ: <subscription-id>
• リソースグループスコープ: <resource-group-name>
• 特定リソーススコープ: 1 つ以上の <resource-id> 値

スコープ処理ルール:

• Azure ARM リソース ID (例: /subscriptions/.../providers/...) をクラウドリソース識別子として扱い、ローカルファイルシステムパスとしてではなく扱う。
• リソース ID は Azure CLI --ids 引数でのみ使用する (例: az resource show --ids <resource-id>)。
• ユーザーが明示的にそれらがローカルファイルパスであると言わない限り、リソース ID をファイル読み取りコマンド (cat、ls、read_file、glob 検索) に渡さない。
• ユーザーが既に 1 つの有効なスコープを提供している場合、失敗するコマンドで必要な場合を除き、追加のスコープ入力をリクエストしない。
• 既に提供されたスコープ値から答えることができるフォローアップの質問をしない。

スコープが不足している場合は明示的にリクエストして停止してください。

2) 認証とコンテキストの設定

選択したスコープに必要なコマンドのみを実行してください。

サブスクリプションスコープの場合:

az login
az account set --subscription <subscription-id>
az account show --query "{subscriptionId:id, name:name, tenantId:tenantId}" -o json

予想される出力: subscriptionId、name、tenantId を含む JSON オブジェクト。

リソースグループまたは特定リソーススコープの場合、az login は引き続き必須ですが、アクティブなコンテキストが既に正しい場合は az account set はオプションです。

特定リソーススコープを使用している場合は、最初に直接 --ids ベースのコマンドを優先し、具体的なコマンドで必要な場合を除き、サブスクリプションまたはリソースグループの追加検出プロンプトを避けてください。

3) 検出コマンドを実行

選択したスコープを使用してリソースを検出してください。正確な Terraform 生成のために必要なすべての情報を取得するようにしてください。

# サブスクリプションスコープ
az resource list --subscription <subscription-id> -o json

# リソースグループスコープ
az resource list --resource-group <resource-group-name> -o json

# 特定リソーススコープ
az resource show --ids <resource-id-1> <resource-id-2> ... -o json

予想される出力: Azure リソースメタデータ (id、type、name、location、tags、properties) を含む JSON オブジェクトまたは配列。

4) コード生成前に依存関係を解決

エクスポートされた JSON をパースして以下をマッピングしてください:

• 親子関係 (例: NIC → サブネット → VNet)
• properties のクロスリソース参照
• Terraform 作成の順序

重要: 以下のドキュメントを生成して、プロジェクトのルートの docs フォルダに保存してください。

• 検出されたすべてのリソースとそのメタデータ、依存関係および参照を含む exported-resources.json
• 検出されたリソースとその関係に基づいた人間が読める形式のアーキテクチャ概要を含む EXPORTED-ARCHITECTURE.MD ファイル

5) Azure Verified Modules を選択 (必須)

各リソースタイプの最新 AVM バージョンを使用してください。

Terraform Registry

• "avm" + リソース名で検索
• "Partner" タグでフィルタリングして公式 AVM モジュールを見つける
• 例: "avm storage account" を検索 → Partner でフィルタリング

公式 AVM インデックス

注: 以下のリンクは常に main ブランチ上の CSV ファイルの最新バージョンを指します。意図的に、ファイルは時間とともに変わる可能性があります。ポイントイン時間バージョンが必要な場合は、URL で特定のリリースタグを使用することを検討してください。

• Terraform リソースモジュール: https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/TerraformResourceModules.csv
• Terraform パターンモジュール: https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/TerraformPatternModules.csv
• Terraform ユーティリティモジュール: https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/TerraformUtilityModules.csv

個別モジュール情報

.terraform フォルダでローカルに利用できない場合、web ツールまたは別の適切な MCP メソッドを使用してモジュール情報を取得してください。

AVM ソースを使用してください:

• Registry: https://registry.terraform.io/modules/Azure/<module>/azurerm/latest
• GitHub: https://github.com/Azure/terraform-azurerm-avm-res-<service>-<resource>

AVM モジュールが存在する場合は、ハンドライトされた azurerm_* リソースより AVM モジュールを優先してください。

GitHub リポジトリからモジュール情報を取得する場合、リポジトリのルートの README.md ファイルには、通常、モジュールに関するすべての詳細情報が含まれています。例: https://raw.githubusercontent.com/Azure/terraform-azurerm-avm-res-<service>-<resource>/refs/heads/main/README.md

5a) コードを書く前にモジュール README を読む (必須)

このステップはオプションではありません。 モジュールの HCL を 1 行書く前に、そのモジュールの完全な README をフェッチして読んでください。生の azurerm プロバイダーの知識や他の AVM モジュールの経験に頼りません。

選択された各 AVM モジュールについて、その README をフェッチしてください:

https://raw.githubusercontent.com/Azure/terraform-azurerm-avm-res-<service>-<resource>/refs/heads/main/README.md

または、terraform init の後にモジュールが既にダウンロードされている場合:

cat .terraform/modules/<module_key>/README.md

README から、コードを書く前に以下を抽出して記録してください:

1. 必須入力 — モジュールが必要とするすべての入力。ここにリストされている任意の子リソース (NIC、拡張機能、サブネット、パブリック IP) はモジュール内で管理されます。それらのリソースに対して スタンドアロン モジュールブロックを作成しないでください。
2. オプション入力 — 正確な Terraform 変数名とその宣言された type。それらが生の azurerm プロバイダー引数名またはブロック形状と一致すると仮定しないでください。
3. 使用例 — どのリソースグループ識別子が使用されるか (parent_id と resource_group_name)、子リソースがどのように表現されるか (インライン map 対別モジュール)、および各入力がどのような構文を期待するかを確認してください。

モジュールルールをパターンとして適用し、仮定としてではなく

以下の教訓をサンプルとして使用してください。このタイプの不一致がインポート失敗をよく引き起こします。これらの正確な名前がすべての AVM モジュールに適用されると仮定しないでください。常に選択されたモジュールの README と variables.tf を検証してください。

avm-res-compute-virtualmachine (任意のバージョン)

• network_interfaces は必須入力です。NIC は VM モジュールによって所有されます。VM モジュールの横にスタンドアロン avm-res-network-networkinterface モジュールを作成しないでください — すべての NIC を network_interfaces 下にインラインで定義してください。
• TrustedLaunch はトップレベルのブール値 secure_boot_enabled = true と vtpm_enabled = true で表現されます。security_type 引数は Confidential VM ディスク暗号化の os_disk の下に存在し、TrustedLaunch に使用してはいけません。
• boot_diagnostics は bool であり、オブジェクトではありません。boot_diagnostics = true を使用してください。ストレージ URI が必要な場合は、別の boot_diagnostics_storage_account_uri 変数を使用してください。
• 拡張機能はモジュール内の extensions map を介して管理されます。スタンドアロン拡張機能リソースを作成しないでください。

avm-res-network-virtualnetwork (任意のバージョン)

• このモジュールは azurerm ではなく AzAPI プロバイダーでサポートされています。リソースグループを指定するために resource_group_name ではなく parent_id (完全なリソースグループリソース ID 文字列) を使用してください。
• README 内のすべての例は parent_id を示しており、resource_group_name を示すものはありません。

すべての AVM モジュールの一般化された結論:

• 兄弟モジュールを作成する前に、必須入力から子リソース所有権を決定してください。
• オプション入力と variables.tf から受け入れられた変数名とタイプを決定してください。
• README 使用例から識別子スタイルと入力形状を決定してください。
• 生の azurerm_* リソースから引数名を推測しないでください。

6) Terraform ファイルを生成

インポートブロックを書く前に — モジュールソースを検査 (必須)

terraform init がモジュールをダウンロード後、各モジュールのソースファイルを検査して、import {} ブロックを書く前に正確な Terraform リソースアドレスを決定してください。メモリからインポートアドレスを書かないでください。

ステップ A — プロバイダーとリソースラベルを識別

grep "^resource" .terraform/modules/<module_key>/main*.tf

これはモジュールが azurerm_* または azapi_resource ラベルを使用しているかどうかを明らかにします。例えば、avm-res-network-virtualnetwork は azurerm_virtual_network "this" ではなく azapi_resource "vnet" を公開します。

ステップ B — 子モジュールとネストされたパスを識別

grep "^module" .terraform/modules/<module_key>/main*.tf

子リソースが子モジュールで管理されている場合 (サブネット、拡張機能など)、インポートアドレスはすべての中間モジュールラベルを含める必要があります:

module.<root_module_key>.module.<child_module_key>["<map_key>"].<resource_type>.<label>[<index>]

ステップ C — count 対 for_each を確認

grep -n "count\|for_each" .terraform/modules/<module_key>/main*.tf

count を使用しているリソースには、インポートアドレスにインデックスが必要です。count = 1 (例: 条件付き Linux 対 Windows 選択) の場合、アドレスは [0] で終わる必要があります。for_each を使用しているリソースは数値インデックスではなく文字列キーを使用します。

既知のインポートアドレスパターン (学習した教訓の例)

これらはサンプルのみです。正確なアドレスを推論するためにテンプレートとしてそれらを使用して、その後、現在のインポートのダウンロードされたモジュールソースから正確なアドレスを導出してください。

リソース	正確なインポート to アドレスパターン
AzAPI ベック VNet	module.<vnet_key>.azapi_resource.vnet
サブネット (ネストされた、count ベース)	module.<vnet_key>.module.subnet["<subnet_name>"].azapi_resource.subnet[0]
Linux VM (count ベース)	module.<vm_key>.azurerm_linux_virtual_machine.this[0]
VM NIC	module.<vm_key>.azurerm_network_interface.virtualmachine_network_interfaces["<nic_key>"]
VM 拡張機能 (デフォルト deploy_sequence=5)	module.<vm_key>.module.extension["<ext_name>"].azurerm_virtual_machine_extension.this
VM 拡張機能 (deploy_sequence=1–4)	module.<vm_key>.module.extension_<n>["<ext_name>"].azurerm_virtual_machine_extension.this
NSG-NIC 関連付け	module.<vm_key>.azurerm_network_interface_security_group_association.this["<nic_key>-<nsg_key>"]

生成してください:

• azurerm プロバイダーと必要なバージョン制約を含む providers.tf
• AVM モジュールブロックと明示的な依存関係を含む main.tf
• 環境固有の値のための variables.tf
• キー ID とエンドポイントのための outputs.tf
• プレースホルダー値を含む terraform.tfvars.example

ライブプロパティをモジュールデフォルトと比較 (必須)

初期設定を書いた後、検出されたライブリソースのすべての非ゼロプロパティを、対応する AVM モジュールの variables.tf で宣言されたデフォルト値と比較してください。ライブ値がモジュールデフォルトから異なるプロパティは、Terraform 構成で明示的に設定される必要があります。

以下のプロパティカテゴリに特に注意を払ってください。これらはサイレント構成ドリフトの一般的な原因です:

• タイムアウト値 (例: パブリック IP idle_timeout_in_minutes デフォルトは 4; ライブデプロイメントはしばしば 30 を使用)
• ネットワークポリシーフラグ (例: サブネット private_endpoint_network_policies デフォルトは "Enabled"; 既存サブネットは "Disabled" を持つことが多い)
• SKU と割り当て (例: パブリック IP sku、allocation_method)
• 可用性ゾーン (例: VM ゾーン、パブリック IP ゾーン)
• 冗長性とレプリケーション設定ストレージおよびデータベースリソースの

完全なライブプロパティを明示的な az コマンドで取得してください。例えば:

az network public-ip show --ids <resource_id> --query "{idleTimeout:idleTimeoutInMinutes, sku:sku.name, zones:zones}" -o json
az network vnet subnet show --ids <resource_id> --query "{privateEndpointPolicies:privateEndpointNetworkPolicies, delegation:delegations}" -o json

az resource list 出力のみに頼らないでください。ネストされたまたはコンピュート済みプロパティが省略される可能性があります。

モジュールバージョンを明示的にピンしてください:

module "example" {
	source  = "Azure/<module>/azurerm"
	version = "<latest-compatible-version>"
}

7) 生成されたコードを検証

実行:

terraform init
terraform fmt -recursive
terraform validate
terraform plan

予想される出力: 構文エラーなし、検証エラーなし、検出されたインフラストラクチャの意図と一致するプラン。

トラブルシューティング

問題	可能な原因	アクション
az コマンドが認可エラーで失敗	誤ったテナント/サブスクリプションまたは欠落している RBAC ロール	az login を再実行し、サブスクリプションコンテキストを検証し、必要な権限を確認
検出出力が空	誤ったスコープまたはスコープ内にリソースなし	スコープ入力を再確認して、スコープ付きリスト/表示コマンドを再実行
AVM モジュールがリソースタイプの場合に見つからない	リソースタイプはまだ AVM でカバーされていない	そのタイプにネイティブ azurerm_* リソースを使用してギャップを文書化
terraform validate が失敗	不足している変数または未解決の依存関係	必要な変数と明示的な依存関係を追加して、検証を再実行
不明な引数またはモジュール内に見つからない変数	AVM 変数名は azurerm プロバイダー引数名と異なる	モジュール README variables.tf またはオプション入力セクションで正しい名前を読む
インポートブロックが失敗 — リソースがアドレスで見つからない	間違ったプロバイダーラベル (azurerm_ 対 azapi_)、不足しているサブモジュールパス、または不足している [0] インデックス	grep "^resource" .terraform/modules/<key>/main*.tf と grep "^module" を実行して正確なアドレスを見つける
terraform plan がインポートされたリソースに予期しない ~ update を表示	ライブ値が AVM モジュールデフォルトと異なる	az <resource> show でライブプロパティをフェッチし、モジュールデフォルトと比較して、明示的な値を追加
子リソースモジュールが「プロバイダー設定が存在しない」を与える	親モジュールが所有していても、子リソースがスタンドアロンモジュールとして宣言されている	README で必須入力を確認、不正なスタンドアロンモジュールを削除、親モジュールの文書化された入力構造を使用して子リソースをモデル化
ネストされた子リソースのインポートが「リソースが見つからない」で失敗	不足している中間モジュールパス、間違ったマップキー、または不足しているインデックス	ソースのモジュールブロックと count/for_each を検査; すべてのモジュールセグメントと必要なキー/インデックスを含む完全なネストされたインポートアドレスを構築
ツールが ARM リソース ID をファイルパスとして読み取ろうとするか、繰り返されたスコープ質問をする	リソース ID が --ids 入力として扱われていない、またはエージェントが既に提供されたスコープを信頼しなかった	ARM ID を厳密にクラウド識別子として扱い、az ... --ids ... を使用し、有効なスコープが存在すると再度促す

応答契約

結果を返すときに以下を提供してください:

1. 使用されたスコープ (サブスクリプション、リソースグループ、またはリソース ID)
2. 作成された検出ファイル
3. 検出されたリソースタイプ
4. 選択された AVM モジュールとバージョン
5. 生成またはアップデートされた Terraform ファイル
6. 検証コマンドの結果
7. ユーザー入力が必要なギャップ (該当する場合)

エージェントの実行ルール

• スコープが不足している場合は続行しないでください。
• 検出されたファイルと検証出力をリストしていない場合、成功したインポートを主張しないでください。
• コード生成前に依存関係マッピングをスキップしないでください。
• 最初に AVM モジュールを優先してください。各 AVM 以外のフォールバックを明示的に正当化してください。
• コードを書く前にすべての AVM モジュールの README を読んでください。 必須入力はモジュールが所有する子リソースを識別します。オプション入力は正確な変数名とタイプを文書化します。使用例はプロバイダー固有の規則 (parent_id 対 resource_group_name) を示します。README をスキップすることは、AVM ベースのインポートのコードエラーの単一最大の原因です。
• NIC、拡張機能、またはパブリック IP リソースがスタンドアロンであると仮定しないでください。 AVM モジュールの場合、README が別のモジュールが必須であることを明示的に示さない限り、子リソースを親所有として扱ってください。兄弟モジュールを作成する前に必須入力を確認してください。
• メモリからインポートアドレスを書かないでください。 terraform init の後、正確なプロバイダー (azurerm 対 azapi)、リソースラベル、サブモジュールネストング、および count 対 for_each 使用法をダウンロードされたモジュールソースから検索して、import {} ブロックを書く前に。
• ARM リソース ID をファイルパスとして扱わないでください。 リソース ID は Azure CLI --ids 引数と API クエリに属し、ファイル IO ツールではありません。実際のワークスペースパスが提供される場合のみローカルファイルを読んでください。
• スコープが既に既知の場合、プロンプトを最小化してください。 サブスクリプション、リソースグループ、または特定リソース ID が既に提供されている場合は、コマンドを直接進めて、コマンドが不足している必要なコンテキストのために失敗する場合のみフォローアップをリクエストしてください。
• terraform plan が 0 destroys と 0 の不要な変更を示すまで、インポートが完了したと宣言しないでください。 テレメトリ + create リソースは許可されます。実際のインフラストラクチャリソースに ~ update または - destroy を解決する必要があります。

参考資料

• Azure Verified Modules インデックス (Terraform)
• Terraform AVM Registry 名前空間