terraform-search-import

terraform-search-import スキルの概要

terraform-search-import でできること

terraform-search-import スキルは、Terraform Search クエリで既存のクラウドリソースを見つけ出し、それらを Terraform state に一括インポートするためのスキルです。すでにインフラが稼働していて、1件ずつ手で対応付けることなく Terraform 管理下に移したいときに最も役立ちます。

どんな人に向いているか

この terraform-search-import スキルは、バックエンド開発チーム、プラットフォームエンジニア、そして移行・棚卸し・ガバナンスの作業に取り組む運用担当者に向いています。特に、未管理のリソースを監査したい、プロビジョニングを標準化したい、あるいは手作業中心のクラウド設定から IaC へ、迷いを減らして移行したい場合に有効です。

何が違うのか

最大の利点は、前提ではなく provider のサポート状況から始める点です。このスキルは、バルクインポートの流れに進む前に、その resource type が Terraform Search で検出可能かどうかを明示的に確認するため、行き止まりや壊れたプロンプトを減らせます。さらに、provider が list resources をサポートしていない場合は、手動での代替手順へ案内します。

terraform-search-import スキルの使い方

インストールして環境を確認する

repo の文脈で terraform-search-import のインストールコマンドを使います: npx skills add hashicorp/agent-skills --skill terraform-search-import。そのうえで、作業ディレクトリで Terraform が初期化済みであること、terraform が利用可能であること、そして jq がインストールされていることを確認してください。ヘルパースクリプトは両方に依存します。このスキルは Terraform >= 1.14 と、list resource をサポートする provider バージョンを前提としています。

まずサポート可否を確認する

インポート計画を依頼する前に、./scripts/list_resources.sh <provider> を実行するか、同じ出力をプロンプト内で確認してください。これが、Terraform Search で対象の object type を扱えるかどうかを最も早く判断する方法です。resource が一覧に出てこない場合は、検索ベースのワークフローを無理に進めず、手動 import の参照に切り替えてください。

具体的なインポート対象を伝える

強いプロンプトには、provider、resource type、scope、目的が入っています。たとえば「terraform-search-import を使って、account prod の us-east-1 にあるすべての aws_s3_bucket resources を検出し一括インポートし、そのうえで Terraform Search query と import 手順を示してほしい」のように依頼します。入力が具体的であるほど、region や account、そして discovery のみか discovery と state import の両方か、といった曖昧さが減ります。

先に読むべきファイル

terraform-search-import を実用的に使うなら、まず SKILL.md、次に references/MANUAL-IMPORT.md、最後に scripts/list_resources.sh を確認してください。SKILL.md にはワークフローが、MANUAL-IMPORT.md には unsupported resource 向けの代替経路が、そして script にはスキルが前提としている provider capability check が書かれています。

terraform-search-import スキルの FAQ

terraform-search-import は一括インポート専用ですか？

いいえ。インポート前の resource discovery やサポート確認にも使えます。単発の単一 resource を 1つだけ import したいのであれば、通常の Terraform import ワークフローのほうがシンプルな場合があります。

どんな場合は使わないほうがいいですか？

対象 type に対して provider が list resource support を提供していない場合や、環境で terraform init を実行できない場合は、terraform-search-import を使わないでください。そうしたケースでは、manual import の案内のほうが適しています。

初心者向けですか？

はい。管理したい cloud resource がすでにわかっていて、provider を特定できるなら使いやすいです。設定の手間は減りますが、出力を解釈して imported state を確認するために、基本的な Terraform と provider の知識は必要です。

一般的なプロンプトと何が違うのですか？

一般的なプロンプトは、provider の capability や tool 前提を確認せずに import 手順を提案してしまうことがあります。terraform-search-import のガイドはワークフローを Terraform Search のサポート状況に結びつけるため、結果がより実行しやすく、後半で失敗しにくくなります。

terraform-search-import スキルを改善するには

結果を変える入力を具体的に渡す

最良の結果を得るには、provider、正確な resource type、environment scope、そして discovery・import・両方のどれを求めているかを伝えてください。たとえば、「subscription dev の対応済み azurerm_storage_account resources をすべて見つけ、そのうえで一括 import 手順を用意してほしい」は、「cloud resources を import してほしい」よりずっと有効です。

よくある失敗パターンに注意する

最大の失敗は、未対応の resource に terraform-search-import を使おうとすることです。support check で何も返らなければ、検索ベースの解決策を押し通そうとせず、references/MANUAL-IMPORT.md を使ってください。これで時間を節約でき、ワークフローを provider の実際の capability に合わせたまま進められます。

discovery から import へ段階的に進める

よい流れは、まず support を確認し、次に resource を列挙し、スコープを狭く切り、その最初の resource が正しいと確認できてから全体へ広げることです。この順番なら、一括 import で state がノイジーになる前に、命名の不一致、権限不足、region や account のずれを見つけやすくなります。

実際の inventory 情報でプロンプトを強化する

すでに例となる resource 名、ARN、ID、account や region の境界がわかっているなら、それを含めてください。そうした情報は terraform-search-import がより絞り込まれた query と、より安全な import plan を作るのに役立ちます。特に、同じ resource type が複数の stage にまたがって存在しうるバックエンド開発環境では効果的です。