使用Terraform-docs与pre-commit自动化生成文档

使用Terraform-docs与pre-commit自动化生成文档

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

在现代基础设施即代码(IaC)开发中，保持文档与代码同步是一个常见挑战。Terraform-docs项目提供了一种优雅的解决方案，结合pre-commit工具可以实现文档的自动化生成和更新。本文将详细介绍如何配置和使用这套工作流。

为什么需要自动化文档

在Terraform模块开发过程中，随着变量、输出和资源定义的变更，手动维护README文档既耗时又容易出错。自动化文档生成可以：

1. 确保文档始终反映模块最新状态
2. 减少开发人员手动维护文档的负担
3. 提高团队协作效率
4. 保持文档风格一致性

基础配置方法

1. 安装pre-commit工具

首先需要在开发环境中安装pre-commit工具。这是一个Git钩子管理框架，可以在提交代码前自动执行特定任务。

2. 创建配置文件

在项目根目录下创建或修改.pre-commit-config.yaml文件，添加以下内容：

repos:
  - repo: terraform-docs/terraform-docs
    rev: "v0.16.0"  # 使用最新稳定版本
    hooks:
      - id: terraform-docs-go
        args: ["--output-file", "README.md", "."]

这个配置指定了：

• 使用terraform-docs的Go实现
• 输出到README.md文件
• 扫描当前目录下的Terraform文件

3. 安装钩子

运行以下命令安装并激活钩子：

pre-commit install

高级配置技巧

多模块支持

对于包含多个子模块的项目，可以配置多个钩子：

hooks:
  - id: terraform-docs-go
    args: ["--output-file", "README.md", "modules/network"]
  - id: terraform-docs-go
    args: ["--output-file", "README.md", "modules/database"]

自定义输出格式

terraform-docs支持多种输出格式，可以通过参数指定：

args: ["--output-format", "markdown table", "--output-file", "README.md", "."]

Docker集成方案

对于没有Go环境的开发团队，可以使用Docker版本的terraform-docs：

repos:
  - repo: local
    hooks:
      - id: terraform-docs
        name: terraform-docs
        language: docker_image
        entry: quay.io/terraform-docs/terraform-docs:latest
        args: ["--output-file", "README.md", "."]
        pass_filenames: false

Git原生钩子方案

如果不使用pre-commit，也可以直接创建Git钩子脚本。在.git/hooks/pre-commit文件中添加：

#!/bin/sh

# 为所有模块生成文档
for d in modules/*; do
  if terraform-docs md "$d" > "$d/README.md"; then
    git add "$d/README.md"
  fi
done

记得给脚本添加执行权限：

chmod +x .git/hooks/pre-commit

最佳实践建议

1. 版本锁定：始终指定terraform-docs的具体版本，避免因版本更新导致格式变化
2. 团队统一：确保团队所有成员使用相同的配置
3. CI集成：在持续集成流程中也加入文档检查
4. 格式审查：结合markdown lint工具确保生成文档的美观性
5. 自定义模板：根据团队需求定制输出模板

通过这套自动化文档工作流，团队可以显著减少文档维护成本，同时提高基础设施代码的可维护性和可读性。

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