terraform-search-import

terraform-search-import 技能概览

terraform-search-import 的作用

terraform-search-import 技能可以帮你用 Terraform Search 查询发现已有云资源，然后批量导入到 Terraform state。它最适合已经有现成基础设施、想把这些资源纳入 Terraform 管理，但又不想逐个手工映射对象的场景。

适合谁使用

这个 terraform-search-import 技能很适合后端开发团队、平台工程师，以及处理迁移、资产盘点或治理任务的运维人员。它在你需要审计未受管资源、统一资源交付方式，或者以更少试错成本从手工云配置迁移到 IaC 时尤其有价值。

它有什么不同

它的核心优势在于先看 provider 支持，而不是先做假设。这个技能会明确检查目标资源类型是否能通过 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，并且 provider 版本支持 list resource。

先做支持性检查

在请求导入方案之前，先运行 ./scripts/list_resources.sh <provider>，或者在提示词里直接检查同样的输出。这是判断 Terraform Search 是否能处理目标对象类型的最快方式。如果资源不在列表里，就应该直接切换到手动导入参考，而不是硬推搜索式流程。

给技能明确的导入目标

高质量提示词要写清 provider、资源类型、范围和目标。比如：“使用 terraform-search-import 发现并批量导入 us-east-1 中 account prod 的所有 aws_s3_bucket 资源，然后展示 Terraform Search 查询和导入步骤。” 输入越具体，越能减少对 region、account，以及你到底是只做发现还是发现加 state 导入的歧义。

先读对的文件

在实际使用 terraform-search-import 时，建议先看 SKILL.md，再看 references/MANUAL-IMPORT.md，最后看 scripts/list_resources.sh。SKILL.md 说明整体工作流，MANUAL-IMPORT.md 提供不受支持资源的回退路径，而脚本则展示了这个技能期望你使用的 provider 能力检查方式。

terraform-search-import 技能常见问题

terraform-search-import 只能做批量导入吗？

不是。它在导入前的资源发现和支持性验证阶段也同样有用。如果你只需要一次性导入单个资源，常规的 Terraform import 流程可能更简单。

什么情况下不该用这个技能？

如果 provider 没有为你的目标类型暴露 list resource 支持，或者你无法在环境中运行 terraform init，就不要使用 terraform-search-import。在这些情况下，手动导入指南会更合适。

这个技能适合新手吗？

适合，但前提是你已经知道自己要管理哪类云资源，并且能识别对应的 provider。这个技能能减少前期配置摩擦，但你仍然需要基本的 Terraform 和 provider 经验，才能正确解读输出并确认导入后的 state。

它和普通提示词有什么区别？

普通提示词可能会直接给出导入步骤，却不会先检查 provider 能力或工具前提。terraform-search-import 指南把流程锚定在 Terraform Search 支持上，这让结果更可执行，也更不容易在后期才失败。

如何改进 terraform-search-import 技能

提供会影响结果的输入

最好的结果来自明确提供 provider、精确资源类型、环境范围，以及你想做的是发现、导入还是两者都要。比如，“找出 dev subscription 中所有受支持的 azurerm_storage_account 资源，然后准备批量导入说明”就远比“导入我的云资源”更有用。

注意最常见的失败模式

最大的失败点，是把 terraform-search-import 用在不受支持的资源上。如果支持性检查没有返回结果，就应该停止并改用 references/MANUAL-IMPORT.md，不要硬凑搜索式方案。这样既省时间，也能让流程始终贴合 provider 的真实能力边界。

按“发现 -> 导入”逐步推进

更稳妥的流程是：先验证支持性，再列出资源，然后缩小范围，确认第一个资源无误后再扩展到全部对象。这样的顺序能帮助你在批量导入造成混乱的 state 之前，及时发现命名不一致、权限缺失，以及 region 或 account 偏移等问题。

用真实资产清单细化提示词

如果你已经知道示例资源名、ARN、ID，或者 account 和 region 的边界，请一并提供。这些信息能帮助 terraform-search-import 生成更精确的查询和更安全的导入方案，尤其适用于后端开发环境里同一类资源可能分布在多个阶段的情况。