alibabacloud-terraform-import

阿里云资源 Terraform 导入向导

分步指南：将阿里云账号下的现有资源导入本地 Terraform 管理。自动执行环境检查、资源发现、HCL 生成、状态导入等操作。用户只需在关键决策点进行确认。

支持两种模式：

• 一次性迁移：端到端完成阶段 1-9
• 增量同步：已有 Terraform 工作目录时，直接跳转到增量同步模式

资源支持范围

• 理论范围：alicloud provider 中任何具有 Read 方法的资源（即可以从云端读取状态的资源）。大多数资源都可以通过 terraform import 命令或 import 块（Terraform 1.5+）直接导入；少数没有 Importer 的资源可以通过手动构造 tfstate 导入，但这要求与 provider 的状态结构精确匹配，并存在一定风险。请在 https://registry.terraform.io/providers/aliyun/alicloud/latest/docs 查看支持状态。
• 预置资源：约 50 种常见资源类型（网络、计算、存储、数据库、负载均衡、DNS、RAM、ACK、FC），其 API 发现命令、HCL 模板和导入 ID 格式已在 references/ 中验证
• 超出预置范围：将即时查阅 provider 文档以提供命令和模板；准确性取决于文档内容，用户应在执行前进行核实

---

命令格式要求

所有 aliyun CLI 命令都必须使用插件模式（小写连字符格式）。禁止使用 CamelCase 命令名称和参数名称。 违反此规则会导致参数错误或调用失败。

示例（正确的插件模式格式）：

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

参数转换规则：

• Region：优先使用 --biz-region-id（业务参数，对应 API 的 RegionId）；仅当 API 的 RegionId 为可选参数时，才应使用 --region（框架参数，用于控制 endpoint 区域）
• 分页：使用 --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）：引导用户访问 https://developer.hashicorp.com/terraform/install 手动安装（需要 root 权限）

所有工具就绪后，进入阶段 2。

配置 aliyun CLI AI-Mode：

必须为所有 aliyun CLI 命令配置 AI-Mode，以便阿里云识别 AI 调用场景并提供优化支持。执行任何 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：身份验证配置

此 Skill 依赖阿里云默认凭证链进行身份验证，支持以下方式（按优先级排序）：

1. 环境变量（ALICLOUD_ACCESS_KEY / ALICLOUD_SECRET_KEY）—— 最高优先级
2. aliyun CLI 配置文件（~/.aliyun/config.json）
3. ECS RAM 角色（仅在 ECS 上运行时）

重要：Terraform alicloud 提供程序和 aliyun CLI 会分别读取凭证，且都优先使用环境变量。当环境变量和 CLI 配置文件中的配置指向不同账号时，以环境变量为准。

验证身份验证：

通过默认凭证链验证身份（不显式传入 AK/SK）：

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。provider 代码块必须包含 configuration_source = "AlibabaCloud-Agent-Skills/alibabacloud-terraform-import"，用于 UA 跟踪
3. 在目标目录中运行 terraform init
4. 分析 init 输出，确认提供程序下载成功
5. （可选增强）运行 terraform providers schema -json，从所有资源中提取以 _id 或 _ids 结尾的字段，为阶段 6 构建引用字段白名单。如果 schema 输出过大导致解析超时，则跳过此步骤；阶段 6 将回退到静态依赖规则进行引用解析
6. **（可选增强）**调用 iacservice list-resource-types（通过分页获取全部结果），将 resourceType 字段中的 ALIYUN 前缀替换为 ACS，以构建 terraformResourceType <-> ResourceCode 双向映射表，并写入 .import/resource-type-mapping.json，供阶段 4/5/6 使用。如果调用失败或权限不足，则回退到 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 中：

• 首先查看 provider 文档（https://registry.terraform.io/providers/aliyun/alicloud/latest/docs），确认是否支持：
  • 有 Import 部分 -> 支持 terraform import，按正常流程继续
  • 没有 Import 部分，但 provider 支持该资源 -> 可通过手动构造 tfstate 导入；继续前告知用户相关风险
  • Provider 完全不支持该资源 -> 明确告知用户无法导入
• 确认支持后，查看 aliyun CLI 文档（https://help.aliyun.com/document_detail/110244.html）或相应的产品 API 文档，了解发现资源的命令

执行相应命令，收集输出，并生成资源发现报告，按类型汇总数量和 ID 列表。

发现结果为空时的处理：

如果某种资源类型（例如 NAT Gateway）未返回结果，但用户认为其应当存在，请主动调查：

• 确认资源是否位于其他 Region
• 确认当前凭证是否具有该资源的 Describe 权限
• 确认资源是否已释放（可检查审计日志）
• 告知用户发现结果与预期不符，并在继续前征求确认

---

阶段 5：选择导入范围和深度

展示资源发现报告，并询问用户：

• 导入全部资源还是选择特定资源类型？
• 按 VPC 范围筛选？
• 按 Tag 筛选？
• 导入深度策略：
  1. 仅导入已发现的资源（不查询相关资源，depth=0）
  2. 导入一层相关资源（depth=1）
  3. 导入完整依赖树（depth=unlimited，推荐）

构建资源依赖图（基于深度策略）

根据用户选择的深度策略：

Depth=0（仅导入已发现的资源）：

• 跳过 API B 调用
• 直接使用 references/dependency-rules.md 中的静态依赖规则对阶段 4 发现的资源排序
• 生成导入顺序

Depth=1（导入一层相关资源）：

• 对于阶段 4 发现的每种资源，如果其类型在 API B 的支持列表中 -> 调用 API B（list-resource-relationships）获取直接相关的资源
• 不要对返回的相关资源递归调用 API B
• 合并已发现的资源和一层相关资源，对资源图进行拓扑排序，生成导入顺序

Depth=unlimited（导入完整依赖树，推荐）：

• 从阶段 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 文件并写入工作目录

每种资源类型对应一个文件，文件名格式：<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/。

跨资源引用解析（三层策略）

为每种资源生成 HCL 时，按照以下优先级判断是否将各字段值替换为 terraform 资源地址：

1. 优先使用 API B 关系：如果资源是通过 API B（list-resource-relationships）发现的，其父级或相关资源已确定。结合阶段 3 提取的引用字段白名单，查找当前资源中类型匹配的 _id 字段，并直接替换为相应的 terraform 资源地址。该关系是确定的，无需猜测。

2. 白名单 + 映射表双重匹配回退：对于 API B 未涵盖的资源，如果字段名称在阶段 3 的引用字段白名单中，且该字段值在资源 ID 映射表中有对应条目，则替换为 terraform 资源地址。

3. dependency-rules.md 静态规则回退：对于上述两层未涵盖的边缘情况（复合 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）
• 保留原始 Tag

---

阶段 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 工作目录已存在时使用此模式。自动检测以下三种变化：

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

比较两个列表，找出差异集，为新增资源生成 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 — 详细的增量同步步骤