📚 课程目录第3章 terraform import命令基础

3. terraform import 命令基础

terraform import 是 Terraform 工作流中用于将已有云上资源纳入状态管理的核心命令。它不生成配置代码，而是将外部资源的标识符与状态文件中的地址绑定，使 Terraform 能够感知并管理该资源。理解其语法、工作原理和限制，是掌握资源导入与状态修复的前提。

3.1 import 命令语法

基本语法结构如下：

terraform import [options] <ADDRESS> <ID>

参数	说明	示例
`<ADDRESS>`	Terraform 资源地址，格式为 `资源类型.资源名称`，支持模块路径	`aws_instance.web`、`module.vpc.aws_subnet.public`
`<ID>`	云服务商提供的资源唯一标识符，格式由 Provider 定义	`i-0abcd1234efgh5678`、`subnet-12345678`
`-var`	导入时传入变量（部分 Provider 需要）	`-var="region=us-east-1"`
`-var-file`	指定变量文件	`-var-file="prod.tfvars"`
`-config`	指定配置目录（默认当前目录）	`-config=./infra`

  关键约束：执行 terraform import 前，目标资源地址对应的配置代码必须已存在于 .tf 文件中。如果配置不存在，导入会失败并提示资源地址未定义。

完整执行示例：

# 1. 确保配置文件中已定义资源
# resource "aws_instance" "web" { ... }

# 2. 执行导入
terraform import aws_instance.web i-0abcd1234efgh5678

# 3. 验证状态
terraform state list | grep aws_instance.web

3.2 import 命令工作原理

terraform import 的执行流程分为三个阶段：地址解析、Provider 读取、状态写入。下图展示了完整的内部工作路径：

三个阶段的具体职责：

地址解析：Terraform 解析 <ADDRESS>，在配置目录中查找对应的 resource 块。如果地址包含模块路径（如 module.network.aws_vpc.main），会递归解析模块嵌套关系。
Provider 读取：调用对应 Provider 的 Read() 方法，使用 <ID> 向云服务商 API 发起请求，获取资源的完整属性集合。此阶段会验证资源是否存在，若不存在则报错。
状态写入：将读取到的属性写入当前工作目录的 terraform.tfstate 文件中，与资源地址绑定。导入完成后，terraform plan 会对比配置代码与状态中的属性差异。

实践要点：导入成功后，建议立即执行 terraform plan 查看配置与真实资源之间的差异。如果配置中未定义任何属性值，plan 会显示大量变更，此时需要将状态中的属性值复制到配置文件中。

3.3 import 命令使用限制

虽然 terraform import 是状态修复的利器，但它存在若干硬性限制，需要在实际操作中规避：

限制类别	具体描述	影响与应对
配置必须预定义	导入前必须在 `.tf` 文件中声明对应的 `resource` 块，即使块内属性为空	需手动编写或使用 `terraform-provider-xxx` 的 import 文档生成骨架
不支持批量导入	每次只能导入一个资源，无法通过通配符或列表批量操作	需编写脚本循环调用 import，或使用 `terraform state mv` 辅助重组
不生成配置代码	import 只更新状态文件，不会自动生成或补全 `.tf` 中的属性	需手动从状态中提取属性（`terraform state show`）并写入配置
依赖资源顺序	如果资源存在依赖关系（如安全组规则依赖安全组），需按依赖顺序导入	先导入被依赖资源，再导入依赖资源，否则 plan 可能报错
Provider 版本兼容	部分旧版本 Provider 的 import 实现不完整，可能丢失某些属性	保持 Provider 版本为最新稳定版，导入后使用 `terraform plan` 验证完整性
模块内资源导入	模块内的资源地址格式为 `module.<模块名>.<资源类型>.<资源名>`，需精确匹配	使用 `terraform state list` 确认模块路径，避免地址拼写错误

常见陷阱：导入后直接执行 terraform apply 可能导致资源被替换或删除。因为配置代码中的属性可能为空或默认值，与真实资源属性不一致。正确的做法是：导入 → terraform plan 查看差异 → 手动调整配置代码匹配真实属性 → 再次 plan 确认无变更 → 执行 apply。

下图总结了 import 命令的输入、输出与核心限制之间的关系：

理解这些限制后，在实际项目中应遵循以下操作顺序：

在 .tf 文件中定义目标资源的空骨架配置。
执行 terraform import 将资源纳入状态。
使用 terraform state show <ADDRESS> 查看导入后的完整属性。
将属性值手动复制到配置文件中，确保配置与真实资源一致。
执行 terraform plan 确认无预期外变更。

  最佳实践：对于需要批量导入的场景，建议编写 Shell 或 Python 脚本，循环调用 terraform import，并结合 terraform state pull 和 terraform state push 进行状态合并。对于大规模迁移，可考虑使用 terraformer 或 terracognita 等第三方工具生成配置代码和状态文件。