Atlas d'infrastructure — documentation auto-générée
Contexte
Une grappe domestique grandit par accrétion : un service ajouté ici, un capteur ajouté là, une dépendance entre containers ajoutée plus tard. Au bout de quelques mois, il devient impossible de redessiner mentalement ce qui parle à quoi, ce qui dépend de quoi, ce qui est encore vivant. Et la documentation manuelle, on la commence puis on l'oublie.
Contrainte
Trois exigences :
- Ne jamais avoir à tenir la doc à la main. Une doc qui dépend de la discipline humaine se périme en quelques semaines.
- Ne jamais publier de secret. Les
.env, les chemins absolus, les tokens — strippés à la sortie, pas scannés à l'entrée. - Pouvoir lire la doc au format texte (Markdown, terminal) autant qu'au format graphe.
Décision
Un scanner cron déployé sur chaque nœud (Pi4 et Pi5). Il lit
les docker-compose.yml trouvés sous une racine
convenue, agrège services / images / réseaux / volumes /
healthchecks, et pousse un HostName.json vers le
nœud central.
Sur le nœud central, un consolidateur fusionne les fichiers, détecte les références croisées (un service Pi4 qui parle à un service Pi5), et un renderer produit trois sorties à partir de la même donnée :
- Un Markdown long avec une section par nœud, par stack, par service.
- Un HTML compact pour lecture rapide.
- Un diagramme Mermaid
(
flowchart TB) qui visualise toute la grappe en une page.
Cron à 5 h du matin. Le rapport est prêt au réveil.
Mesure
Première exécution : 38 healthchecks détectés, 36 OK. Les deux qui clignotaient ont été corrigés dans la foulée — ils étaient invisibles à l'œil nu jusque-là. Depuis, la doc est toujours à jour, par construction.
Ce qu'il en reste
La doc cesse d'être un chantier permanent. Quand une question
se pose (« est-ce que music-intel tourne encore
sur Pi4 ? »), la réponse est dans le rapport du matin. Et la
page que vous lisez sur l'infrastructure
est tirée de ces mêmes exports — la doc publique et la doc
interne ne divergent plus.