aztfexport

aztfexport — Azure リソースを Terraform にエクスポート

概要

aztfexport は、既存の Azure リソースを Terraform HCL と state にエクスポートする Microsoft のツールです。稼働中の Azure インフラストラクチャをリバースエンジニアリングして、Terraform の構成に変換します。Azure 専用のワークフロー、または Terraform 1.14 のネイティブな terraform query より前のバージョンを使用する場合に利用してください。

使用する場面

• 単一の Azure リソースを Terraform にエクスポートする → aztfexport resource
• リソースグループ全体をエクスポートする → aztfexport resource-group
• Azure Resource Graph のクエリに一致するリソースをエクスポートする → aztfexport query
• 既存の Azure インフラストラクチャから IaC を立ち上げる

次の場合は代わりに terraform-search-import スキルを使用してください： terraform query と一括インポートを利用できる Terraform >= 1.14（マルチクラウド対応で、Azure 専用ではありません）。

前提条件

1. aztfexport がインストール済みであること： brew install aztfexport（macOS）、または GitHub リリースを参照してください
2. Azure CLI で認証済みであること： az login を実行し、正しいサブスクリプションを選択してください
3. アーキテクチャを確認すること（macOS では特に重要）：

   file $(which aztfexport)  # Check binary arch
   uname -m                  # Check system arch
   

   不一致がある場合（例：arm64 の Mac で x86_64 バイナリを使用している場合）は、適切なアーキテクチャ版を再インストールしてください。

ワークフロー

ステップ 1：リソース ID を特定する

Azure CLI を使用してリソース ID を確認してください。リソースタイプ別のパターンについては、references/RESOURCE-DISCOVERY.md を参照してください。

汎用的な代替方法：

az resource list --query "[?name=='RESOURCE_NAME']" -o table

ステップ 2：aztfexport バイナリを検証する

file $(which aztfexport)
uname -m
aztfexport --version

アーキテクチャの不一致は、原因の分かりにくいエラーを引き起こします。新しいマシンで初めて使用する前に、必ず確認してください。

ステップ 3：aztfexport を実行する

単一のリソース：

aztfexport resource \
  --non-interactive \
  --plain-ui \
  -o ./terraform-export \
  "/subscriptions/SUB_ID/resourceGroups/RG/providers/TYPE/NAME"

リソースグループ：

aztfexport resource-group \
  --non-interactive \
  --plain-ui \
  -o ./terraform-export \
  RESOURCE_GROUP_NAME

Azure Resource Graph クエリ：

aztfexport query \
  --non-interactive \
  --plain-ui \
  -o ./terraform-export \
  "resources | where name == 'MY_RESOURCE'"

ステップ 4：生成されたファイルを確認する

ls ./terraform-export/
# Expect: main.tf, provider.tf, terraform.tfstate, import.tf (sometimes)

• main.tf — res-0 形式のリソース名を使った、生成済みの HCL
• provider.tf — AzureRM プロバイダーの構成
• terraform.tfstate — インポートされた state ファイル
• res-0 を説明的な名前に変更することを検討してください（HCL と state の両方を更新します）

ステップ 5：検証する

cd ./terraform-export
terraform init
terraform plan

変更なしのクリーンなプランであれば、エクスポートは成功しています。計算属性による軽微な差分が生じる場合があります。確認したうえで、適切であれば lifecycle { ignore_changes } を使って抑制してください。

重要なフラグ

フラグ	用途	必要な場面
--non-interactive	対話型プロンプトをスキップする	CI／ヘッドレス環境／Claude では常に使用
--plain-ui	TUI（ターミナル UI）を無効にする	常に --non-interactive と併用してください — 併用しないと、/dev/tty がない場合に失敗します
-o <dir>	出力ディレクトリ	常に指定（空、または存在しないディレクトリである必要があります）
--append	既存の Terraform ディレクトリに追記する	既存の構成に追加する場合（ただし、以下の注意点を参照）
--overwrite	既存ファイルを上書きする	同じディレクトリに再エクスポートする場合
--hcl-only	state をインポートせずに HCL を生成する	コードだけが必要な場合

注意点とトラブルシューティング

問題	原因	解決方法
バイナリが警告なくクラッシュする、または exec format error が発生する	アーキテクチャの不一致（ARM Mac で x86 を使用）	file $(which aztfexport) と uname -m を実行し、正しいアーキテクチャ版を再インストールする
--non-interactive だけでは失敗する	ヘッドレス環境に /dev/tty がない	常に --plain-ui と併用する
「directory is not empty」エラー	出力ディレクトリにファイルがある	-o <fresh-dir> または --overwrite を使用する
state のない空でないディレクトリで --append が失敗する	aztfexport は既存の Terraform state を必要とする	代わりに、新しいサブディレクトリを -o に指定する
Azure リソース ID が見つからない	リソースタイプが不明、または API が間違っている	複数の az コマンドを試してください — RESOURCE-DISCOVERY.md を参照
出力に res-0 形式の名前がある	aztfexport のデフォルトの命名	エクスポート後に HCL と state の両方で名前を変更する
エクスポート後に terraform plan で差分が表示される	計算属性／サーバー側の属性	差分を確認し、問題のないものには ignore_changes を使用する

例：アクティビティログ アラートをエクスポートする

# Step 1: Find the resource ID
az monitor activity-log alert list -g myResourceGroup \
  --query "[?name=='my-alert'].id" -o tsv

# Step 2: Export
aztfexport resource \
  --non-interactive \
  --plain-ui \
  -o ./alert-export \
  "/subscriptions/xxxx/resourceGroups/myRG/providers/Microsoft.Insights/activityLogAlerts/my-alert"

# Step 3: Verify
cd ./alert-export
terraform init
terraform plan

---

注意点

• aztfexport バイナリと AzureRM プロバイダーの CGO バインディング間のアーキテクチャの不一致：Apple Silicon では ARM64 ビルドが必要です。M シリーズで x86 バイナリを使用すると、警告なしに性能が低下します。
• リソース名の正規表現のデフォルト設定では特殊文字が除外されます：名前に . を含むリソース（FQDN など）は、警告なしにスキップされます。
• 生成される import ブロック（Terraform 1.5+）と state import コマンドの違い：aztfexport は現在ブロックを書き出すため、state import の呼び出しを前提とする古いワークフローは機能しなくなります。
• --include-role-assignment はデフォルトでオフです：RBAC がステートに含まれません。通常、これはまさに避けたい状態です。
• プロバイダーのバージョン固定：aztfexport はインポート時に特定の AzureRM バージョンを固定します。ターゲットスタックのプロバイダーが一致しないと、不要な plan 差分が生じます。
• 非対話型（-n）では名前をカスタマイズできません：azurerm_storage_account_001 のような自動生成された TF 名は、確認しないままにすると、コードに残り続けます。