Документирование Terraform: terraform-docs — туториал

Что такое `terraform-docs`

Это CLI-инструмент, который читает .tf-файлы и собирает:

• входные переменные (inputs)
• выходные значения (outputs)
• требования к провайдерам и версиям Terraform
• используемые модули и ресурсы

Итог — актуальная документация без ручной рутины ✅

Зачем использовать

• README всегда синхронизирован с кодом
• проще передавать модуль другим разработчикам
• удобно для open-source и внутренних registry
• меньше ошибок при использовании переменных

Установка

Через brew:

brew install terraform-docs

Через go:

go install github.com/terraform-docs/terraform-docs@latest

Проверка:

terraform-docs --version

Базовый запуск

Перейдите в папку модуля и выполните:

terraform-docs markdown table .

Команда сгенерирует Markdown-таблицы по модулю. Это удобно для вставки в README.

Пример вывода

Обычно появятся разделы:

• Requirements
• Providers
• Inputs
• Outputs

Например, для переменной:

variable "region" {
  description = "AWS region"
  type        = string
  default     = "eu-central-1"
}

terraform-docs добавит её в таблицу Inputs с типом, описанием и значением по умолчанию.

Автообновление README

Самый практичный сценарий — вставка документации прямо в README.md.

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

В README.md нужно оставить маркеры:

Инструмент автоматически обновит содержимое между ними. Это лучший способ держать документацию живой 🔄

Конфиг через `.terraform-docs.yml`

formatter: markdown table
output:
  file: README.md
  mode: inject

После этого достаточно:

terraform-docs .

Интеграция в CI/CD

Полезно запускать terraform-docs в pipeline или через pre-commit. Тогда в репозиторий не попадут изменения Terraform без обновлённой документации 🛠️

Лучшие практики

• всегда заполняйте description у variable и output
• используйте inject, а не ручную вставку
• добавьте проверку в CI
• документируйте каждый переиспользуемый модуль

Итог

terraform-docs — простой, но очень полезный инструмент для Terraform. Он снижает хаос в README, экономит время команды и делает модули понятнее для всех, кто будет с ними работать 🚀

Посмотрите также подборку каналов про IT — там много полезного по Terraform, DevOps, IaC и автоматизации.

🗣 Подборки каналов
🧠 Каталог ботов и приложений
🗺 Навигация