Kappsul a commencé comme un service proposé à l'Université de Lorraine : les étudiants qui avaient besoin d'un environnement isolé pour déployer une application pouvaient en obtenir un depuis un cluster Kubernetes partagé, via une interface web. La plateforme devait transformer un clic en un namespace avec un quota, des règles d'accès, une frontière réseau et un endroit où faire tourner l'application de l'étudiant. C'est un problème de multi-tenancy avant d'être un problème Kubernetes : chaque étudiant a besoin d'assez de liberté pour être utile, et d'une frontière assez dure pour ne pas impacter les autres.
La première implémentation utilisait ArgoCD. Chaque workspace était une Application ArgoCD, toutes pointant vers le même dépôt Git, et ArgoCD faisait la reconciliation. C'était déclaratif, auditable, et ça fonctionnait. Mais cela faisait dépendre une feature centrale de notre produit d'ArgoCD : créer un workspace exigeait une installation ArgoCD et une source Git, et la plateforme ne pouvait pas tourner sur un cluster qui n'en avait pas. Nous voulions que le service soit portable sur n'importe quel cluster Kubernetes, et nous ne voulions pas qu'une de ses fonctionnalités cœur soit déléguée à un outil externe.
Nous avons aussi réalisé que nous n'avions pas besoin de tout ArgoCD. Nous avions besoin de deux comportements :
- self-heal : un étudiant ne doit pas pouvoir modifier les parties de son workspace qui appartiennent à la plateforme ;
- propagation : un changement de la configuration centrale doit mettre à jour tous les workspaces et leurs ressources.
Nous avons donc gardé GitOps pour ce qu'il fait bien — changer la configuration centrale dans Git — et écrit un petit opérateur qui appartient à l'application. L'opérateur crée l'enveloppe du workspace, l'empêche de dériver, et propage le template partagé à tous les tenants. Il n'utilise que l'API Kubernetes et un CRD, donc il tourne sur n'importe quel cluster.
Cet article parle de cet opérateur : le modèle d'isolation, les deux comportements GitOps, et les compromis.
Le multi-tenant est la raison d'être de l'opérateur
Un workspace n'est pas juste un namespace. C'est une enveloppe d'isolation :
| Couche | Ce qu'elle donne à l'étudiant | Ce qu'elle protège la plateforme de |
|---|---|---|
| Namespace | Un endroit privé pour déployer | Les collisions de noms et l'accès inter-tenant accidentel |
| ResourceQuota | Un budget CPU, mémoire, stockage et pods prévisible | Un workspace qui affame le cluster |
| LimitRange | Des requests et limits par défaut pour les conteneurs | Les pods sans limits qui passent au travers |
| RBAC | admin dans leur namespace, pour le propriétaire et les invités | Les étudiants qui agissent hors de leur workspace |
| NetworkPolicy | Default-deny avec ingress et egress explicites | Le trafic inter-namespace et l'egress inattendu |
| Pod Security Admission | baseline en enforcement, restricted en audit/warn | Les pods privilégiés ou dangereux |
Le premier travail de l'opérateur est de créer cette enveloppe pour chaque étudiant, avec
la même forme et les bonnes valeurs. L'étudiant obtient ensuite admin dans le namespace
pour pouvoir déployer et gérer ses applications. C'est le contrat multi-tenant : un
namespace privé avec une frontière dure, et assez de liberté à l'intérieur pour être
utile.
La frontière est appliquée par les primitives Kubernetes, pas par l'opérateur. Le travail de l'opérateur est de s'assurer que l'enveloppe existe et reste correcte. Cette distinction compte pour la suite de l'article.
Portabilité : ne pas mettre un outil externe sur le chemin critique
Pour nous, la portabilité signifie une chose : l'opérateur ne doit avoir besoin de rien d'autre que d'une API Kubernetes et du CRD. Pas d'ArgoCD, pas de serveur Git, pas d'accès réseau à Git au runtime. C'est la conséquence directe de la première implémentation : une Application ArgoCD par workspace, toutes pointant vers le même dépôt Git. Ça fonctionnait, mais cela faisait dépendre la création d'un workspace d'une installation ArgoCD et de sa source Git. Une opération produit centrale se trouvait derrière une dépendance qui n'avait rien à voir avec le produit.
L'opérateur n'utilise donc que l'API Kubernetes et un CRD. GitOps reste la manière dont le
template arrive dans le cluster : le chart de la plateforme, y compris le template de
ressources du workspace, peut être déployé par ArgoCD, Flux, Helm ou kubectl apply.
L'opérateur s'en moque. C'est le runtime qui transforme ce template en namespaces de
tenants.
C'est l'argument de portabilité en une phrase : GitOps pour la livraison, un opérateur pour le runtime.
Les deux comportements GitOps dont nous avions réellement besoin
Nous n'avions pas besoin de tout ArgoCD. Nous avions besoin du self-heal et de la propagation, et de rien d'autre dans la boîte à outils GitOps.
- Self-heal. Si un étudiant modifie le quota, le limit range, le RBAC ou la network policy, l'opérateur le remet en place.
- Propagation. L'enveloppe du workspace est définie une fois. Changez cette unique configuration, et tous les workspaces et leurs ressources sont mis à jour en conséquence.
Nous n'avions pas besoin d'une Application par tenant, d'un dashboard de sync par workspace, d'un app-of-apps ou d'une orchestration multi-cluster. Nous avions besoin d'un controller qui possède l'enveloppe, détecte le drift et applique un template partagé.
L'opérateur gère aussi la création et la suppression, parce qu'un cycle de vie de tenant a besoin des deux. Mais le self-heal et la propagation sont la raison de son existence.
Le CRD est l'enregistrement du tenant
Le CRD Workspace est volontairement petit. Le spec est l'entrée ; le status est la
mémoire durable de l'opérateur.
type WorkspaceSpec struct {
UserID string `json:"userId"`
UserEmail string `json:"userEmail,omitempty"`
UserCheckSum string `json:"userCheckSum,omitempty"` // generated by the controller
Guests []string `json:"guests,omitempty"`
Namespace string `json:"namespace"`
TemplateConfigMap string `json:"templateConfigMap,omitempty"`
}
type WorkspaceStatus struct {
Phase WorkspacePhase `json:"phase"`
ObservedGeneration int64 `json:"observedGeneration,omitempty"`
ManagedResources []ManagedResource `json:"managedResources,omitempty"`
LastTemplateVersion string `json:"lastTemplateVersion,omitempty"`
PendingDeletions []PendingDeletion `json:"pendingDeletions,omitempty"`
}
managedResources est la liste des ressources créées par l'opérateur, indexées par groupe,
version, kind, namespace et nom. lastTemplateVersion est le resourceVersion du ConfigMap
qui a été appliqué. pendingDeletions est la file de retry pour les ressources retirées du
template mais pas encore supprimées.
Tout mettre dans le status est délibéré. L'opérateur ne garde aucun état durable propre ; un redémarrage de pod ne perd rien. Le CRD est l'enregistrement du tenant, et le namespace est la frontière d'isolation.
La boucle
Le controller est un design classique informer + workqueue, avec trois sources d'événements :
- un informer Workspace, limité au namespace qui contient les CRs ;
- un informer ConfigMap, limité au namespace qui contient les templates ;
- un watcher de ressources dynamique, qui observe tout ce qui est étiqueté comme appartenant au controller, dans tous les namespaces, pour détecter le drift.
La queue est rate-limitée deux fois : un backoff exponentiel en cas d'échec, de 5 millisecondes à 1000 secondes, et un token bucket à 50 éléments par seconde avec un burst de 300. La partie exponentielle protège un workspace cassé du hot-looping. Le bucket protège l'API server quand un événement partagé fan-out vers tout le monde.
L'optimisation la plus importante est celle qui ne fait rien. Si un workspace est Active,
que sa generation n'a pas changé, qu'il n'y a pas d'annotation de drift et que sa version
de template est à jour, le reconciler retourne sans un seul appel API. En régime stable,
ce chemin de skip supprime la grande majorité du travail de reconciliation.
Un template, plusieurs tenants
L'enveloppe du workspace est définie une fois, dans un ConfigMap. Ce ConfigMap fait partie du chart de la plateforme, donc il est géré dans Git et livré par l'outil GitOps que le cluster utilise.
Le template contient deux couches de templating. La couche externe est Helm, évaluée au déploiement de la plateforme. La couche interne est un template Go, évalué par l'opérateur pour chaque workspace. L'équipe plateforme contrôle la forme ; l'opérateur remplit les valeurs depuis le CR.
# workspace-resource-template (rendered by Helm, then by the operator)
data:
namespace.yaml: |
apiVersion: v1
kind: Namespace
metadata:
name: {{ "{{" }} .Workspace.Namespace {{ "}}" }}
labels:
meta.kappsul.io/user-ns: "yes"
meta.kappsul.io/user-email: "{{ "{{" }} .Workspace.UserEmail | replace "@" "_at_" {{ "}}" }}"
meta.kappsul.io/user-checksum: "{{ "{{" }} .Workspace.UserCheckSum {{ "}}" }}"
pod-security.kubernetes.io/enforce: baseline
Le même ConfigMap définit aussi le quota, le limit range, les bindings RBAC et la network policy. C'est le « une seule config » du titre : un unique objet géré dans Git décrit l'enveloppe de tous les tenants.
L'opérateur utilise aussi le template pour la découverte. Il ne code pas en dur une
liste de types de ressources à observer ; il scanne les ConfigMaps de template, extrait
l'apiVersion et le kind de chaque document, et enregistre un informer dynamique pour
les GVR résultants. L'ensemble des kinds observés est dérivé au démarrage, donc ajouter un
nouveau kind au template nécessite un redémarrage du controller avant que son informer ne
soit enregistré.
Appliquer : server-side apply, dans l'ordre des dépendances
Le rendu produit une map de documents YAML. L'opérateur les parse en objets unstructured, les trie par kind — Namespace d'abord, puis quota, limit range, service account, roles, role bindings, ConfigMaps, secrets et network policies — et applique chacun avec server-side apply.
labels["app.kubernetes.io/managed-by"] = "workspace-controller"
labels["workspace.kappsul.io/name"] = workspace.Name
labels["workspace.kappsul.io/uid"] = string(workspace.UID)
// ...and then:
options := metav1.PatchOptions{
FieldManager: "workspace-controller",
Force: boolPtr(true),
}
_, err := resourceClient.Patch(ctx, resource.GetName(),
types.ApplyPatchType, data, options)
Server-side apply est la bonne primitive ici pour trois raisons. C'est idempotent, donc un
retry est toujours sûr. Cela évite les courses read-modify-write. Et cela enregistre la
propriété des champs : l'API server sait que workspace-controller possède ces champs.
Le flag Force fait gagner l'opérateur quand quelqu'un d'autre a touché un champ qu'il
possède, ce qui est exactement ce dont le self-heal a besoin.
L'applier ajoute trois labels et une annotation à chaque ressource. Les labels identifient
le workspace propriétaire ; l'annotation stocke un hash du spec et du data rendus. Ce
hash est utile pour le suivi et le debug, mais ce n'est pas lui qui pilote la détection de
drift. Un hash peut vous dire que quelque chose a changé. Il ne peut pas vous dire qui
l'a changé.
Self-heal : qui a écrit ce champ ?
C'est le premier comportement dont nous avions besoin dans la boîte à outils GitOps.
L'étudiant a admin dans son namespace. C'est intentionnel : il doit pouvoir déployer des
applications, créer des services, gérer ses propres ressources. Mais la même permission lui
permet de modifier le quota, le limit range, les bindings RBAC et la network policy. Ce sont
des invariants de la plateforme, pas des ressources de l'étudiant.
La question difficile est de distinguer l'édition d'un étudiant de l'écriture de l'opérateur. Une comparaison de hash vous dit que l'objet ne correspond plus à la dernière chose que vous avez écrite — mais votre propre reconciliation le change aussi, donc l'événement suivant ressemble exactement à du drift. Et réappliquer à chaque événement aggrave les choses : vos propres écritures déclenchent encore plus d'événements.
La réponse est managedFields. Chaque écriture enregistre un field manager. Le watcher de
drift regarde l'entrée la plus récente et pose une question simple : est-ce
workspace-controller ou quelqu'un d'autre ?
lastModifier := getLastModifier(newObj.GetManagedFields())
if lastModifier == "workspace-controller" {
// Our own reconciliation. Not drift.
return
}
// Someone else changed a resource we own.
setDriftAnnotation(workspaceName)
enqueueWorkspace(workspaceName)
Le reconciler voit l'annotation, force-applique l'état désiré, et retire l'annotation. Le changement de l'étudiant disparaît. Le cycle est intentionnel et idempotent.
Il y a une nuance importante ici. Le self-heal est un contrôle correctif, pas la frontière de sécurité. La frontière de sécurité, c'est le namespace, le RBAC et la NetworkPolicy : ils décident ce que l'étudiant peut atteindre. Le self-heal protège les invariants à l'intérieur du namespace du tenant, là où l'étudiant est légitimement admin. C'est la différence entre « vous êtes autorisé à modifier ceci » et « cette valeur n'est pas la vôtre ».
C'est aussi une heuristique, pas une preuve. Un acteur qui écrit avec un nom de manager
workspace-controller serait indiscernable de nous. Notre modèle de menace est un étudiant
avec kubectl, pas une identité de controller compromise.
Propagation : une config, tous les workspaces
C'est le second comportement dont nous avions besoin.
Changer le template est l'opération à plus fort levier du système. Nous voulons qu'elle soit rapide, visible et rate-limitée.
L'informer ConfigMap stocke le nouveau resourceVersion dans un cache en mémoire et liste
les workspaces depuis le cache de l'informer — pas depuis l'API server. Pour chaque
workspace qui utilise ce template, il ajoute un élément à la work queue. C'est bon marché.
La queue, pas le handler d'événement, est le buffer.
func (c *WorkspaceController) handleConfigMapChange(obj interface{}) {
cm := obj.(*corev1.ConfigMap)
c.templateVersionCache.Store(cm.Name, cm.ResourceVersion)
workspaces, _ := c.workspacesLister.
Workspaces(c.config.WorkspacesNamespace).
List(labels.Everything())
for _, ws := range workspaces {
templateName := ws.Spec.TemplateConfigMap
if templateName == "" {
templateName = c.config.DefaultTemplateConfigMap
}
if templateName == cm.Name {
c.enqueueWorkspace(ws) // one queue item; no API call here
}
}
}
Le reconciler compare ensuite status.lastTemplateVersion avec la version en cache. Si
elles diffèrent, il réconcilie et enregistre la nouvelle version. À 50 workspaces par
seconde, dix mille workspaces convergent en environ trois minutes.
C'est le comportement GitOps que nous voulions : une configuration dans Git, propagée à tous les tenants. Pas d'Application par tenant, pas de boucle de sync par workspace. L'opérateur est le moteur de fan-out.
La leçon n'est pas « fan-out plus vite ». C'est « fan-out dans une queue ». Une boucle qui appelle l'API server dix mille fois est une attaque par déni de service que vous avez écrite vous-même. Une boucle qui enqueue dix mille éléments et laisse un pool de workers rate-limité les drainer est un rollout.
Cycle de vie : créer et supprimer
La création et la suppression sont de la plomberie autour des deux comportements, mais elles demandent quand même du soin.
Création. L'opérateur ajoute un finalizer, génère un userCheckSum s'il manque, rend le
template, applique les ressources et marque le workspace Active. Le checksum et le
finalizer suivent un pattern « une étape par passe » : écrire, retourner, et laisser
l'événement de mise à jour ramener le workspace. La reconciliation est une séquence
d'observations, pas un seul appel de fonction.
Suppression. Il y a deux chemins. Les ressources retirées du template sont diffées
contre managedResources, ajoutées à status.pendingDeletions, et supprimées de manière
asynchrone à une cadence prudente de cinq suppressions par seconde avec vingt retries et un
backoff exponentiel. Le namespace lui-même est supprimé avec foreground propagation ; le
finalizer garde le CR Workspace jusqu'à ce que le namespace ait disparu.
Le Namespace est explicitement exclu du diff de template. Supprimer un namespace est le travail du chemin de suppression de workspace, pas un effet de bord du diff de template.
Protéger le control plane
Tout ce qui précède représente beaucoup d'écritures. Le design est façonné autant par ce que nous refusons de faire que par ce que nous faisons.
| Frontière | Réglage | Pourquoi |
|---|---|---|
| Resync informer | 30s | filet de sécurité pour les événements manqués |
| Queue de reconcile | 50 QPS, burst 300 | progression équitable pendant un rollout de template |
| Queue de suppression | 5 QPS, burst 10, 1 worker | une tempête de suppressions est pire qu'une suppression lente |
| Mises à jour de status | 50 QPS, batch toutes les 30s | les écritures etcd sont les plus coûteuses |
| Client Kubernetes | 50 QPS, burst 300 | protéger l'API server de nous-mêmes |
| Retries de suppression | 20, 5ms à 1000s | succès eventual sans hot loops |
L'opérateur tourne en un seul réplica, et c'est délibéré. Il n'implémente pas de leader
election. Faire tourner deux réplicas signifierait deux reconcilers écrivant le même
status, deux ensembles d'appels API en double, et une classe de conflits que le verrouillage
optimiste ne peut que masquer. À la place, nous utilisons un PodDisruptionBudget avec
maxUnavailable: 0 et une priority class élevée pour que la maintenance ne l'évince pas
sans y penser. Un redémarrage de pod coûte dix à trente secondes de travail de control
plane ; le resync et la queue rendent cela anecdotique.
Si vous avez besoin d'une vraie haute disponibilité, la réponse est le leader election avec
un Lease coordination.k8s.io, pas plus de réplicas derrière un Service. Nous n'en avons
pas eu besoin jusqu'ici. L'opérateur n'est pas sur le chemin temps réel, et le travail est
idempotent.
La facture
Ce design n'est pas gratuit. Voici ce que nous payons.
- Le self-heal est correctif, pas préventif. Un étudiant peut toujours faire le changement ; l'opérateur l'annule. Si vous devez empêcher l'écriture, utilisez le RBAC et les admission policies. Le self-heal est le filet de sécurité pour les ressources que l'étudiant est autorisé à toucher.
- Le template est un blast radius partagé. Un mauvais changement de template atteint tous les workspaces à cinquante par seconde. C'est aussi une ligne dans Git, ce qui le fait paraître inoffensif. Traitez un changement de template comme un rollout de production : stagez-le, regardez les premiers workspaces, et ayez un rollback prêt.
- Deux couches de template sont puissantes et délicates. L'échappement Helm est laid, et une paire d'accolades manquante échoue au rendu, pas à l'écriture. L'alternative — des manifests bruts intégrés à l'image de l'opérateur — perd la frontière GitOps. Nous avons choisi la flexibilité et accepté la syntaxe.
- La détection de drift fait confiance à
managedFields. C'est un très bon signal, mais c'est un signal, pas un système d'autorisation. Un acteur qui peut écrire avec le nom de notre field manager peut l'éviter. - Vous possédez l'opérateur. C'est le compromis de la portabilité. Vous ne dépendez plus d'ArgoCD dans le cluster, mais vous maintenez désormais le controller, son CRD et ses modes de défaillance.
- Il n'y a pas d'audit trail Git par tenant. Le status du CR est l'état, pas un commit par workspace. Si vous avez besoin d'une trace de chaque changement de tenant, il faut l'ajouter.
À retenir
- Commencez par le modèle d'isolation. Un workspace, c'est un namespace plus un quota, un limit range, du RBAC, une network policy et de la pod security. L'opérateur existe pour rendre cette enveloppe cohérente.
- Gardez le runtime portable. Ne faites pas d'un outil externe une dépendance runtime pour une opération produit centrale. GitOps pour la livraison, un opérateur pour le runtime.
- Ne prenez que les comportements GitOps dont vous avez besoin. Le self-heal et la propagation suffisaient. Vous n'avez pas besoin d'un moteur de sync complet pour les obtenir.
- Utilisez server-side apply. Des écritures idempotentes, pas de courses read-modify-write, et une propriété des champs qui a du sens.
- Détectez le drift par qui, pas par quoi.
managedFieldsvous dit si le changement vient de vous ou de quelqu'un d'autre ; un hash ne le peut pas. - Fan-out dans une queue, pas dans des appels API. La queue est le buffer qui transforme un gros changement de template en rollout.
- Séparez la frontière de sécurité du contrôle correctif. Le RBAC et la NetworkPolicy décident ce qu'un étudiant peut atteindre. Le self-heal protège les invariants à l'intérieur de son namespace.