En el mundo del desarrollo, la documentación es clave para mantener proyectos organizados y comprensibles. Si bien muchos están familiarizados con la creación de archivos README.md usando markdown, hoy exploraremos un paso adicional: cómo automatizar la documentación de desarrollos en Terraform utilizando terraform-docs. Este artículo te guiará a través del proceso, explicando qué es terraform-docs, cómo funciona y cómo puedes aprovecharlo para estandarizar la documentación de tus proyectos de manera eficiente.
¿Qué es Terraform-docs?
Terraform-docs es una herramienta de línea de comandos que permite generar documentación automáticamente para módulos de Terraform en varios formatos. Este recurso es especialmente útil para asegurar que la documentación esté siempre actualizada y sea coherente, facilitando el mantenimiento y la colaboración en proyectos.
¿Cómo Funciona?
La herramienta terraform-docs analiza los archivos de código de tu proyecto, como los recursos, variables, outputs y proveedores, y genera un archivo de salida con la documentación organizada según el tipo de objeto de Terraform. Por ejemplo, puede crear una sección que agrupe todas las variables, mostrando sus descripciones, valores por defecto, y más. De esta forma, la documentación reflejará fielmente la estructura y componentes de tu código Terraform.
Pasos para Generar Documentación
Para comenzar a usar terraform-docs, lo primero que necesitas es instalarlo. La instalación varía según la plataforma que utilices, pero para usuarios de Windows, una forma sencilla de hacerlo es a través de un gestor de paquetes como Chocolatey:
C:\> choco install terraform-docs
Una vez instalado, puedes verificar la instalación ejecutando terraform-docs en la línea de comandos, o verificar la versión instalada con el comando terraform-docs -v.
Para MacOS
brew install terraform-docs
Crear Documentación desde la Línea de Comandos
Para documentar un desarrollo en Terraform, puedes ejecutar el siguiente comando desde la carpeta donde se encuentra tu código:
terraform-docs markdown table --output-file README.md
Este comando genera un archivo README.md que incluye la documentación de todas las variables, outputs, y otros componentes de Terraform que hayas definido en tus archivos.
Uso de un Archivo de Configuración
Si deseas tener más control sobre la estructura de la documentación, puedes crear un archivo de configuración YAML, llamado .terraform-docs.yml, en la raíz de tu proyecto. Este archivo te permite definir la estructura de las secciones, su orden, y omitir aquellas que no desees incluir.
Un ejemplo básico de configuración podría verse así:
version: 0.12
output:
file: "README.md"
mode: inject
content:
- header: "tfdocs/header.md"
- footer: "tfdocs/footer.md"
- sections:
- "Inputs"
- "Outputs"
En este archivo, hemos definido un encabezado y pie de página personalizados, así como la inclusión de las secciones «Inputs» y «Outputs». Una vez configurado, puedes generar la documentación ejecutando:
terraform-docs -c .terraform-docs.yml
Automatización con Git Hooks
Para mantener la documentación actualizada automáticamente, puedes crear un hook de Git que ejecute terraform-docs cada vez que realices un commit. Esto se logra editando el archivo .pre-commit-config.yaml e incluyendo el repositorio fuente de terraform-docs junto con los argumentos deseados.
De esta manera, cada vez que hagas un commit, tu archivo README.md se actualizará automáticamente, asegurando que la documentación siempre refleje los cambios más recientes en tu código.
Conclusión
Terraform-docs es una herramienta poderosa que puede simplificar y mejorar significativamente la documentación de tus proyectos en Terraform. Al automatizar la generación de archivos README.md, no solo ahorras tiempo, sino que también garantizas una mayor coherencia y calidad en la documentación.
Más info y ejemplos: Terraform-docs
