Terraform Docs: Como Gerar Documentação Automática no Terraform

Olá pessoal!

Tudo bem com vocês?

Hoje no blog da 4Linux, vamos falar sobre uma ferramenta incrível para documentar sua infraestrutura como código: o Terraform Docs (terraform-docs).

Com ela, é possível gerar documentação automática, padronizada e sempre atualizada dos seus módulos Terraform — economizando tempo e evitando erros.

O que é o Terraform Docs?

Quando trabalhamos com Terraform, criamos infraestrutura como código (IaC) com clareza e intenção. Porém, essa clareza se perde quando falta documentação atualizada nos módulos.

O Terraform Docs é uma ferramenta de linha de comando simples e poderosa que gera documentação automaticamente a partir dos módulos Terraform. Ele suporta diversos formatos, como Markdown, JSON, AsciiDoc e YAML.

Com ele, você mantém um README.md sempre sincronizado com seu código — seja executando manualmente no terminal, integrando em um pipeline CI/CD ou usando hooks de pré-commit. Assim, variáveis, outputs, providers e dependências ficam sempre documentados sem edição manual.

Eu uso bastante o terraform-docs para documentar meus módulos Terraform e OpenTofu, e recomendo!

Instalando Docker

Vamos instalar o Docker rapidamente via script para executar o terraform-docs sem instalar nada diretamente no sistema.

curl -fsSL https://get.docker.com -o docker-install.sh && sh docker-install.sh

Para validar que o Docker está em execução:

$ docker version

Client: Docker Engine - Community
 Version:           28.3.2
 API version:       1.51
 Go version:        go1.24.5
 Git commit:        578ccf6
 Built:             Wed Jul  9 16:13:42 2025
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          28.3.2
  API version:      1.51 (minimum version 1.24)
  Go version:       go1.24.5
  Git commit:       e77ff99
  Built:            Wed Jul  9 16:13:42 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.7.27
  GitCommit:        05044ec0a9a75232cad458027ca83437aae3f4da
 runc:
  Version:          1.2.5
  GitCommit:        v1.2.5-0-g59923ef
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

Gerando documentação automática com Terraform Docs

Vamos demonstrar usando um repositório público com um projeto Terraform para Google Cloud Platform (GCP).

Clone o repositório:

git clone https://github.com/4linux/terraform-docs-4labs.git && cd terraform-docs-4labs.git

O terraform-docs permite gerar a documentação em vários formatos (JSON, YAML, Markdown). Aqui, vamos gerar em Markdown:

docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.20.0 markdown /terraform-docs > doc.md

O resultado será salvo no arquivo doc.md com todas as variáveis, outputs e dependências documentadas.
Resultado do output abaixo:

Resultado completo no repo https://github.com/4linux/terraform-docs-4labs/blob/main/doc.md

Bacana né pessoal? Curtiram?

Benefícios de usar o Terraform Docs

• Mantém a documentação sempre atualizada

• Padroniza a forma de documentar módulos Terraform

• Evita inconsistências entre código e README

• Integra facilmente em pipelines CI/CD

• Suporte a múltiplos formatos de saída

Conclusão

Manter a documentação da infraestrutura como código é tão importante quanto versioná-la e testá-la.

Com o Terraform Docs, conseguimos automatizar a criação de documentação limpa, legível e alinhada com os padrões do Terraform — sem esforço manual.

Neste post, vimos:

• Como instalar o Docker rapidamente

• Como rodar o terraform-docs em um único comando

• Como gerar documentação em Markdown para módulos Terraform

Se você ainda não documenta seus módulos, este é o momento de começar. Com o terraform-docs, esse processo se torna rápido, confiável e automatizável.

Então é isso galera! Nos veremos no proximo post. Compartilhe em suas redes sociais!

Tmj!

Referências

https://terraform-docs.io/user-guide/introduction

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