Terraform-docs 配置指南：深入解析.terraform-docs.yml文件

皮静滢Annette

于 2025-06-09 09:05:39 发布

阅读量395

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00749/article/details/148524801

Terraform-docs 配置指南：深入解析.terraform-docs.yml文件

terraform-docs Generate documentation from Terraform modules in various output formats 项目地址: https://gitcode.com/gh_mirrors/te/terraform-docs

什么是terraform-docs配置文件

Terraform-docs是一款用于自动生成Terraform模块文档的工具，而.terraform-docs.yml文件则是它的核心配置文件。这个YAML格式的文件允许用户自定义文档生成的各个方面，从内容组织到输出格式都能进行精细控制。

配置文件的位置与优先级

理解配置文件的查找顺序对于团队协作和CI/CD集成至关重要。terraform-docs会按照以下路径顺序查找配置文件：

模块根目录
模块根目录下的.config/文件夹
当前工作目录
当前工作目录下的.config/文件夹
用户主目录下的.tfdocs.d/目录

当找到第一个有效的.terraform-docs.yml文件时，该配置将被采用，其他位置的配置将被忽略。

配置文件的基本结构

配置文件采用YAML格式，主要包含以下几个关键部分：

1. 格式化器设置

formatter是唯一必须指定的选项，它决定了输出文档的格式，如markdown、asciidoc等。

2. 内容控制

header-from和footer-from：指定从哪个文件提取页眉和页脚内容
sections：控制显示或隐藏哪些文档部分
content：直接嵌入自定义内容

3. 输出配置

output.file：指定输出文件路径
output.mode：控制输出模式（注入或覆盖）
output.template：自定义输出模板

4. 排序选项

sort.enabled：是否启用排序
sort.by：排序依据（如按名称）

5. 详细设置

settings部分包含各种微调选项，如：

是否显示锚点
是否使用颜色输出
缩进大小
是否显示敏感字段等

实际应用示例

假设我们有一个Terraform项目结构如下：

.
├── main.tf
├── variables.tf
├── outputs.tf
└── .terraform-docs.yml

对应的.terraform-docs.yml配置可能如下：

formatter: "markdown"

header-from: "main.tf"
footer-from: ""

sections:
  show:
    - header
    - inputs
    - outputs
    - providers
    - requirements

output:
  file: "README.md"
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->

sort:
  enabled: true
  by: "name"

settings:
  indent: 4
  required: true
  sensitive: true

这个配置会生成Markdown格式的文档，包含指定的部分，并按名称排序，最后将结果注入到README.md文件中。