Autogenerate Documentation with terraform-docs and GitHub Actions

Using terraform-docs to limit my exposure to Markdown while also providing updated documentation when I do code commits?!?!

Screenshots to Markdown

At some point pretty early in my IT career, I started taking screenshots of the work I was doing. Initially, I did this to reinforce in my own mind, the steps required to configure some application or troubleshooting some issue. Once I started taking screenshots, I screenshot everything!!! Eventually, I started including these screenshots within the documentation I provided to customers at the completion of their projects. I thought this was a nice touch and honestly, each time a document was delivered, I kept hoping, once they see the documentation includes their own screenshots, for a “kid opening the most amazing Christmas gift ever” type of reaction. Reactions varied, from sincere thanks to yawning, but I still believe that most customers appreciated the fact that the screenshots where their own.

Adam can correct me if I’m wrong (he was there), but I earned a…I’ll say reputation, for creating really good documentation. Some may have even believed that I “loved” creating documentation but let me assure you, that was never, ever the case…it was simply a unavoidable task that I tried to complete with the best of my ability because our customers deserved to know as many details as possible about the system and/or service we provided.

Though I still have the desire to create useful documentation, the nature of some projects diminishes the value of screenshots. For instance, I recently finished a multi-month project developing Terraform modules intended for end-user consumption. I spent months creating .tf files….and though I could capture screenshots with VS Code, what would be the point? In this instance, the documentation requirement involved the creation of a Readme file for each module. Do I need to become a Markdown expert or is there an easier way to accomplish this?

terraform-docs

In the world of Infrastructure as Code (IaC), tools like Terraform make it easier to manage and provision infrastructure resources. Terraform Docs is a utility designed to automate the generation of documentation for Terraform modules. It reads your Terraform files and produces formatted documentation in various output formats, such as Markdown. By automatically generating documentation, Terraform-docs ensures consistency, reduces manual effort, and enhances the overall clarity and accessibility of module details for both developers and users.

I’m sure everyone will agree that keeping your Terraform code well-documented is essential, and one way to ensure that your documentation is always current, is to use Terraform Docs in conjunction with GitHub Actions.

Using GitHub Actions

One could run terraform-docs manually to build documentation, but I believe you’ll find GitHub Actions a powerful tool that allows you to automate workflows in response to events within your repository. While it may be a stretch to think of GitHub Actions as “Lambda functions for GitHub repositories,” this analogy helped me to understand their purpose. By leveraging GitHub Actions, you can seamlessly execute a terraform-docs workflow to update your ReadMe file whenever code is committed to the repository. This automation streamlines the documentation process, ensuring that documentation stays in sync with the evolving code.

Basic Implementation Steps

1. Create a .github/workflows directory in your repository….OR in GitHub, select your repository, and then click Actions.
2. Create the GitHub Actions workflow file
   • In this step, you’ll create a YAML file to define the workflow. To get started, you can find a sample YAML file on the terraform-docs site or you can use the templates found on GitHub.
3. Commit the changes to your repository and push them to GitHub.
   • The GitHub Actions workflow will be triggered automatically.
4. View the results

GitHub Actions Virtual Environments and terraform-docs

GitHub Actions workflows run in virtual environments. These environments are based on specific runners that GitHub provides, and they are isolated and customizable based on the job’s operating system and version. GitHub Actions supports several virtual environments allowing you to choose the OS and version that works best for your workflow requirements. Commonly used virtual environments are ubuntu-latest, windows-latest, and macos-latest.

In the case of the screenshot below (screenshots can still be useful), the workflow is configured to use ubuntu-latest as its virtual environment.

Installing/Running terraform-docs

As you may expect, to build your documentation file, you must install and run terraform-docs. You have two (2) choices that I am aware of:

1. You can install and run terraform-docs from a host machine (say your laptop/admin machine)
2. You can install and run terraform-docs form within the virtual environment

To run an instance of terraform-docs that is installed on your local machine, you will need to add code similar to the following within the “steps” section:

    - name: Trigger Local Update
      run: ./update-terraform-docs-locally.sh

Personally, I decided to install and run terraform-docs in the virtual environment because….why not? If you wish to use the virtual environment to run terraform-docs, you will need to add steps to download and configure it within your Workflow file.

Where’s my Documentation?

I was elated the first time my workflow completed successfully….I had made a triumphant entrance into the world of automated Terraform documentation, thus minimizing, or perhaps eliminating, the time I’d spend manually editing README.md files! I had expected to see the documentation eagerly awaiting my review within the repository but alas, it was nowhere to be found….how could this be?!?!?

If that happens to you, verify that git-push is set to “true” and ensure that you have permissions to push the documentation to the repository.

In the sample code below, terraform-docs is downloaded and configured on the ubuntu-latest virtual environment and a GitHub personal access token (PAT) is used for authentication to push the readme to the repository.

name: Generate terraform docs
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Install terraform-docs
      run: |
        curl -sSLo ./terraform-docs.tar.gz https://terraform-docs.io/dl/v0.17.0/terraform-docs-v0.17.0-linux-amd64.tar.gz
        tar -xzf terraform-docs.tar.gz
        chmod +x terraform-docs
        sudo mv terraform-docs /usr/local/bin/
    - 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: inject
        git-push: 'true'
        git-commit-message: 'Update README.md with terraform docs'
        github-token: ${{ secrets.GITHUB_TOKEN }}

Summary

Useful documentation for modern projects, like the development of Terraform modules, requires more than screenshots and continuous manual modification. The integration of terraform-docs with GitHub Actions provides a method to efficiently automate the creation and ongoing maintenance of informative README files within your code repositories. Leveraging GitHub Actions’ event-driven workflows allow you to seamlessly update your documentation whenever code changes are committed, ensuring documentation is always current, accurate, and consistent with the ever-changing codebase.

We’d love to hear how you’re using terraform-docs or GitHub Actions! Feel free to get in touch with us via the Contact page or leave a comment below.