TP 35 : Documentation automatique avec terraform-docs

TP 35 : Documentation automatique avec terraform-docs

Objectifs

À l’issue de ce TP, vous serez capable de :

• générer automatiquement la documentation d’un module avec terraform-docs ;
• injecter cette documentation entre des marqueurs dans un README existant ;
• configurer la génération via un fichier .terraform-docs.yml ;
• automatiser la mise à jour en pre-commit et en CI.

Prérequis

• terraform-docs >= 0.19 installé (terraform-docs --version).
• Un module Terraform (celui du TP 31 convient parfaitement).

Contexte

Les modules d’InfraBank ont des README qui divergent du code : une variable ajoutée, jamais documentée. terraform-docs génère la documentation directement à partir du code, ce qui supprime cette dérive.

Étape 1 : Un module bien décrit

La qualité de la doc générée dépend des description. Assurez-vous que variables et outputs en ont une.

variables.tf

variable "name" {
  type        = string
  description = "Nom logique du bucket (préfixe)."
}

variable "versioning_enabled" {
  type        = string
  description = "Active le versioning du bucket."
  default     = true
}

variable "tags" {
  type        = map(string)
  description = "Tags additionnels appliqués au bucket."
  default     = {}
}

outputs.tf

output "bucket_id" {
  description = "Identifiant du bucket."
  value       = aws_s3_bucket.this.id
}

output "bucket_arn" {
  description = "ARN du bucket."
  value       = aws_s3_bucket.this.arn
}

Étape 2 : Générer un aperçu

cd terraform-aws-secure-bucket
terraform-docs markdown table .

terraform-docs affiche des tableaux Markdown : Providers, Inputs (avec type, description, défaut, obligatoire), Outputs, Resources. Rien n’est encore écrit dans un fichier.

Étape 3 : Injecter dans le README entre marqueurs

Le mode « injection » met à jour uniquement la zone délimitée par des marqueurs, en préservant le reste du README (introduction, exemples, licence).

Ajoutez ces marqueurs dans README.md :

# terraform-aws-secure-bucket

Module de bucket S3 chiffré, versionné et non public.

## Utilisation

Voir `examples/complet`.

<!-- BEGIN_TF_DOCS -->
<!-- END_TF_DOCS -->

## Licence

MIT

Puis générez avec injection :

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

terraform-docs remplace le contenu entre les marqueurs et laisse le reste intact.

sed -n '/BEGIN_TF_DOCS/,/END_TF_DOCS/p' README.md | head -n 20

Étape 4 : Piloter par fichier de configuration

Pour éviter de retaper les options, créez un .terraform-docs.yml à la racine du module :

.terraform-docs.yml

formatter: "markdown table"

output:
  file: "README.md"
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->

sort:
  enabled: true
  by: required

settings:
  anchor: false
  default: true
  description: true
  required: true
  type: true

La commande se réduit alors à :

terraform-docs .

terraform-docs lit .terraform-docs.yml, applique le formatteur markdown table, injecte dans README.md et trie les entrées avec les obligatoires en premier.

Étape 5 : Automatiser en pre-commit

Empêchez tout commit avec une doc obsolète grâce à un hook pre-commit.

.pre-commit-config.yaml

repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: "v0.19.0"
    hooks:
      - id: terraform-docs-go
        args: ["."]

pre-commit install
pre-commit run terraform-docs-go --all-files

Étape 6 : Vérifier en CI que la doc est à jour

En pipeline, régénérez la doc et échouez si le README a changé (preuve qu’un développeur a oublié de la mettre à jour) :

      - name: Vérifier la doc du module
        run: |
          terraform-docs .
          git diff --exit-code README.md

git diff --exit-code renvoie un code non nul si le fichier a été modifié par la génération : la CI échoue tant que le README committé ne reflète pas le code.

Vérification

• Le README contient un tableau d’Inputs/Outputs cohérent avec le code.
• Une variable ajoutée sans mise à jour de la doc fait échouer le hook / la CI.
• Le contenu hors marqueurs est préservé après chaque génération.

Nettoyage

Rien à détruire : le TP ne crée pas d’infrastructure.