🎓 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).

À venir

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