alibabacloud-terraform-import

Alibaba Cloud リソース Terraform インポートウィザード

既存の Alibaba Cloud アカウント内のリソースをローカルの Terraform 管理にインポートするためのステップバイステップガイドです。環境チェック、リソースの検出、HCL の生成、state のインポートなどを自動で実行します。ユーザーは重要な判断ポイントで確認するだけです。

次の 2 つのモードに対応しています。

• 一度限りの移行：フェーズ 1～9 を最初から最後まで実行します
• 段階的な同期：Terraform の作業ディレクトリがすでにある場合は、段階的な同期モードに直接移行します

リソースのサポート範囲

• 理論上の範囲：Read メソッドを持つ alicloud プロバイダー内のあらゆるリソース（つまり、クラウドから state を読み取れるリソース）が対象です。ほとんどのリソースは terraform import コマンドまたは import ブロック（Terraform 1.5 以降）で直接インポートできます。Importer がない一部のリソースは tfstate を手動で作成してインポートできますが、プロバイダーの state 構造に正確に一致させる必要があり、リスクも伴います。サポート状況は https://registry.terraform.io/providers/aliyun/alicloud/latest/docs で確認してください。
• 事前に用意されたリソース：一般的なリソースタイプ約 50 種類（ネットワーク、コンピューティング、ストレージ、データベース、ロードバランシング、DNS、RAM、ACK、FC）について、検証済みの API 検出コマンド、HCL テンプレート、インポート ID 形式を references/ に用意しています
• 事前に用意された範囲外：プロバイダーのドキュメントをその都度参照し、コマンドとテンプレートを提示します。正確性はドキュメントの内容に左右されるため、実行前に確認してください

---

コマンド形式の要件

すべての aliyun CLI コマンドでは、プラグインモード（小文字とハイフンの形式）を使用する必要があります。CamelCase のコマンド名とパラメーター名は禁止されています。このルールに違反すると、パラメーターエラーや呼び出しの失敗が発生します。

例（正しいプラグインモード形式）：

aliyun vpc describe-vpcs --biz-region-id cn-shanghai --page-size 50

パラメーターの変換ルール：

• リージョン：--biz-region-id（API の RegionId に対応するビジネスパラメーター）を優先します。--region（エンドポイントのリージョンを制御するフレームワークパラメーター）は、API の RegionId が任意の場合にのみ使用してください
• ページネーション：--page-size を使用します（PageSize ではありません）
• その他：CamelCase のパラメーター名を小文字とハイフンの形式に変換します（VpcId -> --vpc-id、InstanceIds -> --instance-ids）。aliyun <product> <command> --help を使用して確認してください
• OSS：aliyun ossutil ls oss:// のみを使用します

---

フェーズ 1：環境チェック

次のコマンドを実行して環境を検出します。

echo "=== aliyun CLI ===" && aliyun --version 2>&1 || echo "NOT_INSTALLED"
echo "=== terraform ===" && terraform --version 2>&1 || echo "NOT_INSTALLED"
echo "=== python3 ===" && python3 --version 2>&1 || echo "NOT_INSTALLED"
echo "=== OS ===" && uname -s 2>&1

出力に基づいて、不足しているツールに自動的に対処します。

• aliyun CLI がない場合（macOS）：brew install aliyun-cli を実行します
• aliyun CLI がない場合（Linux）：curl -sSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz | tar xz && sudo mv aliyun /usr/local/bin/ を実行します
• terraform がない場合（macOS）：brew tap hashicorp/tap && brew install hashicorp/tap/terraform を実行します
• terraform がない場合（Linux）：手動インストール（root 権限が必要）のため、ユーザーに https://developer.hashicorp.com/terraform/install を案内します

すべてのツールの準備ができたら、フェーズ 2 に進みます。

aliyun CLI の AI-Mode を設定する：

Alibaba Cloud が AI による呼び出しのシナリオを識別して最適化されたサポートを提供できるよう、すべての aliyun CLI コマンドで AI-Mode を設定する必要があります。aliyun CLI コマンドを実行する前に、次を実行してください。

# Enable AI-Mode (required)
aliyun configure ai-mode enable

# Set User-Agent identifier (required)
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-terraform-import"

# Update plugins to latest version (recommended)
aliyun plugin update

以降のすべての aliyun CLI コマンドには、AI-Mode と User-Agent の識別子が自動的に付与されます。コマンド形式のルールについては、上記の「コマンド形式の要件」セクションを参照してください。

AI-Mode を無効にする（セッション終了時、または必要な場合）：

aliyun configure ai-mode disable

---

フェーズ 2：認証の設定

このスキルは、Alibaba Cloud のデフォルト認証情報チェーンを使用して認証を行い、次の方法を優先順位順にサポートします。

1. 環境変数（ALICLOUD_ACCESS_KEY / ALICLOUD_SECRET_KEY）— 最優先
2. aliyun CLI 設定ファイル（~/.aliyun/config.json）
3. ECS RAM ロール（ECS 上で実行している場合のみ）

重要：Terraform の alicloud プロバイダーと aliyun CLI は、それぞれ独立して認証情報を読み込み、どちらも環境変数を優先します。環境変数と CLI プロファイルが異なるアカウントを参照している場合、環境変数が優先されます。

認証を確認します：

AK/SK を明示的に渡さずに、デフォルト認証情報チェーンを使用して ID を確認します。

aliyun sts get-caller-identity 2>&1

出力を分析します：

• AccountId と UserId を確認し、Region を記録します
• 認証情報の取得元が想定と異なる場合（例：環境変数と CLI プロファイルが異なるアカウントを参照している場合）、認証情報の競合をユーザーに伝え、再試行する前に認証情報の設定を統一するよう提案します

エラーが発生した場合は、ユーザーに次の確認を依頼します：

• 認証情報が設定されているかを確認する（aliyun configure または環境変数を使用）
• 権限を確認する（ReadOnlyAccess または該当リソースの Describe 権限が必要です）
• 必要な権限については references/ram-policies.md を参照する

---

フェーズ 3：作業ディレクトリの初期化

次の情報をユーザーに尋ねます：

• 対象の作業ディレクトリのパス（デフォルトは ~/alicloud-terraform）
• 対象の Region（フェーズ 2 ですでに推測できている場合は確認し、そうでない場合は尋ねます）
• Terraform の作業ディレクトリがすでに存在するかどうか（存在する場合はこのフェーズをスキップします）

ユーザーの確認後、次の処理を自動的に実行します。

1. 作業ディレクトリと .import/ サブディレクトリを作成します（中間成果物の保存用）
2. 対象ディレクトリに provider.tf を生成します（examples/provider.tf を参照）。Region のデフォルト値をユーザーが確認した Region に置き換えます。UA の追跡のため、プロバイダーブロックには configuration_source = "AlibabaCloud-Agent-Skills/alibabacloud-terraform-import" を含める必要があります
3. 対象ディレクトリで terraform init を実行します
4. init の出力を分析し、プロバイダーのダウンロードが成功したことを確認します
5. （任意の拡張機能） terraform providers schema -json を実行し、すべてのリソースから _id または _ids で終わるフィールドを抽出して、フェーズ 6 用の参照フィールドの許可リストを作成します。スキーマの出力が大きすぎて解析がタイムアウトする場合は、この手順をスキップします。その場合、フェーズ 6 では参照の解決に静的な依存関係ルールを使用します
6. （任意の拡張機能） iacservice list-resource-types を呼び出し（すべて取得するためページネーションを実施）、resourceType フィールドの ALIYUN プレフィックスを ACS に置き換えて、terraformResourceType <-> ResourceCode の双方向マッピングテーブルを作成し、フェーズ 4／5／6 で使用するため .import/resource-type-mapping.json に書き込みます。呼び出しに失敗した場合、または権限が不十分な場合は、references/resource-hub-api.md の静的マッピングテーブルを使用します。この手順をスキップしても、インポートの基本フローには影響しませんが、ResourceCenter API のリソースタイプ変換に影響します
7. 初期化が完了したことをユーザーに伝え、フェーズ 4 に進みます

---

フェーズ 4：リソースの検出

ステップ 0 — ResourceCenter がサポートするリソースタイプを照会する（最初に実行）

aliyun resourcecenter list-resource-types を実行して、API A（search-resources）と API B（list-resource-relationships）がサポートするリソースタイプの一覧を取得し、このフェーズとフェーズ 5 で使えるようにキャッシュします。詳細は references/resource-hub-api.md を参照してください。

呼び出しに失敗した場合、または権限が不足している場合は、ステップ 0 をスキップし、リソース検出には一貫してネイティブの製品 API を使用します。

ステップ 1 — リソースを検出する

対象のリソースタイプごとに、次の優先順位に従って検出方法を選択します。

1. リソースタイプが API A のサポート一覧にある場合 -> 一括クエリには API A（search-resources）を使用します。詳細は references/resource-hub-api.md を参照してください。
2. それ以外の場合 -> references/api-commands.md に記載されたネイティブの製品 API コマンドにフォールバックします。

ユーザーが references/api-commands.md に記載されていないリソースタイプの検出を必要としている場合：

• まずプロバイダーのドキュメント（https://registry.terraform.io/providers/aliyun/alicloud/latest/docs）を確認して、サポート状況を判断します。
  • Import セクションがある -> terraform import をサポートしています。通常どおり進めます。
  • Import セクションはないが、プロバイダーがリソースをサポートしている -> 手動での tfstate 構築によってインポートできます。進める前にリスクをユーザーに伝えます。
  • プロバイダーがリソースをまったくサポートしていない -> インポートできないことを明確に伝えます。
• サポートを確認した後、aliyun CLI のドキュメント（https://help.aliyun.com/document_detail/110244.html）または該当する製品 API のドキュメントを確認して、検出コマンドを調べます。

適切なコマンドを実行して出力を収集し、タイプごとの件数と ID 一覧をまとめたリソース検出レポートを作成します。

検出結果が空の場合の対応：

あるリソースタイプ（例：NAT Gateway）の結果が空で、ユーザーはリソースが存在するはずだと考えている場合は、次の点を積極的に調査します。

• リソースが別のリージョンにないか確認します。
• 現在の認証情報に、そのリソースの Describe 権限があるか確認します。
• リソースがリリース済みでないか確認します（監査ログで確認できます）。
• 検出結果が想定と一致しないことをユーザーに伝え、続行する前に確認を求めます。

フェーズ 5：インポート範囲と深度を選択する

リソース検出レポートを提示し、ユーザーに次の内容を確認します。

• すべてをインポートするか、特定のリソースタイプを選択するか？
• VPC の範囲で絞り込むか？
• タグで絞り込むか？
• インポート深度の戦略：
  1. 検出されたリソースのみをインポートする（関連リソースのクエリなし、深度=0）
  2. 関連リソースを 1 階層分インポートする（深度=1）
  3. 依存関係ツリー全体をインポートする（深度=無制限、推奨）

リソース依存関係グラフを構築する（深度戦略に基づく）

ユーザーが選択した深度戦略に基づいて、次のように処理します。

深度=0（検出されたリソースのみをインポート）：

• API B の呼び出しをスキップします
• references/dependency-rules.md の静的な依存関係ルールを使用して、フェーズ 4 で検出したリソースを直接並べ替えます
• インポート順序を生成します

深度=1（関連リソースを 1 階層分インポート）：

• フェーズ 4 で検出した各リソースについて、そのタイプが API B のサポートリストに含まれている場合、API B（list-resource-relationships）を呼び出して直接関連するリソースを取得します
• 返された関連リソースについて、API B を再帰的に呼び出しません
• 検出されたリソースと 1 階層分の関連リソースを統合し、リソースグラフをトポロジカルソートして、インポート順序を生成します

深度=無制限（依存関係ツリー全体をインポート、推奨）：

• フェーズ 4 で検出したリソースから、親の依存関係を持たないルートリソース（VPC、OSS Bucket、DNS ドメイン、RAM ユーザーなど）を特定します
• 各ルートリソースについて、そのタイプが API B のサポートリストに含まれている場合、API B を呼び出して関連リソースを取得します
• 新しいリソースがなくなるまで（新規リソースセット == 空セット）、関連リソースに対して API B を再帰的に呼び出します
• API B がサポートしていないリソースタイプについては、references/dependency-rules.md の静的な依存関係ルールにフォールバックします
• すべての関係ツリーを統合し、リソースグラフをトポロジカルソートして、インポート順序を生成します

静的なインポート順序へのフォールバック（API B が利用できない場合）：

Layer 0: VPC, OSS Bucket (no dependencies)
Layer 1: VSwitch, Security Group, EIP (depend on VPC)
Layer 2: NAT Gateway, SLB (depend on VPC + VSwitch)
Layer 3: ECS Instance (depends on VSwitch + Security Group)
Layer 4: Disk (depends on ECS)
Layer 5: RDS, Redis, MongoDB (depend on VSwitch)
Layer 6: DNS Record (depends on Domain)

依存関係ルールの詳細については、references/dependency-rules.md を参照してください。

---

フェーズ 6：Terraform HCL コードを生成する

リソースをタイプごとにバッチ処理します。各リソースタイプについて、次のように処理します。

1. 詳細取得コマンドを実行します（JSON 形式）
2. JSON を解析し、対応する .tf ファイルを生成して作業ディレクトリに書き込みます

リソースタイプごとに 1 ファイルを作成し、ファイル名の形式は <product>_<resource_type>.tf です。

vpc_vpcs.tf
vpc_vswitches.tf
vpc_security_groups.tf
vpc_eips.tf
vpc_nat_gateways.tf
ecs_instances.tf
ecs_disks.tf
oss_buckets.tf
rds_instances.tf
kvstore_instances.tf
dds_instances.tf
slb_load_balancers.tf
alidns_domains.tf
alidns_records.tf

HCL コードのテンプレートについては references/terraform-patterns.md を、例については examples/ を参照してください。

リソース間参照の解決（3 層戦略）

各リソースの HCL を生成する際、各フィールド値を Terraform のリソースアドレスに置き換えるかどうかを、次の優先順位で判断します。

1. まず API B の関係を使用：API B（list-resource-relationships）でリソースが検出された場合、親リソースまたは関連リソースはすでに特定されています。フェーズ 3 で抽出した参照フィールドのホワイトリストと照合し、現在のリソース内にあるタイプが一致する _id フィールドを見つけて、対応する Terraform リソースアドレスに直接置き換えます。関係は確定しているため、推測する必要はありません。

2. ホワイトリストとマッピングテーブルの両方に一致する場合のフォールバック：API B で扱われていないリソースについて、フィールド名がフェーズ 3 の参照フィールドのホワイトリストに含まれ、フィールド値に対応するエントリがリソース ID マッピングテーブルにある場合は、Terraform リソースアドレスに置き換えます。

3. dependency-rules.md の静的ルールへのフォールバック：上記 2 層では扱えない例外ケース（複合 ID、_id で終わらない参照フィールドなど）については、references/dependency-rules.md の静的ルールを参照します。

リソース ID マッピングテーブル

各リソースブロックを生成したら、すぐにマッピングテーブルにレコードを追加します。

<cloud resource ID>  ->  <terraform resource address>
# Example:
vpc-bp1xxx   ->  alicloud_vpc.vpc_prod_main
vsw-bp1aaa   ->  alicloud_vswitch.vsw_prod_a
sg-bp1xxx    ->  alicloud_security_group.sg_web

後続のフェーズで使用するため、マッピングテーブルを .import/id-mapping.json に書き込みます。

その他の重要な原則：

• リソース名には <type>_<name> 形式を使用します（例：alicloud_vpc.vpc_prod_main）
• パスワード／シークレットフィールドには変数を使用します（var.db_password）
• 元のタグを保持します

---

フェーズ 7：状態のインポート

フェーズ 5 で生成したトポロジカルソートに基づいて、terraform import コマンドの完全なリストを生成し、ユーザーに確認を求めた後、バッチごとに実行します。

バッチ 1 — ネットワーク基盤：

terraform import alicloud_vpc.vpc_<name> <vpc-id>
terraform import alicloud_vswitch.vsw_<name> <vsw-id>
terraform import alicloud_security_group.sg_<name> <sg-id>

バッチ 2 — ネットワーク付属リソース：

terraform import alicloud_nat_gateway.nat_<name> <nat-id>
terraform import alicloud_eip_address.eip_<name> <eip-id>

バッチ 3 — コンピューティング：

terraform import alicloud_instance.ecs_<name> <instance-id>
terraform import alicloud_disk.disk_<name> <disk-id>

バッチ 4 — ストレージ：

terraform import alicloud_oss_bucket.bucket_<name> <bucket-name>

バッチ 5 — データベース：

terraform import alicloud_db_instance.rds_<name> <db-id>
terraform import alicloud_kvstore_instance.redis_<name> <redis-id>
terraform import alicloud_mongodb_instance.mongo_<name> <mongo-id>

バッチ 6 — ロードバランシング：

terraform import alicloud_slb_load_balancer.slb_<name> <slb-id>

バッチ 7 — DNS：

terraform import alicloud_dns_domain.domain_<name> <domain-name>

各バッチの後に出力を分析し、一般的なエラーに対処します。

• ResourceNotFound：リソース ID が正しくありません。再確認してください。
• PermissionDenied：対応するリソースの Describe 権限が必要です。
• already managed：リソースはすでに状態に含まれているため、スキップします。
• ID 形式エラー：references/resource-types.md のインポート形式を参照してください。

---

フェーズ 8：検証

以下のコマンドを実行して、インポート結果を検証します。

# List all resources in state
terraform state list 2>&1

# Run plan, target is No changes
terraform plan -refresh=true 2>&1

プランの出力を分析します。

• No changes -> 検証に合格しました。フェーズ 9 に進みます。
• 差分あり -> 原因を分析し、references/terraform-patterns.md の一般的な差分修正パターンを参照して、修正案を提示しユーザーに通知します。ユーザーの確認後に修正を実行します。

一般的な差分の原因：

• タグ形式の不一致（HCL のタグ構文を調整する必要があります）
• パスワードフィールドを API から読み取れない（ignore_changes を使って無視します）
• 計算フィールドの差異（lifecycle { ignore_changes = [...] } を追加します）
• デフォルト値の差異（クラウドと一致する値を明示的に設定します）

---

フェーズ 9：リソース関係グラフ

以下のコマンドを実行して、リソース関係グラフを生成します。

# Export state JSON
terraform show -json > .import/tf_state.json 2>&1

# Extract dependencies
python3 -c "
import json, sys
with open('.import/tf_state.json') as f:
    state = json.load(f)
resources = state.get('values', {}).get('root_module', {}).get('resources', [])
print(f'Total resources: {len(resources)}')
for r in resources:
    deps = r.get('depends_on', [])
    if deps:
        for d in deps:
            print(f'  {d} --> {r[\"address\"]}')
" 2>&1

出力に基づいて、次の内容を示すテキスト形式のリソース関係グラフ（ツリー構造）を生成します。

• ネットワーク層 -> コンピューティング層 -> データ層の依存関係
• セキュリティグループの横断的な参照
• ロードバランサーのバックエンドバインド関係

形式の例については、examples/dependency-graph.txt を参照してください。

---

増分同期モード

Terraform の作業ディレクトリがすでに存在する場合は、このモードを使用します。次の 3 種類の変更を自動的に検出します。

1. 新規リソースの検出（クラウドに存在し、状態には存在しない）：

以下のコマンドを実行して、状態とクラウドの ID リストを比較します。

# ECS example
terraform state list | grep alicloud_instance
aliyun ecs describe-instances --biz-region-id $REGION --page-size 100 \
  --output cols=InstanceId rows=Instances.Instance 2>&1

2 つのリストを比較して差分集合を特定し、新しいリソースの HCL とインポートコマンドを生成します。実行前にユーザーに通知し、確認を求めます。

2. 削除されたリソースの検出（状態に存在し、クラウドには存在しない）：

状態にある各リソースの存在を確認します。API が空の結果を返した場合は、次を実行します。

terraform state rm alicloud_instance.<name>

3. 構成ドリフトの検出：

以下のコマンドを実行してドリフトを検出します。

terraform plan -refresh=true 2>&1

増分同期の詳しい手順については、references/incremental-sync.md を参照してください。

---

参考資料

• references/resource-types.md — リソースタイプの完全なマッピング表（20 種類以上）
• references/terraform-patterns.md — HCL コードテンプレートと一般的な差分の修正方法
• references/state-management.md — terraform state コマンドのリファレンス
• references/api-commands.md — aliyun CLI コマンドのクイックリファレンス（ネイティブ製品 API のフォールバック経路）
• references/dependency-rules.md — リソースの依存レイヤーとインポート順序（API B のフォールバック経路）
• references/resource-hub-api.md — ResourceCenter API ガイド（list-resource-types / search-resources / list-resource-relationships）
• references/incremental-sync.md — 増分同期の詳しい手順