Today, I'm furthering my war on DevOps busy work. This is a continuation of a previous post: For DevOps Professionals: Analyzing and Eliminating Busy Work. For this post, I want to remove the tediousness of properly documenting Terraform code.
Terraform code documentation should detail the following to make it easy for other developers to consume and maintain a Terraform configuration or project. The bottom line is high quality and accurate documentation for Terraform code makes change easier and saves people time. The relevant quote from my previous post is:
Automatically generate Terraform documentation. Like many, we use the open source product Terraform-docs to generate Terraform documentation. We seem to be executing that generation locally. When pull requests are created or updated, a GitHub Workflow that automatically executes the documentation generation and pushes any changes would eliminate the manual step.
Terraform code documentation should have the following components. Without this information, anyone consuming or changing the project would be forced to audit the code line by line. Here's an example from one of my Terraform modules.
- A concise description of what the Terraform project supports
- For reusable modules, a usage example
- Details about all inputs, including any defaults
- Details for all outputs
- Identification of all Terraform resources maintained
- A listing of any modules used by the Terraform project
- Provider requirements, including versions
Keeping these documentation items current is tedious and boring. Consequently, it usually becomes out of date quickly. Fortunately, the open-source product Terraform Docs can generate this information. My team uses this product religiously.
We go further and have Terraform documentation updated automatically for every pull request update. As we're largely using GitHub, our Terraform projects update documentation automatically when our developers create or update a pull request. We've encapsulated the regeneration logic into GitHub action terraform-docs, making it easy to reuse for all Terraform projects in all our repositories. This concept is usable for most CI/CD toolsets.
Using the terraform-docs action is relatively straightforward. That said, I might take the step of creating a reusable GitHub workflow to further streamline usage. Here's an example of workflow usage.
If you use it directly, we recommend explicitly referencing a release tag. That way, you're not accidentally impacted by changes to the action going forward.
I'm always interested in your views on the topic. Especially if you've discovered additional ways to make documenting Terraform code higher quality and easier to maintain.
