Terraform-Docs Guide with Real-World Examples

Maintaining clear and accurate documentation for Terraform modules is a common challenge for DevOps and cloud engineering teams. terraform-docs is a powerful CLI utility that automatically generates Terraform module documentation directly from your code, ensuring it stays consistent, readable, and always up to date.

This blog post explains how the Terraform documentation generator works, why it matters, and how to use it with real-world examples, outputs, and automation workflows — following all modern SEO best practices.

What Is terraform-docs?

terraform-docs is an open-source command-line tool that scans Terraform configuration files and produces structured documentation. It extracts information such as:

Input variables
Output values
Provider requirements
Terraform version constraints
Resource usage

Instead of manually updating README files, teams can rely on this automation tool to generate documentation that accurately reflects the current Terraform module implementation.

Why Use a Terraform Documentation Generator?

As infrastructure evolves, manually written documentation often becomes outdated. Automating Terraform module documentation helps prevent drift and improves collaboration.

Key Advantages

Keeps documentation aligned with code changes
Reduces manual maintenance effort
Improves onboarding for new engineers
Enforces consistent documentation standards
Integrates easily with CI/CD pipelines

Installing the Terraform Documentation Tool

macOS (Homebrew)

brew install terraform-docs

Linux (Binary Install)

curl -sS https://terraform-docs.io/install.sh | sh

Windows (Chocolatey)

choco install terraform-docs

Docker Usage

docker run --rm -v "$(pwd):/docs" quay.io/terraform-docs/terraform-docs markdown /docs

Example Terraform Module Structure

Consider a simple AWS EC2 module with the following layout:

aws-ec2-module/
├── main.tf
├── variables.tf
├── outputs.tf
├── versions.tf
└── README.md

variables.tf

variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t2.micro"
}

variable "instance_name" {
  description = "Name tag for the EC2 instance"
  type        = string
}

outputs.tf

output "instance_id" {
  description = "ID of the EC2 instance"
  value       = aws_instance.this.id
}

output "public_ip" {
  description = "Public IP address of the EC2 instance"
  value       = aws_instance.this.public_ip
}

Generating Documentation for Terraform Modules

To generate Markdown documentation for the module, run:

terraform-docs markdown table .

This command reads all Terraform files and prints formatted documentation to the terminal.

Injecting Documentation into README.md

Add documentation markers to your README file:

&lt;!-- BEGIN_TF_DOCS -->
&lt;!-- END_TF_DOCS -->

Now inject the generated documentation automatically:

terraform-docs markdown table --output-file README.md --output-mode inject .

This keeps your README synchronized with your Terraform code.

Example Generated Outputs

After running the documentation generator, the README will include tables similar to the following.

Inputs

Name	Description	Type	Default	Required
instance_type	EC2 instance type	string	t2.micro	no
instance_name	Name tag for the EC2 instance	string	n/a	yes

Outputs

Name	Description
instance_id	ID of the EC2 instance
public_ip	Public IP address of the EC2 instance

These tables are produced automatically from the Terraform source files.

Using a Configuration File for Consistency

To standardize documentation settings across projects, create a .terraform-docs.yml file:

formatter: "markdown table"
output:
  file: "README.md"
  mode: "inject"

With this configuration in place, documentation can be generated using a single command:

terraform-docs .

Automating Terraform Documentation in CI/CD

Keeping documentation up to date is easier when automated. The documentation generator can be integrated into CI/CD pipelines.

GitHub Actions Example

name: Generate Terraform Module Docs
on: [pull_request]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: terraform-docs/gh-actions@v1
        with:
          working-dir: .
          output-file: README.md
          output-method: inject

This ensures documentation updates are included with every pull request.

Pre-Commit Hook for Terraform Documentation

You can also enforce documentation generation before commits:

repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: v0.20.0
    hooks:
      - id: terraform-docs-go
        args: ["markdown", "table", "."]

Best Practices for Terraform Module Documentation

Write clear descriptions for variables and outputs
Avoid hardcoding values without explanation
Always include README markers
Automate documentation generation
Review generated docs during code reviews

Conclusion

Automating Terraform module documentation reduces manual effort and prevents documentation drift. By integrating terraform-docs into your workflow, teams can maintain professional, accurate, and scalable infrastructure documentation with minimal overhead.

If you build reusable Terraform modules, adopting this documentation generator is a best practice worth implementing.

DevToolHub