terraform-docs 模块文档自动生成

文档漂移是怎么发生的

Terraform 模块的变量、输出和 providers 声明散落在 variables.tf、outputs.tf、main.tf 中，而模块文档通常写在 README 里，靠人手工维护。第一次迭代加了参数、改了输出名之后，两者就开始分叉：

• 使用者按过时文档传参，踩到 Unsupported argument 或拼错参数名。
• 审查者拿到的 terraform plan 与文档描述不一致，难以判断变更范围。
• 上游 provider 升级后，文档里声明的依赖已经过期。

这类问题不会在 terraform validate 里暴露——校验只看语法，不看文档。

技能如何工作

terraform-docs 把模块目录当作唯一事实来源，解析 Terraform 配置，生成 Markdown 或 JSON 形式的变量、输出、providers、resources 列表。

核心能力：

• 从源码生成：variables 的 description、类型、默认值，以及 outputs 的 sensitive 标记，全部取自代码而非手写。
• 模板与排序：支持自定义 README 模板和 --sort-by，让生成段落固定插入到文档的指定位置。
• CI 中校验漂移：用 --check 在文档与代码不一致时让流水线失败，把漂移挡在合并之前。

关键步骤：

1. 在模块根目录执行生成命令，产出文档片段。
2. 通过模板或 --output-file 把片段写回 README.md。
3. 在 PR 流程中加一步校验，确保新增参数必须同步更新文档。

适用边界与注意点

• 只覆盖文档层面：它不会补全设计意图，比如某个 variable 为什么允许 0-100，这类说明仍要人写。
• 依赖 Terraform 配置能被正常解析；terraform init 未完成或 provider 未拉取时，部分推断可能不准确。
• sensitive 输出不会泄露真实值，但也不要把敏感变量的具体取值贴进文档。
• 多模块仓库需要为每个模块单独运行，脚本化时注意路径遍历。