gemaal

# gemaal **gemaal** (mot néerlandais désignant une station de pompage) est un outil d'orchestration conçu pour maintenir la santé des clusters de test Kubernetes partagés. Tout comme une station de pompage physique maintient un polder au sec en évacuant continuellement l'eau, gemaal maintient un cluster de test utilisable en détectant et nettoyant automatiquement les installations éphémères obsolètes. Il garantit que les locataires de test temporaires ne s'accumulent pas et ne dégradent pas l'environnement pour les autres utilisateurs. ## Philosophie fondamentale * **Nettoyage non bloquant** : gemaal n'installe jamais rien. Les clients exécutent eux-mêmes `helm upgrade --install`. Le service se contente de désinstaller et de balayer les ressources qui ne sont plus utilisées. Si le service tombe en panne, le nettoyage est retardé, mais il ne bloque jamais la boucle d'installation des clients. * **Mode fantôme** : Par défaut, le service s'exécute en mode fantôme (`dryRun: true`). Il planifie, signale et journalise les actions de suppression, mais ne les exécute pas tant qu'il n'est pas explicitement activé. Cela assure la sécurité lors du déploiement et permet aux opérateurs de vérifier la logique de nettoyage avant qu'elle n'impacte les ressources en production. * **Observateur déclenché par niveau** : Le service fonctionne selon une boucle de type cron qui redérive l'état du cluster à partir de zéro à chaque cycle. Il utilise `helm list` par namespace pour voir exactement ce que voit un opérateur, en regroupant les releases en paires d'anneaux (application + infrastructure) et en appliquant des règles de garbage collection basées sur les étiquettes de durée de vie (TTL). ## Trois facettes 1. **`gemaal` (Service)** : Un observateur in-cluster responsable de : * La gestion des TTL sur les locataires de test. * Le démontage conscient des paires d'anneaux (garantissant que l'infrastructure est démontée après les applications). * Le balayage des artefacts orphelins (par exemple, les sous-arbres S3). * L'exposition de six RPC ConnectRPC : Plan, ListTenants, Checkout, Extend, Sweep, Resolve. * La fourniture d'une console web pour surveiller les locataires, les âges, les niveaux et l'historique des balayages. 2. **`gemaalctl` (CLI)** : Une interface en ligne de commande pour : * Vérifier les chaînes de preuves d'identité et les locataires résolus (`whoami`). * Gérer les installations/désinstallations Helm côté client avec les étiquettes de registre apposées. * Interagir avec le service via ConnectRPC pour planifier, extraire ou prolonger la durée de vie des locataires. 3. **Bibliothèque Go** : Importée par les harnais de test pour : * Résoudre les locataires permanents. * Encadrer les phases de la suite de tests (build, deploy, setup, teardown). * Gérer la résolution d'identité et le chargement de la configuration. ## Fonctionnalités clés * **Isolation et identité des locataires** : Utilise des étiquettes de niveau (par exemple, `tenancy.truvity.io/tier`) pour identifier les namespaces accessibles. Ignore les namespaces système comme `gemaal-system`. L'identité est résolue via une chaîne impliquant l'e-mail, les groupes kubectl et les sessions AWS SSO. * **Règles de garbage collection** : * TTL uniforme basé sur la dernière activité, configurable par locataire ou par niveau. * Priorité `keep-until` pour des besoins de rétention spécifiques. * Démontage ordonné par anneaux (application avant infrastructure). * Collecte des artefacts orphelins après une période de grâce. * **Authentification et autorisation** : * Les mutations s'authentifient via TokenReview auprès de l'API Kubernetes (pour les charges de travail) ou via OIDC JWT (pour les humains). * Checkout/Extend nécessitent des droits de propriétaire ou d'administrateur. * Les opérations de balayage sont réservées aux administrateurs. * **Console web** : Une application monopage Vite/React/MUI intégrée dans le binaire, fournissant une pile de console de flotte pour visualiser l'état des locataires et l'historique des balayages. ## Intégration du harnais de test Les projets peuvent intégrer gemaal dans leurs tests d'intégration Go en utilisant la bibliothèque `pkg/harness`. Le harnais résout un locataire permanent une fois dans `TestMain`, permettant aux tests de s'exécuter dans un namespace dédié. Le service gère le nettoyage via des étiquettes apposées sur les releases Helm, de sorte que la suite de tests elle-même ne crée et ne supprime rien directement (sauf dans les hooks de démontage intermédiaires). Des variables d'environnement comme `GEMAAL_TEST_SKIP_BUILD`, `GEMAAL_TEST_SKIP_DEPLOY` et `GEMAAL_TEST_KEEP` permettent un contrôle fin du cycle de vie des tests dans les pipelines CI/CD. ## Accès AWS Le service prend en charge les chaînes d'informations d'identification AWS standard, notamment EKS Pod Identity et IRSA (IAM Roles for Service Accounts). Il interagit avec AWS Systems Manager (SSM) pour le stockage des artefacts et nécessite les autorisations appropriées pour STS et les points de terminaison d'identité de pod. ## Développement * **Chaîne d'outils** : Utilise [devbox](https://www.jetify.com/devbox/) et [just](https://just.systems/) pour la gestion des tâches. * **Commandes** : * `just check` : Exécute les vérifications de build, test, lint et vulnérabilité. * `just generate` : Régénère le code à partir des définitions Protobuf. * `just run` : Exécute le squelette du service avec une configuration d'exemple. ## Statut Le projet est en développement précoce (phase G4). La conception, la surface proto, la bibliothèque client, la CLI et le service sont en place. Le service n'a pas encore connu de déploiement en production ; les déploiements initiaux se feront en mode fantôme. L'API client est réellement utilisée mais peut changer entre les versions mineures 0.x. ## Licence Licence MIT