Generate documentation for Terraform code with terraform-docs

October 07, 2023

Generate documentation for Terraform code with terraform-docs

Source code terraform-docs example for the article contains :

Terraform code to create S3 bucket
Github workflow for terraform docs
Pre-commit hook configuration
README.md has example of the terraform-docs autogenerated docs

terraform-docs documentation

terraform-docs Documentation & Quickstart

Github repo of terraform-docs :

https://github.com/terraform-docs/terraform-docs

terraform-docs website :

https://terraform-docs.io/

terraform-docs demo

Check out an interesting stream of Anton Babenko & Khosrow Moossavi on terraform-docs :

terraform-docs youtube

Install terraform-docs Mac Os

brew install terraform-docs

Install terraform-docs Windows via chocolatey package manager

choco install terraform-docs

How to autogenerate documentation based on your variables, outputs and providers information

terraform-docs markdown ./

This will only output the documentation, so we need to save it into a Markdown file README.MD

terraform-docs markdown ./ --output-file README.md --output-mode inject

This will add the markdown, without overwriting README.MD file There are two modes "--output-mode inject" and "--output-mode replace"

Reference repo for this blog article terraform-docs example

git clone https://github.com/cloudtipss/terraform-docs-example

terraform-docs markdown ./ --output-file README.md --output-mode inject


README.md updated successfully

Terraform-docs pre-commit

Install the pre-commit pre-commit project on MacOS

brew install pre-commit

Verify :

pre-commit --version

Generate config file for pre-commit

It declares which "hooks" , which are some checks/validations to run before you commit from your local

pre-commit sample-config > .pre-commit-config.yaml

Add this to pre-commit terraform-docs configuration file

repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.83.4
    hooks:
      - id: terraform_fmt
      - id: terraform_validate
      - id: terraform_docs
        args:
          - '--args=--lockfile=false'

You can read about this pre-commit hook bundle here : https://github.com/antonbabenko/pre-commit-terraform

Install the hooks we gonna run prior to commit

pre-commit install

Example output :

pre-commit installed at .git/hooks/pre-commit

Perform a quickly test if pre-commit works
Check our code against all hooks (faster than trying commit)

pre-commit run --all-files

Output : 
Terraform fmt............................................................Passed
Terraform validate.......................................................Passed
Terraform docs...........................................................Passed

Lets test it with git commit :



Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   main.tf
        modified:   variables.tf

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        .pre-commit-config.yaml

no changes added to commit (use "git add" and/or "git commit -a")
(base) terraform-docs-example % git add .
(base) terraform-docs-example % git commit -m "Adding Pre-commit to the code base for the article"
Terraform fmt............................................................Passed
Terraform validate.......................................................Passed
Terraform docs...........................................................Passed
[develop 6b87a3c] Adding Pre-commit to the code base for the article
 3 files changed, 19 insertions(+), 8 deletions(-)
 create mode 100644 .pre-commit-config.yaml

Terraform-docs github workflow / action

Under .github/workflows/terraform-docs.yml, you will find a Github action file for terraform-docs

In order to trigger the Action/Workflow, you will need to create some small change. For example :

change some text of README.md
create a new branch

git add .
git commit -m "New change"
git checkout -b "develop"
git push --set-upstream origin develop

Go to your Github repository , Create Pull Request from develop to main ("main" <- "develop" )

NOTE :

There is high chance of possibility, that your first PR to the repo, will result in 403 Default Github Actions/Workflows configuration, prohibits PRs from a bot/default pipeline user So, you need to adjust some permission to resolve 403 error

::debug Following files will be committed
M  README.md
[develop f425976] terraform-docs: automated action
 1 file changed, 1 insertion(+)
remote: Permission to cloudtipss/terraform-docs-example.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/cloudtipss/terraform-docs-example/': The requested URL returned error: 403

Two possible solutions for Permission denied to github-actions[bot] 403 :

Github Repo -> Settings -> Action -> General -> Workflow permissions -> choose read and write permissions

Add workflow permissions declaratively :

permissions:
  pull-requests: write
  contents: write
  repository-projects: write