How to auto generate Terraform documentation

Introduction

Terraform has become an indispensable tool for managing infrastructure as code (IaC) across a variety of providers. However, as with any IaC, understanding and documenting the infrastructure you’re provisioning is crucial for effective team collaboration and maintenance. In this tutorial, we will cover how you can automatically generate documentation for your Terraform configurations, enhancing your infrastructure management practices.

Getting Started with Terraform Documentation

Before diving into the auto-generation of Terraform documentation, ensure you have Terraform installed and a basic understanding of its syntax and file structure. Let’s start by understanding the value of automating documentation generation.

Automating the generation of documentation for your Terraform modules can significantly enhance the maintainability and clarity of your infrastructure code. It ensures that as your infrastructure evolves, your documentation stays up-to-date with minimal effort.

Basic Documentation Generation

The simplest way to start generating documentation for your Terraform modules is by using the terraform-docs tool. This tool extracts information from Terraform modules and generates documentation in various formats like Markdown, JSON, and others.

Installation: Install terraform-docs via Homebrew or download it directly from GitHub:

$ brew install terraform-docs

Usage: Navigate to your Terraform module directory and run:

$ terraform-docs markdown . > README.md

This command generates a Markdown formatted README file with information about inputs, outputs, providers, and modules used in your Terraform module.

Advanced Documentation Techniques

While terraform-docs provides a solid foundation, you might seek more control and detail in your documentation. Advanced techniques include integrating documentation generation into your CI/CD pipeline and customizing the content of your documentation.

Integration with CI/CD: Automating the generation of your Terraform documentation within your CI/CD pipeline ensures that your documentation is automatically updated whenever your infrastructure code changes. Here’s an example using GitHub Actions:

name: Generate Terraform Documentation

on:
  push:
    branches:
      - main

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v2
      - name: Generate Documentation
        uses: terraform-docs/gh-actions@v1
        with:
          working-dir: .
          output-file: README.md
          output-method: replace

This GitHub Action checks out your code, generates the documentation using terraform-docs, and updates the README file in your repository.

Customization: Terraform-docs supports various flags and options to customize the output. For instance, you can control which sections are included or excluded from your documentation.

$ terraform-docs markdown table --output-file README.md --output-mode inject . --hide modules,providers

This command generates a table format documentation but excludes information about providers and modules, helping focus on the most important aspects of your Terraform configuration.

Documentation with Pre-commit Hooks

Another advanced technique is using pre-commit hooks to ensure documentation is generated every time you commit changes. This approach requires the pre-commit framework and a small configuration.

repos:
-   repo: git://github.com/antonbabenko/pre-commit-terraform
    rev: v1.50.0
    hooks:
    -   id: terraform_docs

Add this to your .pre-commit-config.yaml file and install pre-commit hooks in your repository:

$ pre-commit install

Now, every commit will automatically trigger the documentation generation, ensuring your docs are always in sync with your code.

Conclusion

Automatically generating documentation for Terraform configurations simplifies infrastructure management, ensures documentation accuracy, and improves team collaboration. By integrating tools like terraform-docs into your workflow through basic commands, CI/CD pipelines, or pre-commit hooks, you can maintain up-to-date documentation with minimal effort. As Terraform projects grow in complexity, adopting these practices becomes essential for managing your infrastructure efficiently.