ADR 025 — Gouvernance des ressources : requests/limits mesurés, QoS, LimitRange et ResourceQuota (2026-06-24)

Statut

Accepté (2026-06-24). Right-sizing (Décision 1/2) + LimitRange au bootstrap (Décision 3) validés live from-scratch le 2026-06-25 (no BestEffort dans les 8 namespaces possédés). ResourceQuota livré au Sprint 6 (#136, 2026-07-26, un quota par namespace d'env — voir Décision 3). La validation a révélé que des requests honnêtes sur-souscrivent le nœud unique (requests mémoire à 99 %, prometheus non planifiable) → #114 (capacité) devient un prérequis dur ; #112 reste ouvert et sera clos avec #114 (voir « Validation live »). Issue #112, né de l'incident INC-060. Décision 2 complétée le 2026-08-12 (#164) : le HPA de fastapi scale sur CPU seul, la métrique mémoire étant un point fixe mathématique (voir « Corollaire (#164) »). Décision 2 appliquée le 2026-08-15 (#169, INC-066) : limits.cpu retirée du conteneur applicatif, la configuration contredisait la prescription et la panne annoncée s'est produite (voir « Corollaire (#169) »). ADR compagnon : ADR 026 (segmentation des node groups + Spot, #114) traite le volet « capacité matérielle » ; le présent ADR traite le volet « discipline des ressources ».

Contexte

L'incident INC-060 a coupé tout l'ingress (~10 min) sur le nœud unique t3.medium : un redéploiement de Grafana a déclenché un pic mémoire qui a fait basculer un nœud sur-engagé (limits.memory cumulées = 168 % de la capacité). Le déclencheur (préinstall des plugins Grafana) est traité à part. La cause racine est l'overcommit sans garde-fou : les pods se planifient sur des requests sous-évaluées, mais la pression au runtime vient des limits, et rien n'empêche leur somme de dépasser la capacité physique.

À l'approche de Tempo (#108, gourmand) et d'un 2e workload (frontend #109), continuer sans gouvernance rejouerait l'incident.

Décision 1 — Dimensionner sur la mesure, pas sur l'intuition

On relève la consommation réelle par pod (régime stable et pic) avec l'outillage déjà en place (Prometheus + kube-state-metrics + node-exporter) :

• Mémoire : container_memory_working_set_bytes (c'est la métrique qui déclenche l'OOMKill, pas le RSS).
• CPU : rate(container_cpu_usage_seconds_total[5m]).
• Aide à la recommandation : VPA en mode recommender (Off) ou Goldilocks (dashboard de reco par namespace), sans appliquer automatiquement.

Décision 2 — Régler mémoire et CPU différemment (compressible vs non)

• Mémoire (non compressible → dépassement = OOMKill) : request = working set en régime + marge ; limit couvre le pic mesuré (+ ~15-20 %). Sur les composants critiques, request = limit → classe QoS Guaranteed (les derniers évincés sous pression).
• CPU (compressible → dépassement = throttling, pas de kill) : request = usage p95 ; limit large ou absente sur le latency-sensitive (le throttling CPU fait souvent plus de mal qu'un léger dépassement). Arbitré selon ce que le check kube-linter exige en CI.

Corollaire (#164) — dimensionner sur la mémoire, mais ne pas scaler dessus

La distinction compressible / non compressible vaut pour les requests et limits. Elle ne dit rien du HPA, et l'assimilation des deux a coûté un défaut de configuration : le HPA de fastapi portait une métrique mémoire à 80 % en plus du CPU à 70 %. Mesuré le 2026-08-11, elle était inutile pour monter et nuisible pour descendre.

• Elle ne déclenche jamais de scale-up. Sous fortio -c 150, le CPU est monté à 334 % de sa cible pendant que la mémoire plafonnait à 74 %, sous le seuil. Tous les scale-up observés venaient du CPU.
• Elle interdit tout scale-down. Un pod consomme 89 Mi pour une request de 128 Mi, soit 69 % pour une cible de 80 %. Or desired = ceil(replicas × 69/80) = ceil(replicas × 0,8625) redonne replicas pour tout N : 2→2, 3→3, 4→4, 5→5. Chaque nombre de replicas se justifie lui-même, le HPA reste verrouillé sur le maximum atteint (prod à 5 replicas 25 min après la fin de la charge, CPU à 3 %). Pour redescendre de 4 à 3 il aurait fallu passer sous 60 % de mémoire, de 3 à 2 sous 53 % — inatteignable.

La raison de fond : les 89 Mi sont l'empreinte de base de l'application — interpréteur Python, FastAPI, SQLAlchemy, dépendances chargées à l'import. Elle est payée au démarrage et ne dépend pas du trafic (88-90 Mi au repos, ~95 Mi sous charge, soit ~7 % de variation contre un facteur 100 côté CPU). Une empreinte quasi constante ne peut pas piloter un autoscaler : elle produit un ratio permanent, donc un point fixe. Le HPA de fastapi scale donc sur CPU seul.

Ce n'est pas un argument contre le dimensionnement mémoire de la Décision 2, qui reste mesuré et nécessaire — c'est la borne de ce que cette mesure autorise à faire. Corollaire opérationnel : maxReplicas devenait un plancher de fait après le premier pic, ce qui vidait de leur sens les alignements de #149 et #158 et aurait rendu Karpenter (#163) plus coûteux, pas moins, en maintenant un nœud allumé.

⚠️ Baisser la request mémoire n'est pas la parade. À 96 Mi le ratio monterait à 93 %, au-dessus de la cible : le HPA scalerait alors en permanence. Symétrique du même piège, déjà relevé sur #158.

Corollaire (#169) — la limite CPU du latency-sensitive a produit la panne annoncée

La Décision 2 prescrit une limit CPU « large ou absente sur le latency-sensitive ». La configuration livrée portait pourtant limits.cpu: 500m, soit 5× la request, sur fastapi — le service le plus sensible à la latence du cluster. Mesuré le 2026-08-12 (INC-066), la défaillance décrite entre parenthèses par cette même Décision 2 s'est produite telle quelle.

Sous une charge jouée par le chemin de production (NLB → Envoy → pods), les pods collent au plafond : 496m et 491m pour 500m. Throttlés, ils ralentissent sur tout, y compris sur la readiness /healthz/ready, qui fait un SELECT 1. La sonde dépasse ses 3 s, trois échecs consécutifs suffisent, le pod sort de l'EndpointSlice — et Envoy, à court d'upstreams, sert des 503 aux clients. Le trafic du pod retiré se reporte sur les survivants, qui saturent à leur tour.

Le mécanisme censé protéger la disponibilité la dégrade : retirer du Service un pod parce qu'il est occupé prive le système de capacité au moment précis où il en manque. C'est le schéma déjà rencontré sur la liveness (#162), un cran plus bas — là on redémarrait un pod sain, ici on cesse de lui parler.

limits.cpu est donc retirée du conteneur applicatif, ce qui aligne la configuration sur la prescription plutôt que d'ajouter un réglage compensatoire. Deux vérifications faites avant, parce qu'une limite peut revenir par la bande : le ResourceQuota de chaque overlay ne borne que la mémoire (voir Décision 3), et le LimitRange default-limits du bootstrap n'a pas de default.cpu.

L'arbitrage kube-linter annoncé par la Décision 2 est tranché, par la mesure et non par l'hypothèse : le check unset-cpu-requirements (v0.8.3, la version épinglée en CI, activé par défaut) porte le paramètre requirementsType: request. Il n'exige donc aucune limite, et kube-linter lint k8s/base/ k8s/frontend/ sort en 0 sans elle. Le frontend, lui, n'en portait déjà aucune.

Décision 3 — Border par namespace : LimitRange + ResourceQuota

• LimitRange (defaults par namespace) : tout pod sans requests/limits hérite de valeurs par défaut → plus de pod BestEffort qui se faufile. Placement (corrigé en live, voir plus bas) : un LimitRange n'agit qu'à l'admission du pod (defaults injectés à la création, jamais rétroactivement). Il doit donc exister avant les pods → il est créé au bootstrap (Ansible), avant tout composant, et non par une Application GitOps qui se synchronise trop tard. Poulet/œuf assumé : une gouvernance qui doit précéder ArgoCD ne peut pas être gérée par ce même ArgoCD.
• ResourceQuota plafonnant la somme des limits.memory par namespace (livré au Sprint 6, #136) → c'est le garde-fou qui rendrait l'overcommit mémoire structurellement impossible à l'admission. Nuance acquise en live : la somme des limits n'est pas la cause directe d'INC-060 (les limits ne réservent rien) ; le quota reste utile comme plafond dur, mais le vrai levier anti-incident immédiat a été le déclencheur (préinstall Grafana, !195) et la capacité (#114).

Dimensionnement du ResourceQuota (#136)

Un quota vit dans l'overlay (valeur propre à l'env), contrairement au LimitRange qui vit au bootstrap (il doit précéder ArgoCD). Formule retenue :

plafond = (réplicas max de l'env + 2) × consommation d'un pod

Le +2 couvre le surge d'un rolling update (maxSurge: 25 %). C'est le paramètre qui compte : un quota calé au ras des réplicas nominaux laisse tourner la charge mais fait échouer le prochain déploiement, ce qui est le pire des deux mondes (le blocage ne se révèle qu'au déploiement suivant, pas au moment où on pose le quota).

Pas de limits.cpu dans le quota. C'est la conséquence directe de la Décision 2 (CPU compressible → pas de limite CPU par défaut dans le LimitRange). Un ResourceQuota qui borne une ressource exige que chaque pod du namespace la déclare : borner limits.cpu rendrait donc tout le namespace non déployable, puisque ni le LimitRange ni les manifests frontend n'injectent de limite CPU. On borne la mémoire, pas le CPU.

Vérifié sur cluster kind le 2026-07-26, quotas réels du repo (#136) : réplicas nominaux admis ; rolling update convergent en consommant exactement la marge de surge ; pod sans requests admis en Burstable grâce au LimitRange (jamais BestEffort) ; dépassement refusé à l'admission (ReplicaFailure), les quatre dimensions du quota saturant au même point. Ajouter limits.cpu au quota a bien gelé le namespace entier (must specify limits.cpu, Deployment à 0 UP-TO-DATE alors que les pods existants restaient sains) — le mode de défaillance annoncé ci-dessus, reproduit.

Reconfirmé sur EKS le 2026-07-26 (cluster réel, 6 namespaces d'env) : les 6 quotas présents sans limits.cpu, 6/6 LimitRange conformes, 10/10 pods Burstable et zéro BestEffort dans les envs. Le refus de dépassement cite les quatre dimensions ensemble (exceeded quota: default-quota, requested: pods=1, used: pods=3, limited: pods=3) et vient du replicaset-controller en FailedCreate : les pods sous le plafond restent Running. Le quota refuse, il n'évince pas — c'est la propriété à retenir. La saturation simultanée des quatre dimensions se vérifie sur les 6 envs, ce qui rend le quota lisible comme un simple plafond de pods.

Couplage à surveiller (#149). Le +2 de la formule fige une hypothèse sur maxReplicas dans un fichier (resourcequota.yaml) différent de celui qui la porte (le patch HPA de l'overlay). fastapi-prod était le cas limite : HPA max 5 + maxSurge 25 % = pic à 7 pods pour un plafond de 7, soit zéro marge. Corrigé le 2026-08-11 en alignant les bornes sur la capacité mesurée (HPA 2-4, quota 6 pods) plutôt qu'en relevant le quota — voir ci-dessous pourquoi relever seul aurait aggravé la lisibilité. Changer maxReplicas sans recalculer le quota casse le prochain rollout, longtemps après le changement qui en est la cause.

Survenu en réel le 2026-08-11, sans que le cas soit provoqué. Le déplacement des réconciliateurs de plateforme (#158) a permis au HPA prod d'atteindre 5 réplicas pour la première fois, et il y est resté verrouillé (la métrique mémoire d'un processus Python ne redescend pas après un pic — cause analysée en Décision 2, « Corollaire (#164) »). Le rollout suivant s'est donc déclenché HPA au maximum : 10 FailedCreate ... exceeded quota, sur les quatre dimensions simultanément. Deux enseignements qui complètent la propriété « le quota refuse, il n'évince pas » :

• le rollout a abouti malgré tout, par réessais au fur et à mesure que les anciens pods disparaissaient. Le mode de défaillance réel n'est donc pas un déploiement bloqué mais un déploiement plus lent et plus fragile, que kubectl rollout status déclare successfully rolled out sans rien signaler ;
• relever le quota seul n'aurait rien réglé : au même instant le nœud était à 98 % de mémoire réservée. Le pod aurait été admis puis serait resté Pending, déplaçant le symptôme de « refusé à l'admission » vers « accepté mais jamais placé », moins visible et non plus sain. Quota et capacité se règlent ensemble, jamais l'un sans l'autre.

Corollaire (#148) — hors du périmètre du LimitRange, le réglage est à la charge du composant

Le LimitRange posé au bootstrap couvre les namespaces d'environnement. Il ne s'applique pas à kube-system, et c'est délibéré : y injecter des defaults reviendrait à dimensionner à l'aveugle des composants système dont on ne maîtrise ni les manifestes ni les besoins.

Cette exclusion dit qu'on ne defaulte pas ce namespace. Elle ne dit pas qu'on peut y laisser n'importe quoi en BestEffort. La nuance a été perdue une fois : le Done when de #136 ne portait que sur les namespaces d'env, tous Burstable, et personne n'a regardé ce qui restait hors périmètre. Relevé le 2026-07-26 pendant la validation de #136, cinq pods Cilium et Hubble étaient BestEffort, dont cilium-envoy, le dataplane L7.

Un pod BestEffort est le premier évincé sous MemoryPressure, ce qui est le scénario d'INC-060. Là où aucun LimitRange n'agit, la seule façon de régler la QoS est à la source du composant, c'est-à-dire dans ses values Helm — ici ansible/bootstrap.yml, qui installe Cilium.

Deux règles en découlent, appliquées en #148 :

• La criticité décide, pas le namespace. cilium-envoy et cilium-operator reçoivent des requests explicites. Hubble (relay et UI) reste volontairement BestEffort : c'est ce qui rend l'ordre d'éviction intentionnel plutôt qu'accidentel. Sous pression, le nœud sacrifie l'observabilité et garde le dataplane.
• La mesure vaut dans les conditions où elle a été prise. Le pic mesuré de cilium-envoy (16,1 MiB, 1,6 m) l'a été sans aucune politique L7 : le dépôt ne contient que des NetworkPolicy standard L3/L4, donc le proxy tourne à vide — il n'a pas bougé pendant que 200 580 requêtes traversaient le cluster le 2026-08-16. Le jour où une CiliumNetworkPolicy avec des règles HTTP sera écrite, ces valeurs deviendront fausses. Elles portent donc leur condition de validité en commentaire, à côté d'elles.

Conséquences

• L'incident INC-060 ne peut plus se reproduire par overcommit : un déploiement qui ferait dépasser le quota est refusé à l'admission, au lieu de tuer le nœud au runtime.
• Les valeurs (requests/limits, plafond de quota) se calent et se valident en live (MR3) : un quota trop serré bloquerait les déploiements, donc il se vérifie sur le cluster réel, pas seulement par helm template.
• Classe QoS explicite sur le critique → comportement d'éviction prévisible sous pression.
• Alternatives écartées : monter un nœud plus gros sans gouvernance (déplace le mur sans le supprimer) ; Karpenter tout de suite (ne corrige pas l'overcommit runtime, il réagit au Pending — donc inutile sans requests honnêtes ; reporté Sprint 6).

Validation live (2026-06-25)

Boot from-scratch, mesures par pod via Prometheus (metrics-server réparé en parallèle, #115/INC-061).

• Déclencheur (!195) ✅ : cluster monté propre, api 200, aucune cascade NodeNotReady au redéploiement Grafana (préinstall plugins désactivé). C'est le gain anti-incident immédiat.
• Right-sizing (!196) ✅ : valeurs mesurées bien déployées (fastapi req 100m/128Mi limit 256Mi ; argocd-application-controller req 512Mi limit 1Gi — le runaway BestEffort à ~800Mi est désormais capé ; grafana et prometheus req 384Mi limit 512Mi).
• Nuance honnête sur l'overcommit : la somme des limits.memory du nœud est montée (168 % → 217 %), pas baissée. Ce n'est pas un échec : c'est l'effet mécanique d'avoir donné une limite explicite (1Gi) à un gros pod jusque-là non borné (BestEffort = 0 dans la somme). Borner un runaway fait monter la somme des limits tout en réduisant le risque réel. La métrique qui compte est ailleurs : requests mémoire à 91 % → nœud tendu, ce qui confirme que le vrai fix capacité est #114, pas le right-sizing seul.
• LimitRange (!197 → !199) — trou trouvé puis corrigé, reprouvé from-scratch ✅ : livré en GitOps (sync-wave 2), il arrivait après les composants déjà démarrés → ~14 pods plateforme (argocd, cert-manager, ESO, external-dns) restaient BestEffort (un LimitRange n'agit qu'à l'admission). Corrigé (!199) : LimitRange déplacé au bootstrap Ansible, créé avant tout composant. 2e boot from-scratch (2026-06-25) : plus AUCUN BestEffort dans les 8 namespaces possédés, fastapi né restricted (PSA) une seule fois, LimitRange présent partout avant les pods.

La gouvernance honnête révèle la sur-souscription (le vrai enseignement)

Conséquence directe et assumée du LimitRange efficace : chaque pod jusque-là BestEffort réserve désormais le defaultRequest (64Mi). Sur le boot from-scratch, le nœud unique t3.medium est monté à 99 % de requests mémoire (3286Mi / ~3319 allouables) → prometheus-kps-prometheus-0 (request 384Mi) ne peut plus être planifié (FailedScheduling: Insufficient memory). À noter : MemoryPressure: False — c'est de la sur-réservation (somme des requests), pas un manque de RAM réelle (usage ~69 %) ; les pods ne consomment pas ces 64Mi, ils bloquent juste le scheduler.

Décision (assumée avec Youssef) : ne PAS band-aider en baissant le defaultRequest à un plancher-jeton (16Mi) qu'il faudrait remonter ensuite. On garde des requests honnêtes (64Mi) : c'est future-correct (dès que la capacité existe, tout se planifie sans rien retoucher). La gouvernance par réservations et la capacité sont couplées : on ne peut pas réserver un plancher pour chaque pod sur un nœud déjà plein.

→ #114 (ADR 026) passe de « souhaitable » à prérequis dur, prouvé par la mesure (requests à 99 %). #112 reste ouvert : la gouvernance est livrée et validée (no BestEffort, runaways capés), mais la stack ne planifie entièrement qu'après #114 (capacité). On clôt #112 avec #114.

Évolution possible

• ADR 026 (#114) : segmenter en node groups core (on-demand) / observability (Spot) pour isoler les workloads gourmands du trafic.
• Karpenter (Sprint 6) : une fois les requests fiables, l'autoscaling des nœuds devient pertinent (il se déclenche sur le Pending, qui dépend des requests).

---

Date : 2026-06-24 Sprint : 5 Issue : #112 (INC-060)