用 Terraform Search…

当需要把未纳管的云资源纳入 Terraform、审计现有基础设施或从手工配置迁移到 IaC 时，用声明式查询发现资源并批量导入。

适用场景

解决思路

1. 先确认目标资源类型是否被支持：运行 ./scripts/list_resources.sh aws 查看指定 provider 的 list 资源，或运行 ./scripts/list_resources.sh 查看所有已配置 provider。
2. 也可手动查询 provider schema：terraform providers schema -json | jq '.provider_schemas | to_entries | map({key: (.key | split("/")[-1]), value: (.value.list_resource_schemas // {} | keys)})'。
3. 确保工作目录已初始化：在 terraform.tf 中声明 required_providers（如 aws source = "hashicorp/aws" version = "~> 6.0"），然后运行 terraform init 下载 provider。
4. 根据支持情况选择工作流：若资源被支持且 Terraform 版本高于 1.14.0，使用 Terraform Search 工作流；若不支持或版本低于 1.14.0，使用手动发现工作流（见 references/MANUAL-IMPORT.md）。
5. 创建 .tfquery.hcl 文件，用 list 块定义搜索查询；查询文件支持 provider 块做认证、list 块做资源发现、variable 和 locals 块做参数化。
6. 编写 list 块：list "<list_type>" "<symbolic_name>" { provider = <provider_reference> ... }，provider 为必填；可选 config 块（schema 因 provider 而异，可用 terraform providers schema -json | jq '.provider_schemas."registry.terraform.io/hashicorp/<provider>".list_resource_schemas."<resource_type>"' 查看）和 limit 限制结果数。
7. 在 config 块中使用 filter 过滤结果，例如按标签 filter { name = "tag:Environment" values = ["production"] }，或按类型 filter { name = "instance-type" values = ["t3.large", "t3.xlarge"] }。
8. 做多区域发现：用 locals 定义 regions 列表，在 list 块中用 for_each = toset(local.regions) 并在 config 中设置 region = each.value。
9. 做参数化查询：定义 variable（如 target_environment），在 filter 的 values 中引用 var.target_environment。
10. 运行 terraform query 执行查询并显示结果；输出格式为 <query_address> <identity_attributes> <name_tag>。
11. 用 terraform query -generate-config-out=imported.tf 生成配置文件；用 terraform query -var='target_environment=production' 传入变量。
12. 检查生成的配置：-generate-config-out 会生成带 __generated__ 注释的 resource 块和基于 identity 的 import 块（Terraform 1.12+）。
13. 对生成配置做清理：移除 computed/只读属性（如 arn、id），把硬编码值替换为变量，添加合理的资源命名，并组织到合适的文件中。
14. 运行 terraform plan 和 terraform apply 执行导入。
15. 导入后用 terraform state list 确认资源已被管理并核对地址；用 terraform show -json | jq '.values.root_module.resources[] | {address, type, name}' 查看已导入资源的属性值（需先 terraform init）。
16. 仅在 provider 不可用且无法 init、只需粗略信息（地址、outputs、serial/lineage）或必须避免执行 Terraform 时，才回退到原始 state（terraform state pull / terraform.tfstate）；不要把原始 version-4 state 格式当作稳定接口解析。
17. 注意 state 在所有格式中都包含明文敏感值，绝不要把 state 内容回显到日志或输出中。
18. 查询设计上先宽后窄：先广泛搜索再加 filter 缩小结果，用 limit 防止输出过多，生成配置前先测试查询。
19. 配置管理上：应用前审查所有生成代码，移除不必要的默认值，使用一致的命名约定，并做好变量抽象。
20. 排障：出现 "No list resources found" 时检查 provider 版本是否支持 list 资源；查询为空时核对 region 和 filter 值；生成配置报错时移除 computed 属性并修复废弃参数；导入失败时确认资源尚未在 state 中。

适用边界 · 注意事项

• 目标资源类型不被 provider 的 list 资源支持，或 Terraform 版本低于 1.14.0 时，应改用手动发现工作流。
• provider 未安装且无法运行 terraform init 时，无法使用 terraform show -json，只能回退到原始 state 做粗略检查。
• 资源已在 state 中时不要重复导入。