Terraform-docs: generate docs for Terraform
This can build documentation for our Terraform project in seconds.
Once we developed Terraform projects, built and enabled modules in our infrastructure, we should have some place to describe our works and let people understand what we made and our team can comprehend so easily in a glance. This will benefit us for better maintenance and monitoring in long term.
terraform-docs
terraform-docs is a tool to generate documentation from our Terraform project in various formats. It can extract modules, resources, providers, and much more to a single file where we can read and understand it.
This is the homepage of terraform-docs.
There are many ways of installation described in the link above. I prefer using homebrew or winget.
Example usage
It’s so simple to use terraform-docs by supply format we would like or a configuration file and the path of Terraform directory.
1
2
3
4
5
# specify format
terraform-docs [format] [flags] [path]
# specify config file
terraform-docs -c [config file] [path]
Formats
There are plenty of formats we can generate with this tool. Markdown, AsciiDoc, JSON, YAML, or just pretty printing to console are available.
To me as one who like to write in Markdown, I usually do it in that format especially in table style.
This will generate in the table style displaying information in columns that is easy to read.
1 2 3 4 5
# syntax terraform-docs markdown table <terraform directory> # example terraform-docs markdown table .
and the example result:
This document style displays information in sections, in top-down direction, so we can read in relaxing eye movement.
1 2 3 4 5
# syntax terraform-docs markdown document <terraform directory> # example terraform-docs markdown document .
and the example result:
Insert to README file
We can insert the doc into the README file by 2 steps.
add this comment block into the file. This block marks the place
terraform-docscan insert the generated doc into.1 2
<!-- BEGIN_TF_DOCS --> <!-- END_TF_DOCS -->
run the command to
injectthe generated doc into the file.1 2 3 4 5 6 7
# syntax terraform-docs markdown [table|document] <terraform directory> \ --output-file <output filepath> \ --output-mode inject # example terraform-docs markdown table . --output-file README.md --output-mode inject
Then we can see the example like this.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# README
lorem ipsum
<!-- BEGIN_TF_DOCS -->
## Requirements
| Name | Version |
|------|---------|
| <a name="requirement_google"></a> [google](#requirement\_google) | ~> 3.5 |
...
<!-- END_TF_DOCS -->
Another output mode is --output-mode replace which will replace all the file content with the generated doc.
Configuration file
There are lots of customization that we can pack them all in one single configuration file named .terraform-docs.yml like this example.
1
2
3
4
formatter: "markdown table"
output:
file: "./README.md"
mode: inject
This example means we want “markdown table” style and “inject” it into the file ./README.md. Similar to the command above.
For more details and configurations, please visit the site below.
Then apply it with terraform-docs by this command.
1
2
3
4
5
# syntax
terraform-docs -c .terraform-docs.yml <terraform directory>
# example
terraform-docs -c .terraform-docs.yml .
Add into pre-commit
As I shared about pre-commit blog before (here), we can include terraform-docs with the config file .terraform-docs.yml into our pre-commit hooks like this.
1
2
3
4
5
6
7
8
repos:
- repo: https://github.com/antonbabenko/pre-commit-terraform
rev: "v1.99.5"
hooks:
- id: terraform_docs
args:
- --args=--config=.terraform-docs.yml
We are using the hook repo from antonbabenko/pre-commit-terraform.
Or visit my repo here.
Now we have documents in our hands to simply communicate with people what we have built in Terraform projects in a simple way.