Automating Terraform Documentation with terraform-docs: The Complete Guide

While working on large projects, I encountered many Terraform repositories with no documentation. Going through each repository’s code to understand what it does is painful. I always wished for a genie to come out of a bottle and document everything for me and my team.

In my org, we made a rule: Never approve a Terraform module PR without documentation. Problem solved? Nope! Now, everyone’s grumbling about writing docs manually.

I strongly believe everyone should document their modules, but doing it manually is a pain. This is where Terraform-docs, an open-source and easy-to-use tool, comes in.

Terraform docs solve this problem, and I’ll show you how easy it is to use and automate it with pre-commit hooks or GitHub Actions.

Why terraform-docs is Essential for Your Infrastructure as Code

Before diving into the how, let’s quickly cover the why:

  • Consistency: Ensures uniform documentation across all your Terraform projects
  • Automation: Completely eliminates manual documentation tasks
  • Accuracy: Documentation is always in sync with your actual code
  • Customization: Flexible output formats and templates to match your project needs
  • Developer-friendly: Easy to set up and integrate into existing workflows

How to Automate Perfect Terraform Documentation with terraform-docs, Pre-commit Hooks, and GitHub Actions

How to Install terraform-docs on Different Platforms

Installing terraform-docs is straightforward across different platforms:

macOS

brew install terraform-docs

On Linux

curl -Lo ./terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.16.0/terraform-docs-v0.16.0-$(uname)-amd64.tar.gz
tar -xzf terraform-docs.tar.gz
chmod +x terraform-docs
mv terraform-docs /usr/local/bin/

Windows

choco install terraform-docs

You can also follow the official documentation for additional installation methods.

Since I use Mac, I will use brew to install it.

Check the installation

terraform-docs --version

Getting Started with terraform-docs

For this tutorial, I’ll use a sample Terraform module. You can clone it to follow along:

git clone https://github.com/akhileshmishrabiz/terraform-google-workstation
cd terraform-google-workstation

Basic Command Syntax

The general syntax for terraform-docs is:

terraform-docs [FORMAT] --output-file [FILE] --output-mode [MODE] [PATH]

Where:

  • [FORMAT]: The output format (markdown, json, yaml, etc.)
  • --output-file [FILE]: Specifies the output file (e.g., README.md)
  • --output-mode [MODE]: How to write output (inject or replace)
  • [PATH]: Path to the Terraform module

Available Output Formats

terraform-docs supports multiple output formats:

  • asciidoc
  • json
  • markdown
  • markdown document
  • markdown table
  • pretty
  • tfvars hcl
  • tfvars json
  • toml
  • xml
  • yaml

Output Modes

  • inject: Inserts documentation between specified markers in the output file
  • replace: Replaces the entire output file with generated documentation

Default Template

By default, terraform-docs uses this template:

<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->

Running terraform-docs to Generate Documentation

Let’s generate documentation for our module using the markdown table format:

terraform-docs markdown table --output-file README.md --output-mode inject .
  • --output-file README.md: specifies the output file
  • --output-mode inject: This option specifies the mode in which the generated documentation will be injected into the specified output file.
  • Another option is replace – It replaces the output-file with generated output

This will create a README.md file with documentation.

Trying Different Output Formats for terraform-docs

Let’s try generating the YAML format:

terraform-docs yaml --output-file README.md --output-mode replace .

Markdown is the most commonly used format for code documentation, but you can use other ones too.

Using Configuration Files for terraform-docs

Instead of passing many command-line arguments, you can use a configuration file.

And I suggest that you do as you can keep this config file within your code, so everyone can use the same configuration and you don’t have to leave any angry comments in PR.

The default config file is .terraform-docs.yml, but you can use some other name as well.

You can terraform-docs command with -c flag to pass the config file

# Generating the terraform documentation with config file
terraform-docs -c [CONFIG_FILE] [PATH]

Let’s create a config file .terraform-docs.yml:

formatter: json # this is required
content: ""
output:
  file: USAGE.md # output-file
  mode: replace
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->    
output-values:
  enabled: false
  from: ""
sort:
  enabled: true
  by: name
settings:
  anchor: true
  escape: true
  hide-empty: true
  html: true
  indent: 4
  lockfile: true

Now run:

# This will take the default config 
terraform-docs .

# Or you can pass a config file with -c flag
terraform-docs -c .terraform-docs.yml .

Using Docker for terraform-docs

If you prefer not to install terraform-docs locally, you can use Docker:

docker run --rm --volume "$(pwd):/src" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.16.0 markdown table /src

Automating Terraform Documentation with Pre-commit Hooks

One of the most powerful ways to ensure your documentation stays up-to-date is by using pre-commit hooks. This prevents you from committing code changes without updating the documentation.

Setting Up Pre-commit

First, install pre-commit:

pip install pre-commit

Next, create a .pre-commit-config.yaml file in your repository root:

repos:
- repo: https://github.com/terraform-docs/terraform-docs
  rev: "v0.16.0"
  hooks:
    - id: terraform-docs-go
      args: ["--output-file", "README.md", "."]

For a more advanced configuration, you can reference a terraform-docs config file instead:

repos:
- repo: https://github.com/terraform-docs/terraform-docs
  rev: "v0.16.0"
  hooks:
    - id: terraform-docs-go
      args: ["--config", ".terraform-docs.yml"]

Initialize pre-commit in your repository:

pre-commit install

Now, whenever you try to commit changes to your Terraform files, pre-commit will automatically run terraform-docs and update your documentation. If there are any changes to the documentation, the commit will fail, allowing you to add the updated documentation to your commit.

I will use the pre-commit with terraform-docs config file.

Creating a terraform-docs Configuration File for Pre-commit

Create a .terraform-docs.yml file:

formatter: markdown table # output format
version: ""
header-from: main.tf
footer-from: ""
content: ""
output:
  file: README.md
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->
output-values:
  enabled: false
  from: ""
sort:
  enabled: true
  by: name
settings:
  anchor: true
  color: true
  default: true
  description: true
  escape: true
  hide-empty: false
  html: true
  indent: 2
  lockfile: true
  required: true
  sensitive: true
  type: true

Now commit the changes, and the pre-commit hook should automatically create the USAGE.md file for you.

Automating Terraform Documentation with GitHub Actions

For team environments, GitHub Actions provide another excellent way to automatically update documentation:

Create a workflow file at .github/workflows/terraform-docs.yaml:

name: Generate terraform docs
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  docs:
    runs-on: ubuntu-latest
    permissions:
        contents: 'read'
        id-token: 'write'
    steps:
    - uses: actions/checkout@v3
      with:
        ref: ${{ github.event.pull_request.head.ref }}
    - name: Render terraform docs inside the README.md and push changes back to PR branch
      uses: terraform-docs/gh-actions@v1.0.0
      with:
        working-dir: .
        output-file: README.md
        output-method: replace
        config-file: .terraform-docs.yml
        git-push: "true"  # This will commit and push the changes

Also, create a .terraform-docs.yml configuration file:

formatter: markdown table # this is required
version: ""
header-from: main.tf
footer-from: ""
content: ""
output:
  file: README.md # output-file
  mode: replace
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->    
output-values:
  enabled: false
  from: ""
sort:
  enabled: true
  by: name
settings:
  anchor: true
  color: true
  default: true
  description: true
  escape: true
  hide-empty: true
  html: true
  indent: 4
  lockfile: true
  required: true
  sensitive: true
  type: true

With this setup, your documentation will automatically update on every pull request or push to main.

Best Practices for terraform-docs

  • Always Use Version Control: Commit your terraform-docs configuration file to your repository
  • Combine with Pre-commit Hooks: Prevent documentation drift with pre-commit hooks
  • Document Your Variables Properly: Use meaningful descriptions in your variable blocks
  • Customize for Your Team: Adjust the output format to what works best for your team
  • Automate Everything: Use GitHub Actions for Team Environments

Final Thoughts on Automating Terraform Documentation

Let’s be real – nobody wakes up excited to write documentation. But with terraform-docs, you don’t have to! Set it up once with pre-commit hooks or GitHub Actions, and boom – your documentation updates itself forever.

If you found this helpful, smash that clap button 👏 so others can discover it too.

Additional Resources for terraform-docs

  • terraform-docs Official Documentation
  • GitHub Repository
  • Pre-commit Hooks Documentation

Akhilesh Mishra

Akhilesh Mishra

I am Akhilesh Mishra, a self-taught Devops engineer with 11+ years working on private and public cloud (GCP & AWS)technologies.

I also mentor DevOps aspirants in their journey to devops by providing guided learning and Mentorship.

Topmate: https://topmate.io/akhilesh_mishra/