Terraformer 输出定制指南:hcl/json 格式、compact 紧凑模式与目录结构 path-pattern 玩法
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。