Terraformer 输出定制指南:hcl/json 格式、compact 紧凑模式与目录结构 path-pattern 玩法

原创2026-09-21 12:31:411,647 阅读
文章标签:开发工具CLIIaC

Terraformer 输出定制指南:hcl/json 格式、compact 紧凑模式与目录结构 path-pattern 玩法

Terraformer 是一个"反向 Terraform"CLI 工具:把云上已有的基础设施自动扫描并生成 Terraform 配置文件。而真正决定"生成出来的代码长什么样、放在哪里"的,正是它的输出定制能力——输出格式(hcl/json)、文件粒度(compact 紧凑模式)与目录结构(path-pattern)。本文带你一次吃透这三大关键参数 🎯

💡 需要源码构建时:git clone https://gitcode.com/gh_mirrors/ter/terraformer

输出参数速查表

所有输出相关参数在各 provider 子命令下通用,定义见 cmd/import.go:

参数 短写 默认值 作用
--output -O hcl 输出文件格式:hcl 或 json
--compact -C false 紧凑模式,所有资源合并到一个文件
--path-pattern -p {output}/{provider}/{service}/ 生成目录的模板
--path-output -o generated 替换模板中的 {output} 占位符
--no-sort -S false 禁用 HCL 内容自动排序
--state -s local state 文件存本地或 gs:// bucket

三个默认值常量定义在 cmd/import.go。

1️⃣ hcl 还是 json?用 --output 一键切换

Terraformer 默认输出 HCL 语法的 .tf 文件(人读友好、社区主流);加上 -O json 后,输出即变为 Terraform 原生 JSON 语法,文件扩展名自动切换为 .tf.json。扩展名选择逻辑见 terraformutils/terraformoutput/hcl.go。

# 默认:HCL 输出
terraformer import google -r vpcs --projects demo-project -z us-central1

# JSON 输出
terraformer import google -r vpcs --projects demo-project -z us-central1 -O json

怎么选?

  • 📖 交给团队人工审阅、二次编辑 → 选 hcl(默认);
  • 🤖 需要程序化生成/比对(CI 流水线、diff 工具)→ 选 json,结构稳定、无格式抖动。

⚠️ 小技巧:HCL 输出默认会对资源块排序以保证输出可复现(见 terraformutils/hcl.go);如果你的上游有特定字段顺序要求,可用 -S 关闭排序。

2️⃣ compact 紧凑模式:一堆小文件 vs 一个资源大文件

默认情况下,Terraformer 会按资源类型拆分文件:aws_s3.tf、aws_instance.tf、aws_route53_record.tf…… 资源种类多时目录下会出现几十个小文件。

加上 -C(--compact)后,该目录下所有资源合并进单个 resources.tf,文件数量从 N 变成 1。这个分支逻辑位于 terraformutils/terraformoutput/hcl.go。

模式 文件布局 适用场景
默认(分类型) vpc.tf + subnet.tf + s3.tf … 资源种类少、想按类型维护
-C 紧凑模式 仅 resources.tf 资源杂而多、只需一个文件整体交付
# 紧凑模式示例
terraformer import aws -r ec2 -C -O hcl

3️⃣ path-pattern:目录结构的终极玩法

--path-pattern 是一个带占位符的路径模板,占位符由 cmd/import.go 的 Path() 函数统一替换:

  • {output} → --path-output 的值(默认 generated)
  • {provider} → 云厂商名(google、aws、azure…)
  • {service} → 资源服务名(vpcs、compute…)

几个常用玩法:

# ① 默认:generated/{provider}/{service}/
terraformer import google -r vpcs --projects demo -p "{output}/{provider}/{service}/"

# ② 自定义根目录:out/ 下按厂商归档
terraformer import aws -r ec2 -o out -p "{output}/{provider}/{service}/"

# ③ 去掉 service 层级,扁平化
terraformer import aws -r ec2 -p "{output}/{provider}/"

🌟 进阶:GCP 多项目场景下,Terraformer 会自动把模板中的 {provider}/{service} 替换为 {project}/{region} 结构(见 cmd/provider_cmd_google.go),天然实现"项目/区域"两级目录隔离。

4️⃣ 每个输出目录里都有哪些文件?

无论哪种模式,每个服务目录下都会生成一套完整可 terraform plan 的文件:

generated/
└── google/
    └── vpcs/
        ├── provider.tf        # 所需 provider 版本声明
        ├── outputs.tf         # 资源 ID 的 output 引用
        ├── resources.tf       # 紧凑模式;否则为按类型拆分的多个 .tf
        ├── variables.tf      # --connect 开启时生成资源间引用
        └── terraform.tfstate  # 生成的 state,可直接 terraform import 衔接

其中 terraform.tfstate 是关键:配合 --connect(默认开启),跨服务引用会通过 terraform_remote_state 写入 variables.tf,让生成的多目录配置能互相引用而不用改 ID 硬编码。

5️⃣ 加分项:planfile 两阶段导入

输出定制参数同样适用于"计划文件"流程:先用 plan 子命令把扫描结果落盘为 plan.json(导出逻辑见 cmd/plan.go),之后再执行 import <provider> plan 生成配置。好处是扫描只发生一次,格式/目录调整(换 -O json、改 -p 模板)时无需重复拉取云资源,特别适合反复调试输出样式。

总结:三参数一分钟决策

你的需求 推荐组合
团队审阅、常规导入 默认 hcl + 默认分类型 + 默认 path-pattern
机器处理 / CI 比对 -O json
资源杂多、想要单文件交付 追加 -C
按项目/环境隔离目录 自定义 -p,如 "{output}/{provider}/"

掌握 --output、--compact、--path-pattern 三个参数,你就完全掌控了 Terraformer 的产物形态——从"能跑"到"好用",只差这几行参数。

更多各云厂商的资源与过滤示例,可参考官方文档目录 docs/,例如 docs/aws.md 与 docs/gcp.md。

登录后查看全文
terraformer