Aller au contenu principal

Workspaces Kubernetes multi-tenant : isolation, self-heal et une seule config

Comment nous avons construit un opérateur Workspace qui isole chaque étudiant dans son propre namespace, empêche les ressources de la plateforme de dériver, et propage un seul template géré dans Git à tous les tenants — sans exiger ArgoCD dans le cluster.

JV

Joël Vappiani

17 min

Partager sur X

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 :

CoucheCe qu'elle donne à l'étudiantCe qu'elle protège la plateforme de
NamespaceUn endroit privé pour déployerLes collisions de noms et l'accès inter-tenant accidentel
ResourceQuotaUn budget CPU, mémoire, stockage et pods prévisibleUn workspace qui affame le cluster
LimitRangeDes requests et limits par défaut pour les conteneursLes pods sans limits qui passent au travers
RBACadmin dans leur namespace, pour le propriétaire et les invitésLes étudiants qui agissent hors de leur workspace
NetworkPolicyDefault-deny avec ingress et egress explicitesLe trafic inter-namespace et l'egress inattendu
Pod Security Admissionbaseline en enforcement, restricted en audit/warnLes 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èreRéglagePourquoi
Resync informer30sfilet de sécurité pour les événements manqués
Queue de reconcile50 QPS, burst 300progression équitable pendant un rollout de template
Queue de suppression5 QPS, burst 10, 1 workerune tempête de suppressions est pire qu'une suppression lente
Mises à jour de status50 QPS, batch toutes les 30sles écritures etcd sont les plus coûteuses
Client Kubernetes50 QPS, burst 300protéger l'API server de nous-mêmes
Retries de suppression20, 5ms à 1000ssuccè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. managedFields vous 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.