Overview

As we all know, the importance of documentation in software development becomes visibly apparent when knowledge or information needs to be shared about the project or code.

Even if you write and develop IaC (Infrastructure as Code) using terraform, working in a team or sharing your terraform modules with others, you're most likely going to want to create some sort of documentation about your terraform code/modules so that others may understand the code better, or to give more information on how to use your modules.

Today we are going to look at a cool tool that can be used to "automagically" generate your Terraform module documentation called terraform-docs.

If you want a quick autonomous way to document your terraform modules you're going to love this tool. We will look at how the tool can be used manually first followed by how it can be automated in CI/CD using GitHub Actions.

Manual Usage

If you want to use this tool locally there are a few ways that you can install it on your development machine which is documented here: terraform-docs Installation. In my case I am using a Windows machine and will use Chocolatey to install the tool:

• First install 'Chocolatey' (Online instructions):

Open an Administrative shell and run:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

NOTE: After chocolatey is installed you'll need to restart your shell session.

• Next install 'terraform-docs':

choco install terraform-docs

Example

Now with the tool installed locally I can simply run the following command to generate a markdown table:

terraform-docs markdown table [/path/to/module] [flags]

NOTE: You can also add additional flags to the command if needed. There are also other output formats available other than markdown, such as JSON, XML etc.

Here I have a terraform module I have written on my local development machine under the folder path 'C:\temp\sonarcube-aci':

After running the following command:

terraform-docs markdown table "C:\temp\sonarcube-aci" --output-file "README.md"

We can now see a README.md file has been created:

Take a look here to see what the README.md document looks like: example_README.md

You can also create a configuration yaml file with additional options and have consistent execution through the '.terraform-docs.yml' file.

Once you've set up a configuration file, every time you or your teammates want to regenerate documentation (manually, through a pre-commit hook, or as part of a CI pipeline) all you need to do is run 'terraform-docs /module/path'.

Automated Usage using GitHub Actions

The examples in this section can also be found on my GitHub repository: Azure-Terraform-Deployments.

So far we have looked at how to use the tool locally. In this section we will look at how our documentation can be automated through CI/CD using the tool as a GitHub Action inside of a workflow.

In my GitHub repository called: Azure-Terraform-Deployments, notice that I have structured my terraform module code with folders using a numbering system e.g: '01_Foundation', '02_Storage', etc.

In each terraform module folder there is no documentation or 'README.md' file:

Create GitHub Actions workflow

Under the '.github/workflows' folder I created the following GitHub workflow: Auto_Generate_Module_Documentation.yml:

name: Generate terraform docs
on:
  workflow_dispatch:
  pull_request:
    branches:
      - master

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3.6.0
        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:
          find-dir: .
          output-file: README.md
          output-method: inject
          git-push: 'true'

Notice in the above workflow the GitHub Action under 'steps:' for terraform-docs:

- name: Render terraform docs inside the README.md and push changes back to PR branch
    uses: terraform-docs/gh-actions@v1.0.0
    with:
        find-dir: .
        output-file: README.md
        output-method: inject
        git-push: "true"

The parameters passed into the GitHub Action is done using 'with:'. You can look at all the available input parameters on the official terraform-docs GitHub Actions page.

I am using a parameter called 'find-dir' and pointing it to the root of my repository using dot: '.'. The 'find-dir' parameter is a setting that will extract a list of directories by running 'find ./find\_dir -name \*.tf' to automatically find the directories containing my module '.tf' files, so I do not have to specify each directory.

You can also specify a comma separated list of directories to generate docs for each directory manually by using the 'working-dir' parameter instead.

You should now see the GitHub Action under the repository Actions pane and be able to run the workflow manually as we specified the 'workflow_dispatch:' trigger:

After running the workflow you will now notice that each of my module folders have a 'README.md' file:

You can take a look at the README.md file that was created here: README.md.

Conclusion

As you can see, this tool can be a valuable asset to easily maintain and have terraform documentation for your modules without much effort.

I hope you have enjoyed this post and have learned something new. You can also find the code samples used in this blog post on my published GitHub page. ❤️

Author

Like, share, follow me on: 🐙 GitHub | 🐧 X/Twitter | 👾 LinkedIn

Marcel.LFollow

Dual Microsoft MVP DevOps + Azure | DevOps Architect | Technical speaker focused on Microsoft technologies, IaC and automation in Azure. Find me on GitHub: https://github.com/Pwd9000-ML