🎓 Comprendre

Cette rubrique explique comment marchent les grands choix techniques du projet, de façon accessible et révisable. Elle est faite pour qu'on puisse y revenir calmement, sans avoir à relire tout le code.

Comprendre vs ADR : la différence

	But	Format
ADR (docs/adr/)	Justifier pourquoi une décision a été prise	Court, figé dans le temps
Comprendre (cette rubrique)	Expliquer comment ça marche	Pédagogique, vivant, illustré

Les deux se renvoient l'un à l'autre : un guide pointe vers l'ADR qui justifie le choix, un ADR peut renvoyer au guide qui l'explique.

Guides disponibles

• Architecture de bout en bout : la vue d'ensemble, en deux récits (livraison CI/CD + GitOps, et trafic DNS → Gateway → pod), le pourquoi de chaque brique, et le cahier des charges pour refaire le schéma.
• Observabilité : GitOps, métriques et logs : comment la stack d'observabilité est installée (ArgoCD) et comment ses composants se parlent (Prometheus, Grafana, Loki, Alloy).
• Comprendre ArgoCD : l'objet Application, app-of-apps, sync/prune/ selfHeal, sync-waves, multi-source, le découplage avec le pipeline CI, et les pièges courants.
• La démarche d'exposition (Grafana public) : exposer un service en sécurité (Gateway API, cert wildcard DNS-01, ExternalDNS, ESO), routage cross-namespace, et l'approche « sécurité d'abord » en 2 MRs.
• Alerting : de la métrique au message Slack : comment une alerte se déclenche (cycle de vie, for:), ce que fait Alertmanager (groupe, route, inhibe), et le piège up == 0 vs absent().
• Durcissement du runner GitLab : pourquoi et comment le runner self-hosted est durci en défense en profondeur (SSH/pare-feu, isolation de l'executor Docker, cloisonnement réseau des jobs), avec le runbook de restauration.
• Comprendre Cilium (migration depuis le VPC CNI) : pourquoi on quitte le VPC CNI, le datapath overlay et eBPF, le remplacement de kube-proxy, Hubble, et le piège d'ordre de boot (composant vpc-cni vs addon managé) résolu par l'amorce Ansible.
• Valider hors infra (avant de pusher) : par type d'artefact (Terraform, Ansible, Helm, Kustomize, K8s, CI), la commande de validation statique alignée sur la CI, le pourquoi et les pièges (tfsec sale, versions pinnées, rendu vs runtime).
• Vuln management (VEX et risk acceptance) : comment gérer une CVE qu'on ne peut pas patcher tout de suite, en distinguant l'inexploitable prouvé (VEX not_affected) du risque atteignable mais accepté (risk acceptance datée).
• Capacité et ressources (requests, limits, QoS) : comment Kubernetes gère mémoire et CPU (scheduler/requests vs kubelet/limits), les classes de QoS, pourquoi un nœud sur-engagé casse au premier pic (INC-060), et le garde-fou mesure + LimitRange + ResourceQuota.

• Tracing distribué (Tempo + OpenTelemetry) : comment marche Tempo (entrepôt de traces indexé par trace ID), la chaîne FastAPI → Collector → Tempo, l'auto-instrumentation HTTP + SQL, la corrélation des 3 piliers, et l'incident mémoire du ballast Go décortiqué (GC vs limite cgroup).

• Exposition involontaire (un env public tout seul) : comment trois briques qui font correctement leur travail (Gateway permissif, HTTPRoute sans sectionName, ExternalDNS obéissant) publient sur internet un environnement que personne n'a décidé d'exposer, pourquoi un certificat invalide n'est pas un contrôle d'accès, et la leçon de fond : un garde-fou documentaire n'est pas un contrôle.

• Rétention ECR (l'image que prod ne trouve plus) : pourquoi le registre a supprimé deux fois l'image servie par la production, ce que le pipeline fabrique exactement (une seule image, deux étiquettes), pourquoi élargir la fenêtre ne fait que déplacer la date, et la correction par fenêtre de rétention séparée.

• Le 503 sous charge (un symptôme, deux mécanismes) : la spirale de readiness sous throttling CPU (flag UH, corrigée) et la course de fermeture entre le keep-alive d'uvicorn et le pool d'Envoy (flag UC, ouverte), comment le response_flags du log Envoy les sépare, et pourquoi ces logs se lisent dans Loki et non par kubectl logs.

• Périmètre du pipeline (contexte de build et filtrage) : pourquoi corriger une phrase de documentation déclenchait 17 jobs et faisait avancer dev, pourquoi il fallait déplacer le backend sous backend/ avant de pouvoir filtrer, pourquoi les huit jobs de la chaîne image partagent un seul déclencheur, et le piège du pipeline vide qui est failed et non skipped.

Écrire une page « Comprendre »

Quand une page se justifie

Tous les sujets n'en méritent pas une. Deux critères, l'un ou l'autre suffit :

• le sujet a produit deux incidents — il ne s'agit plus d'un accident ;
• une décision a été prise contre l'intuition, et le raisonnement se perdra si personne ne l'écrit.

Sinon, un ADR (la décision) ou une entrée d'incident (le fait) suffit. Sans ce filtre, la rubrique gonfle et cesse d'être un repère.

Le gabarit

L'ordre compte autant que le contenu : il place le résultat avant le raisonnement.

Section	Rôle
En trois phrases	Le résultat d'abord. Ce qui s'est passé, ce qui est corrigé, ce qui reste. Une personne pressée s'arrête ici.
Les mots du sujet	Chaque sigle et terme métier défini avant son premier usage, en tableau. Jamais de périphrase à la place du terme : ce sont les mots qu'on entendra ailleurs.
Le mécanisme	Comment ça marche quand tout va bien, avec un schéma. C'est la partie qui permet de comprendre la panne ensuite.
Ce qui s'est passé	La chronologie datée, incidents et correctifs mêlés. Un tableau suffit.
La correction	Ce qui change, et surtout pourquoi cette solution plutôt qu'une autre. Les alternatives écartées valent autant que celle retenue.
Ce que ça ne fait pas	Les limites, ce qui reste ouvert, ce qui attend une validation.
Ce qu'il faut retenir	Deux à quatre phrases transposables à d'autres sujets.

Les règles de forme

• [TOC] juste après l'introduction dès qu'une page dépasse l'écran. Le sommaire s'affiche en carte, sur deux colonnes.
• Paragraphes courts, trois lignes au plus. Au-delà, couper ou passer en liste.
• Les encarts sont typés : !!! warning pour un piège, !!! note pour un aparté, !!! success pour un état vérifié.
• Chiffres, chemins et commandes exacts, jamais reformulés. Un chiffre arrondi ne se vérifie plus.
• Les schémas montrent le mécanisme, pas son nom. Mermaid rend bien un flux ; pour une file qui déborde ou une saturation, un SVG écrit à la main dit ce qu'un diagramme générique ne sait pas dire. L'extension md_in_html le permet, et les classes yk-svg-* de docs/stylesheets/extra.css lui donnent des couleurs qui tiennent dans les deux thèmes.

Ne jamais dupliquer

Une page renvoie à l'ADR et à l'incident, elle ne les recopie pas. Deux copies d'un même fait divergent, et c'est arrivé ici : promotion-multi-env.md a affirmé pendant quatre jours une chose que le dépôt avait cessé de faire.

À venir

Au fil des sessions, un fichier par grand sujet (Helm et values, sécurité et RBAC, réseau et NetworkPolicy, Terraform persistent/ephemeral...).