Aller au contenu principal

Les watchers Kubernetes à l'échelle : un seul watch, des milliers de dashboards

Comment nous avons construit une interface temps réel adossée à Kubernetes pour des milliers d'utilisateurs simultanés, sans multiplier les watches sur l'API server — watches par scope, propriété Redis, leases à la demande et fan-out d'événements.

JV

Joël Vappiani

20 min

Partager sur X

Kappsul est une plateforme éducative construite à l'Université de Lorraine. Un étudiant choisit un service dans un catalogue, obtient un namespace Kubernetes, et un dashboard montre ce qui tourne à l'intérieur. Ce dashboard, c'est le produit : il doit être temps réel. Il doit aussi survivre à trois mille onglets ouverts en même temps.

C'est l'histoire du petit système distribué que nous avons placé entre le navigateur et l'API Kubernetes pour que ces deux affirmations soient vraies en même temps.

Un porte-conteneurs entièrement chargé de conteneurs

Le piège : une session est une très mauvaise unité d'échelle​

« Temps réel » sonne comme une préoccupation d'interface. Dans un produit adossé à Kubernetes, c'est une préoccupation d'API server, et les implémentations évidentes échouent de deux manières très différentes.

Le polling. Chaque dashboard demande l'état courant au backend toutes les quelques secondes. Avec trois mille dashboards ouverts et un poll toutes les cinq secondes, cela fait environ six cents requêtes par seconde avant même que quiconque clique. Chaque réponse est une lecture complète : lister les deployments, les statefulsets, les pods, le resource quota. La charge utile grandit avec le nombre d'objets, et les données sont périmées par définition. Vous avez construit un générateur de charge contre votre propre control plane, et vous affichez quand même aux utilisateurs des chiffres faux de quelques secondes.

Un watch par navigateur. Kubernetes fournit une API de streaming, donc le réflexe est d'ouvrir un flux par onglet. Un seul dashboard a besoin de plus d'un flux : deployments et statefulsets pour un workspace, ou pods pour une application précise, ou namespaces pour la vue admin. Trois mille utilisateurs deviennent six à neuf mille flux longue durée, chacun étant une connexion que l'API server doit maintenir, bufferiser et fan-out. L'API server est une ressource partagée et rare : chaque flux qu'il sert pour votre UI est de la capacité qu'il ne consacre pas à faire tourner le cluster.

Il y a un troisième piège, plus subtil : lancer un watch par pod backend sans coordination. Vous passez le service à dix réplicas, et chaque réplica ouvre son propre watch pour le même namespace. L'UI a l'air correcte. L'API server voit dix flux identiques. Mettre à l'échelle votre propre service multiplie la charge sur le composant que vous essayiez de protéger.

L'erreur est la même dans les trois cas : nous avons fait du watch une propriété de l'utilisateur. Un watch est une propriété de la donnée. Si mille personnes regardent le même workspace, il n'y a aucune raison pour que l'API server en connaisse plus d'une.

Watch 101, en une page​

Un watch Kubernetes est un flux de deltas sur une collection. On liste d'abord la collection pour obtenir un metadata.resourceVersion, puis on regarde à partir de cette version. Le serveur envoie des événements ADDED, MODIFIED, DELETED et ERROR ; chaque objet porte le resourceVersion nécessaire pour reprendre. Le watch est borné par un timeout, et quand le serveur le ferme — sur timeout, sur erreur, ou parce que l'historique sous-jacent a expiré — le client est censé rembobiner et regarder à nouveau depuis la dernière version qu'il a vue.

Deux détails font l'essentiel du travail dans un design comme le nôtre :

  • Les sélecteurs. Un watch n'est aussi coûteux que l'ensemble qu'il observe. Le cloisonnement par namespace et les label selectors (app.kubernetes.io/instance=my-app, meta.kappsul.io/user-ns=yes) réduisent le flux à exactement la tranche dont l'UI a besoin.
  • Une durée bornée. Un watch qui tourne indéfiniment est un watch que personne ne réévalue. Un watch borné est un point de contrôle naturel : quand la fenêtre se ferme, vous pouvez demander si quelqu'un s'y intéresse encore avant d'en ouvrir une autre.

Si vous avez écrit un controller, vous connaissez la réponse standard : un informer. Un watch par type de ressource et par processus, un cache en mémoire, et des handlers qui fan-out vers ceux qui ont besoin de la donnée. Les informers sont la bonne brique de base pour un controller. Ce ne sont pas une réponse complète pour une application web multi-tenant, parce qu'un informer est local au processus. Dix réplicas signifient toujours dix informers, et vous ne voulez pas non plus d'un informer par utilisateur final. Ce qu'il faut réellement coordonner, c'est le watch, et l'unité de coordination n'est ni la connexion ni le processus. C'est le scope.

L'unité de partage : un scope​

Un scope est la tranche du cluster qu'un groupe de spectateurs a en commun. Dans Kappsul, nous en avons trois :

ScopeObjets KubernetesSélecteurQui le regarde
allWorkspacesNamespacesmeta.kappsul.io/user-ns=yesVues admin
workspace:{name}Deployments, StatefulSetslimité au namespaceTous les utilisateurs d'un dashboard de workspace
app:{workspace}:{app}Podsapp.kubernetes.io/instance={app}Tous les utilisateurs d'une page de détail d'application

C'est toute l'astuce, exprimée sous forme de tableau. Un scope est une promesse : ces spectateurs regardent la même donnée, donc ils peuvent partager le même flux. Le nombre de watches que voit l'API server devient le nombre de scopes actifs, pas le nombre d'utilisateurs.

Règle de trois : si chaque dashboard avait besoin de trois flux et que chaque utilisateur avait le sien, trois mille utilisateurs voudraient dire neuf mille watches. Si ces utilisateurs sont répartis sur six cents workspaces, et que la vue admin se réduit à un seul scope global, le système a besoin d'environ six cent un. Les utilisateurs sont une dimension de l'UI, pas du watch.

Remarquez ce qui n'est pas dans le diagramme : une flèche de chaque navigateur vers l'API server. La seule chose qui touche Kubernetes est l'unique propriétaire du scope.

Un propriétaire par scope​

La couche de coordination est un petit package Go, watch-manager, partagé par les services admin, workspace et application. Il ne connaît rien à Kubernetes. Il implémente un lease : exactement une instance de conteneur possède un scope à la fois, et le lease est stocké dans Redis sous une clé dérivée du scope.

watch-all-workspaces
watch-workspace:{workspace}
watch-app:{workspace}:{app}

Démarrer un watch est une décision à trois branches : rejoindre, revendiquer, ou prendre le relais.

La branche « rejoindre » est celle qui rend des milliers d'utilisateurs peu coûteux. Un second spectateur ne crée pas un second watch ; il prouve que le scope est toujours désiré en repoussant le lease, et renvoie le propriétaire existant.

// watch-manager/manager.go (trimmed)
watchKey := handler.GenerateWatchKey(watchCtx)

currentWatcher, _ := c.redisClient.Get(ctx, watchKey).Result()
if currentWatcher != "" {
alive, _ := c.isContainerStillWatching(ctx, currentWatcher, config)

if alive {
// Someone already watches this scope: join it, do not duplicate the stream.
ttl := time.Duration(config.WatchRedisTTL) * time.Second
c.redisClient.Set(ctx, watchKey, currentWatcher, ttl)
return &WatchResult{Success: true, WatchingContainerID: currentWatcher}, nil
}

// The owner is gone: exactly one contender wins the takeover.
taken, _ := c.attemptTakeover(ctx, currentWatcher, watchKey, config)
if !taken {
return &WatchResult{Success: false, Message: "takeover lost"}, nil
}
}

// Nobody owns the scope: claim it, then start the actual watch.
ttl := time.Duration(config.WatchRedisTTL) * time.Second
c.redisClient.Set(ctx, watchKey, c.containerID, ttl)
c.startHeartbeat(watchKey, config)
if err := handler.StartWatch(ctx, watchCtx); err != nil {
c.stopHeartbeat(watchKey)
c.redisClient.Del(ctx, watchKey)
return nil, err
}

Prouver que le propriétaire est vivant​

La propriété seule ne suffit pas : un pod peut mourir en gardant la clé. Le propriétaire prouve sa vivacité avec un heartbeat, et chaque concurrent le vérifie avant de lui faire confiance. Le heartbeat est écrit toutes les trente secondes avec un TTL de soixante secondes, et un heartbeat plus vieux que soixante secondes est considéré comme mort.

// A per-container heartbeat, refreshed by the owner's active watch loops.
heartbeatKey := config.HeartbeatPrefix + c.containerID
ticker := time.NewTicker(time.Duration(config.HeartbeatInterval) * time.Second)

go func() {
for range ticker.C {
ts := strconv.FormatInt(time.Now().Unix(), 10)
c.redisClient.Set(ctx, heartbeatKey, ts,
2*time.Duration(config.HeartbeatInterval)*time.Second)
}
}()

// ...and on the reader side:
timeSinceHeartbeat := time.Now().Unix() - timestamp
return timeSinceHeartbeat < 60, nil

Prendre le relais sans stampede​

Quand le propriétaire est déclaré mort, chaque réplica qui le remarque peut tenter de prendre le relais. La revendication doit être atomique, sinon vous obtenez exactement ce que vous essayiez d'éviter : plusieurs pods convaincus de posséder le scope, chacun ouvrant un watch. Nous faisons le compare-and-swap dans Redis avec un script Lua, pour que la vérification et l'écriture soient une seule opération.

-- takeover.lua: only replace the owner we all agreed was dead.
local current = redis.call('get', KEYS[1])
if current == ARGV[1] then
redis.call('set', KEYS[1], ARGV[2], 'EX', ARGV[3])
return 1
else
return 0
end

Un conteneur concurrent obtient 1, démarre le watch et commence un heartbeat. Les autres obtiennent 0 et se retirent. Le gagnant supprime aussi la clé de heartbeat du propriétaire mort, pour que le concurrent suivant voie un état propre.

Le lease est la source de vérité, pas le watch​

Le changement le plus utile de tout le design a été d'arrêter de penser le watch comme une ressource que l'on démarre et que l'on arrête, et de le penser comme un lease que l'on maintient en vie.

Arrêter un watch ne supprime pas la clé. Cela abaisse le TTL à soixante secondes et arrête le heartbeat. Cette période de grâce compte pour trois raisons :

  • un autre utilisateur peut encore regarder le même scope ;
  • le même utilisateur peut recharger la page ou se reconnecter via un réseau instable ;
  • tuer le flux immédiatement garantirait un démarrage à froid à la requête suivante.

Le frontend est l'autre moitié du lease. Un hook React démarre le watch au montage, le renouvelle toutes les deux minutes tant que la page est ouverte, et l'arrête au démontage. Le renouvellement n'est pas un nouveau watch ; c'est la même branche « rejoindre » que le backend supporte déjà, qui prolonge le lease si le propriétaire est vivant et prend le relais sinon.

// useWatch.ts (trimmed)
const { enabled = true, renewalInterval = 2 * 60 * 1000 } = options;

useEffect(() => {
if (!enabled) return;

startWatch(); // claim or join the lease
const timer = setInterval(renewWatch, renewalInterval); // keep the lease fresh

return () => {
clearInterval(timer);
stopWatch(); // drop the lease, not the stream
};
}, [enabled, config.type]);

Cela donne au système trois horloges indépendantes, et il vaut la peine d'être explicite sur ce que chacune protège :

HorlogeValeurOù elle vitCe qu'elle protège
Fenêtre de watch Kubernetes90sflux vers l'API serverborne chaque flux et force un rembobinage
Intervalle de heartbeat30spod propriétaire → Redisprouve que le propriétaire est vivant
Péremption du heartbeat60sRedis / lecteurdéclare le propriétaire mort
TTL du lease180sRedisconserve la propriété tant que le scope est regardé
Renouvellement client120snavigateurgarde le lease frais tant que la page est ouverte
Arrêt gracieux60sRedislaisse les reconnexions et les autres spectateurs gagner

L'ordre n'est pas accidentel. Le client renouvelle avant que le lease n'expire. Le heartbeat est bien plus fréquent que le lease, donc un propriétaire mort est remarqué bien avant que le lease lui-même n'arrive à échéance. La fenêtre de watch Kubernetes est indépendante des deux : elle est là pour rendre le flux fini, pas pour maintenir la propriété.

Le watch lui-même : borné, rembobiné, et volontairement ennuyeux​

Le watch-manager décide qui regarde. Le service décide quoi regarder, et il le fait avec une boucle de rewatch manuelle. Pour un workspace, cela signifie les deployments et les statefulsets d'un namespace, chacun rembobiné depuis le dernier resourceVersion vu.

// workspace-service, WatchWorkspaceResources (trimmed)
for {
deploymentWatcher, _ := ws.k8sClient.WatchDeployments(ctx, workspace, metav1.ListOptions{
ResourceVersion: deploymentResourceVersion,
TimeoutSeconds: &timeout, // 90 seconds
})
statefulSetWatcher, _ := ws.k8sClient.WatchStatefulSets(ctx, workspace, metav1.ListOptions{
ResourceVersion: statefulSetResourceVersion,
TimeoutSeconds: &timeout,
})

watchLoop:
for {
select {
case event, ok := <-deploymentWatcher.ResultChan():
if !ok {
statefulSetWatcher.Stop()
break watchLoop // window closed: rewind with the last version
}
if d, ok := event.Object.(*appsv1.Deployment); ok {
deploymentResourceVersion = d.ResourceVersion
}
ws.emitWorkspaceChanged(ctx, workspace, "watch-deployment")

case event, ok := <-statefulSetWatcher.ResultChan():
// same shape for StatefulSets

case <-ctx.Done():
deploymentWatcher.Stop()
statefulSetWatcher.Stop()
return
}
}

time.Sleep(time.Second) // small backoff before rewinding
}

Deux choses méritent d'être soulignées.

Le rembobinage est l'endroit où l'on gère les parties désagréables. Un watch peut se fermer pour une raison ordinaire (timeout) ou mauvaise (ERROR, historique expiré). Transporter le dernier resourceVersion à travers le rembobinage évite les trous dans le cas courant. Si l'API server répond que la version est trop ancienne — le cas 410 Gone — la bonne récupération n'est pas de réessayer la même version indéfiniment, mais de lister à nouveau et de repartir de zéro. La fenêtre bornée existe en partie pour rendre cette décision peu coûteuse : vous n'êtes jamais à plus de quatre-vingt-dix secondes d'un redémarrage propre.

Les sélecteurs font partie du contrat, pas de l'optimisation. Le watcher admin liste les namespaces avec meta.kappsul.io/user-ns=yes. Le watcher d'application liste les pods avec app.kubernetes.io/instance={app} et regarde depuis le resourceVersion de la liste. Le watcher de workspace reste à l'intérieur d'un namespace. Si vous vous surprenez à regarder une collection large et à filtrer en mémoire, vous avez déplacé le coût de l'API server vers votre propre processus et conservé la pire partie du flux.

Fan-out : envoyer des signaux, pas des objets​

À ce stade, le côté Kubernetes est réglé : un flux par scope actif. La question restante est de savoir comment un flux devient des mises à jour pour trois mille navigateurs.

La réponse courte est que le navigateur ne voit jamais un objet Kubernetes. Il voit un petit signal, puis il lit la vérité via l'API normale.

Le service émet un événement de topic avec une routing key dans l'espace client.*. Le gateway possède une queue durable client liée à client.# sur l'exchange events. Il consomme l'événement, transforme la routing key en nom de souscription GraphQL, et publie dans Redis Pub/Sub. Redis est ce qui rend le gateway horizontalement scalable : un WebSocket peut être connecté à n'importe quel réplica, et l'événement l'atteint quand même.

// gateway: routing key -> subscription name
private getSubscriptionName(routingKey: string): string {
return routingKey
.split(/[._-]/)
.filter((part) => part !== 'client')
.map((part, i) => (i === 0 ? part : part[0].toUpperCase() + part.slice(1)))
.join('');
}

// client.workspace-resources.changed -> workspaceResourcesChanged

La charge utile est volontairement minuscule : un nom de workspace, un nom d'application, et une phase comme initial, watch-deployment ou watch-statefulset. C'est un message d'invalidation de cache, pas un transfert de données. Le frontend s'abonne, filtre par les arguments (workspace, et pour les applications aussi app), et rafraîchit via la même requête qu'il aurait utilisée au premier chargement.

// The event is a signal. Read the truth through the API.
useEffect(() => {
if (subscriptionData?.workspaceResourcesChanged) {
refetch();
}
}, [subscriptionData, refetch]);

Ce choix apporte trois choses :

  • Bande passante et couplage. Les objets Kubernetes sont gros et versionnés ; un signal de changement n'est ni l'un ni l'autre. Le navigateur n'a pas besoin de comprendre les Deployments pour savoir que les deployments ont changé.
  • L'autorisation reste sur le chemin de lecture. L'événement dit « quelque chose a changé » ; le refetch passe par la requête GraphQL authentifiée normale, avec les règles d'accès normales.
  • La cohérence reste là où elle vit déjà. Le chemin de requête sait assembler le dashboard depuis la base et le cluster. Le chemin d'événement n'a pas à réimplémenter cet assemblage.

Le coût est l'amplification des refetchs : un vrai changement peut déclencher un refetch par spectateur connecté. C'est généralement le bon compromis à cette échelle — un refetch est une lecture bon marché et cacheable, alors qu'un flux par utilisateur ne l'est pas — mais c'est un coût à surveiller, pas à ignorer.

L'échec est le cas normal​

Le design part du principe que les pods meurent. Quand le propriétaire d'un scope meurt, rien n'est supprimé ; le lease cesse simplement d'être rafraîchi.

Un heartbeat plus vieux que soixante secondes suffit à un autre réplica pour tenter un takeover, et le compare-and-swap Lua garantit qu'un seul réussit. La fenêtre d'échec pratique est de l'ordre d'une minute, plus le temps qu'un renouvellement ou un scan de démarrage le remarque.

La récupération au démarrage utilise les mêmes primitives. Chaque service scanne son propre préfixe dans Redis, restaure les scopes qu'il possède déjà, et tente de prendre le relais sur les scopes dont le propriétaire est mort. C'est pourquoi un rolling restart ne produit pas de stampede de démarrages à froid : le nouveau pod ne revendique pas aveuglément tous les scopes qu'il voit ; il vérifie d'abord le heartbeat.

Le système est volontairement eventually consistent pendant un failover. Pendant une courte fenêtre, deux watchers peuvent observer le même scope. C'est acceptable parce que les événements sont des signaux d'invalidation idempotents : l'UI refetch et converge. Un bref watch en double est un problème bien plus petit qu'un protocole de coordination qui bloque sur un processus mort.

Ce que ce design coûte​

Il serait malhonnête de présenter cela comme gratuit. La charge sur l'API server n'a pas disparu ; elle s'est déplacée, et les nouveaux endroits sont moins chers et plus faciles à scaler indépendamment, mais ce sont quand même des endroits.

  • Redis est sur le chemin chaud. Chaque démarrage, renouvellement et contrôle de vivacité est un aller-retour Redis. C'est un petit nombre d'opérations par scope, pas par utilisateur, mais Redis fait désormais partie de votre histoire de disponibilité. Traitez-le comme tel : Sentinel ou un déploiement managé, et un plan pour ce qui se passe quand il est lent.
  • La vivacité dépend des horloges. Le contrôle de heartbeat compare des timestamps écrits par différents pods. Une discipline d'horloge raisonnable suffit, mais un pod avec une horloge très décalée peut paraître mort ou immortel. Un signal de vivacité purement basé sur le TTL est une piste de durcissement.
  • Les refetchs peuvent partir en stampede. Une rafale qui touche cinq cents pods produit une rafale d'invalidations, puis une rafale de refetchs. Le debounce ou le coalescing par scope, et le jitter sur les rafraîchissements client, sont les prochains leviers évidents.
  • Des watches en double existent brièvement. Le failover n'est pas atomique à travers l'API server. Acceptez-le, et assurez-vous que des flux en double ne peuvent pas causer des effets de bord en double.
  • Il y a plus de surface à opérer. Clés Redis, heartbeats, TTL de leases, un broker de messages, une couche pub/sub et des réplicas WebSocket. Chacun est simple ; la combinaison est un système qu'il faut observer.

Le compromis reste largement en faveur de ce design, parce que la ressource qu'il protège — l'API server Kubernetes — est celle qui est partagée par tout le reste du cluster.

Régler les paramètres​

Les chiffres ne sont pas magiques. Ils encodent quelques relations simples :

ParamètreValeur KappsulContrainte
WatchExpirationTime90sla fenêtre entre deux rembobinages
WatchRedisTTL180sdoit dépasser l'intervalle de renouvellement client
HeartbeatInterval30sdoit être bien inférieur au seuil de péremption
Péremption du heartbeat60sdoit être inférieur au TTL du lease
Renouvellement client120sdoit être inférieur à WatchRedisTTL
TTL d'arrêt gracieux60sassez court pour libérer le scope, assez long pour survivre à un reload

Si vous ne retenez qu'une règle de ce tableau, retenez celle-ci : le client doit renouveler avant que le lease n'expire, et le heartbeat doit expirer avant le lease. Inversez cet ordre et vous perdrez soit des watches vivants, soit vous garderez des watches morts.

Ce que je mesurerais ensuite​

Le design n'est défendable qu'avec des chiffres, et les chiffres qui comptent sont principalement du côté de l'API server :

  • Les watches par type de ressource, et comment ce nombre suit les scopes actifs plutôt que les utilisateurs connectés. C'est l'affirmation centrale du design.
  • Le QPS de list et de watch, plus le taux de réponses 410 Gone. Un taux de 410 qui monte signifie que votre rembobinage est trop lent ou que vos fenêtres sont trop longues.
  • La latence de livraison des événements, p50 et p99, depuis l'événement Kubernetes jusqu'au refetch du navigateur. C'est ce que les utilisateurs ressentent vraiment.
  • Le taux de refetch par scope. C'est là qu'une rafale devient une stampede.
  • Le temps de failover, depuis la mort du propriétaire jusqu'au watch d'un nouveau propriétaire. Les valeurs de heartbeat et de lease ci-dessus impliquent une cible ; mesurez si vous l'atteignez.

Si je devais durcir cela davantage, je commencerais par le debounce par scope des signaux d'invalidation, du jitter sur les renouvellements client, et un contrôle de vivacité plus strict qui ne dépend pas de la comparaison d'horloges murales entre pods.

À retenir​

  • Faites du watch une propriété de la donnée, pas de l'utilisateur. Définissez des scopes — ensemble de ressources, sélecteur et namespace — et partagez un flux par scope.
  • Élisez un propriétaire par scope. Une clé Redis avec un TTL suffit, à condition d'ajouter un heartbeat pour qu'un propriétaire mort ne la garde pas indéfiniment.
  • Rendez le takeover atomique. Un compare-and-swap Lua évite la stampede de failover qui recréerait le problème que vous avez résolu.
  • Traitez le watch comme un lease. Démarrez à la consultation, renouvelez tant que c'est consulté, baissez le TTL à l'arrêt, et laissez-le expirer naturellement.
  • Bornez et rembobinez le flux. Une fenêtre finie vous force à réévaluer la demande et vous donne un endroit propre pour gérer les resourceVersion expirés.
  • Fan-out des signaux, pas des objets. Laissez un événement Kubernetes devenir une petite invalidation, et laissez chaque client lire la vérité via l'API normale.
  • Partez du principe que l'échec est normal. Récupérez les scopes au démarrage, acceptez un bref chevauchement, et rendez les événements en double inoffensifs.
  • Protégez d'abord l'API server. C'est la ressource partagée ; tout le reste de ce design existe pour la garder hors du chemin chaud.