Terraform modules are essential building blocks for reusing Terraform configurations. For a Terraform module to be successful, ease of use and discoverability are key. Since creating a Terraform module also goes through a development and maintenance cycle, storing that in a GitHub repository is convenient. By doing so, Organizations improve collaboration, increase transparency, and enhance maintainability. A README file in a GitHub repository is the primary reference for users to understand a project’s purpose and usage. Centralizing this information in a README ensures that module consumers can quickly find what they need to integrate the module into their infrastructure. Maintaining an up-to-date README can be tedious, especially as Terraform modules evolve. This is where terraform-docs comes in. This open-source tool automates the generation of structured documentation from the Terraform configuration files, ensuring that the README remains current, accurate, and consistent without manual updates.

In this note, I demonstrate two use cases where terraform-docs can help auto-generate the README when a pull request is created. I learned about these from the official terraform docs reference guide.

Use-Case 1: CLI-based, out-of-the-box approach This approach aims to automatically update the README.md file whenever a pull request is created. Here’s how to do it:

1. Add Placeholders for terraform-docs In the repository README.md, define placeholders (<!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS -->) where the documentation must be inserted. These placeholders help terraform-docs identify where to place the generated documentation.

When terraform-docs runs, via a GitHub Actions workflow, it will replace the contents between <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS --> with the generated documentation.

2. Set Up terraform-docs in GitHub Actions Pipeline Create a GitHub Actions workflow file to auto-generate the contents to insert in the README.md file. Please check this GitHub Actions workflow file. As you can examine, the workflow triggers only on a pull request and updates the README.md file from the workflow. 109-image-1 This approach is straightforward and does not provide options to the team on all the properties to show or the sequencing of the properties. Here is an example of a README.md file after following this approach. The content from “Requirements” to “Outputs” was auto-generated using terraform-docs.

Use-Case 2: YAML-based, highly customized approach This approach requires a YAML file to store the terraform-docs configuration and generate the README.md file, and it is highly customizable.

1. Create a Custom YAML File The idea behind this approach is to configure terraform-docs using a YAML file containing specific settings and options for generating the documentation. Here’s an example of a YAML configuration file, typically named terraform-docs.yml.

This file defines the format (Markdown), specifies the output location (README.md), and the sections to include in the README (e.g., header, providers, inputs, resources, outputs, footer).

2. Set Up terraform-docs in GitHub Actions Pipeline Create a GitHub Actions workflow file to auto-generate the contents to insert in the README.md file. Please check this GitHub Actions workflow file. As you can examine, the workflow triggers only on a pull request and updates the README.md file from the workflow using the value defined in the config-file property. 109-image-2 This approach allows customization based on the properties selected in the docs.yml file in this repository. Here is an example of a README.md file after following this approach. The content from “Requirements” to “Usage” was auto-generated using terraform-docs. This approach also enabled rendering the main.tf file from the example folder so as to inform the readers how to use this Terraform module.

That brings us to the end of this short note. Based on the project team’s requirements, both approaches work fine. By integrating terraform-docs into the GitHub Actions pipeline, Cloud engineering teams can ensure that the Terraform module documentation stays current and accurate without requiring manual updates.