Docker镜像：terraform-docs

镜像概述和主要用途

基于Alpine Linux的轻量级多阶段构建Docker镜像，包含terraform-docs工具及其扩展功能terraform-docs-replace。该工具用于生成Terraform模块的文档，并能在文件中自动安全地替换生成的文档内容。镜像支持多架构，提供多个稳定版本，每日构建并推送到Docker Hub，兼容Terraform >=0.12，适用于CI/CD和自动化文档生成场景。

核心功能和特性

• 轻量级基础：基于Alpine Linux，镜像体积小，资源占用低
• 多架构支持：兼容amd64、i386、arm64、arm/v7、arm/v6（不同版本架构支持可能不同）
• 多版本支持：提供多个terraform-docs版本标签，满足不同项目需求
• 自动替换功能：集成terraform-docs-replace，可在文件中指定分隔符之间自动更新文档块
• Terraform兼容性：支持Terraform >=0.12（通过terraform-docs-012命令）和旧版本（terraform-docs命令）

可用版本

滚动发布版本（每日更新）

固定发布版本（一次性构建）

环境变量

Docker挂载

容器内工作目录为/data/，需将本地Terraform模块所在目录挂载到此路径，以便工具访问模块文件：

-v $(pwd):/data

使用方法

通用用法

Usage: cytopia/terraform-docs terraform-docs <ARGS> .
       cytopia/terraform-docs terraform-docs-012 <ARGS> .

       cytopia/terraform-docs terraform-docs-replace <ARGS> <PATH-TO-FILE>
       cytopia/terraform-docs terraform-docs-replace-012 <ARGS> <PATH-TO-FILE>

terraform-docs              标准terraform-docs输出（适用于Terraform <0.12）
terraform-docs-012          适用于Terraform >=0.12的terraform-docs输出
terraform-docs-replace      在文件中替换文档块（适用于Terraform <0.12）
terraform-docs-replace-012  在文件中替换文档块（适用于Terraform >=0.12）
<ARGS>                      terraform-docs支持的所有参数
<PATH-TO-FILE>              要替换文档块的文件路径

输出到stdout

生成Markdown格式文档并输出到标准输出：

# [Terraform < 0.12]
docker run --rm \
  -v $(pwd):/data \
  cytopia/terraform-docs \
  terraform-docs --sort-by-required md .

# [Terraform >= 0.12]
docker run --rm \
  -v $(pwd):/data \
  cytopia/terraform-docs \
  terraform-docs-012 --sort-by-required md .

存储到文件

将生成的文档保存到文件（如README.md）：

# [Terraform < 0.12]
docker run --rm \
  -v $(pwd):/data \
  cytopia/terraform-docs \
  terraform-docs --sort-by-required md . > README.md

# [Terraform >= 0.12]
docker run --rm \
  -v $(pwd):/data \
  cytopia/terraform-docs \
  terraform-docs-012 --sort-by-required md . > README.md

替换文件中的文档块

在现有文件（如README.md）中替换文档块，需确保文件中包含默认分隔符：

<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
## Inputs
...
<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

执行替换命令：

# [Terraform < 0.12]
docker run --rm \
  -v $(pwd):/data \
  cytopia/terraform-docs \
  terraform-docs-replace --sort-by-required md README.md

# [Terraform >= 0.12]
docker run --rm \
  -v $(pwd):/data \
  cytopia/terraform-docs \
  terraform-docs-replace-012 --sort-by-required md README.md

使用自定义分隔符

通过环境变量自定义分隔符，例如INFO.md中使用<!-- TFDOC_START -->和<!-- TFDOC_END -->：

# [Terraform < 0.12]
docker run --rm \
  -v $(pwd):/data \
  -e DELIM_START='<!-- TFDOC_START -->' \
  -e DELIM_CLOSE='<!-- TFDOC_END -->' \
  cytopia/terraform-docs \
  terraform-docs-replace --sort-by-required md INFO.md

# [Terraform >= 0.12]
docker run --rm \
  -v $(pwd):/data \
  -e DELIM_START='<!-- TFDOC_START -->' \
  -e DELIM_CLOSE='<!-- TFDOC_END -->' \
  cytopia/terraform-docs \
  terraform-docs-replace-012 --sort-by-required md INFO.md

示例项目

以下项目展示了如何在CI中使用此镜像验证README.md是否更新了最新文档：

• [***]
• [***]

相关项目

Docker镜像

以下是相关的CI工具Docker镜像，可用于代码分析和自动化测试：