💡 [REQUEST] - Migration des plugins vers une approche déclarative #2087

Description

La création des ressources par les plugins du Console repose sur une logique impérative : chaque plugin orchestre lui-même les appels HTTP au service externe (GitLab, Keycloak, Nexus, Harbor, Vault, SonarQube, ArgoCD). L'état n'est pas déclaré mais reconstruit à chaque réconciliation par une suite de lectures et de créations manuelles.

Cette approche présente trois défaillances observées :

1. Latence — les créateurs enchaînent des allers-retours API redondants (vérification d'existence, puis création, puis relecture) pour chaque ressource, sur chaque synchronisation, même quand rien n'a changé.
2. Cohérence — sous réconciliation concurrente (cron + événement project.upsert), deux passes peuvent créer la même ressource ; le perdant reçoit un 409 (ou un has already been taken) et fait échouer la synchronisation entière. Six de ces failles ont été constatées (issues liées ci-dessous).
3. Non-généralisable — chaque plugin réimplémente le même squelette de tolérance aux conflits, de retry et de gestion d'état, sans mécanisme commun de réconciliation.

L'objectif est de migrer cette logique vers le moteur Alchemy.run afin d'adopter une approche déclarative. Cela permettra de déléguer la gestion de l'état et de l'idempotence au moteur de réconciliation, garantissant ainsi que les ressources sont créées ou mises à jour de manière optimale et fiable, quel que soit l'état de départ.

Contexte et étapes préalables

La migration déclarative ne peut être menée que sur une base saine. Les problèmes d'idempotence signalés ci-dessous doivent d'abord être résolus selon la convention de la couche client : chaque créateur exposé par un service client suit le motif create-first upsert (ensure*) — on tente la création, sur un 409/conflit on relit la ressource une seule fois puis on réconcilie (mise à jour si l'état diffère, retour de l'existant sinon). Cette convention supprime les allers-retours redondants et stabilise l'état des ressources, condition requise avant le passage au moteur de réconciliation.

La couche interface fournisseur / service externe définie dans #2427 fixe le contrat que le moteur déclaratif consommera ; la présente issue consomme l'état exposé par cette interface.

PRs liées

No response

Issues liées

• 🐛 [BUG] - Réconciliation SonarQube non idempotente : les variables CI GitLab échouent en 'already been taken' #2616 Réconciliation SonarQube non idempotente : variables CI GitLab en already been taken
• 🐛 [BUG] - Réconciliation Keycloak non idempotente : course 409 sur la création du groupe racine #2618 Réconciliation Keycloak non idempotente : course 409 sur la création du groupe racine
• 🐛 [BUG] - Réconciliation Nexus non idempotente : 7 chemins de création sans tolérance 409 #2619 Réconciliation Nexus non idempotente : 7 chemins de création sans tolérance 409
• 🐛 [BUG] - Réconciliation Registry non idempotente : 4 chemins de création sans tolérance 409 #2620 Réconciliation Registry non idempotente : 4 chemins de création sans tolérance 409
• 🐛 [BUG] - gitlab-client : createGroupRepo et commit concurrents sans tolérance au conflit (Observability + ArgoCD) #2621 gitlab-client : createGroupRepo et commit concurrents sans tolérance au conflit
• 🐛 [BUG] - ArgoCD : un secret-id Vault AppRole est généré à chaque synchronisation #2622 ArgoCD : un secret-id Vault AppRole est généré à chaque synchronisation
• 💡 [REQUEST] - Abstraction plugins : interface fournisseur vs service externe #2427 Abstraction plugins : interface fournisseur vs service externe (complémentaire)

Exemples simples

No response

Spécifications techniques

Alchemy.run est un moteur d'infrastructure décrite en code (type IaC) en TypeScript sur Effect, adoptant une approche déclarative (cycle de vie : plan → reconcile → delete). Le modèle pertinent pour les plugins :

• Provider — une ressource est gérée par un provider qui implémente reconcile, delete, diff, read pour un type de ressource.
• Reconcile convergent — une seule fonction reconcile(news, output, olds, bindings) amène l'état réel au désiré, quel que soit le point de départ (greenfield, mise à jour, adoption). Forme attendue : observe → ensure → sync → return.
• Observe — lecture de l'état réel (getX/describeX) ; nom physique déterministe dérivé de stack/stage/id logique, ce qui permet à une retry de retrouver la ressource déjà créée.
• Ensure — créer si absente (en tolérant les erreurs de type AlreadyExists comme des courses), puis pour chaque aspect mutable différer l'état observé contre le désiré et n'appliquer que le delta.
• Idempotence — chaque étape est indépendamment idempotente ; reconcile et delete sont sûrs à rejouer (suppression d'une ressource déjà absente = succès).
• Adoption / récupération d'état — read retrouve une ressource créée lors d'un déploiement précédent dont l'état a été perdu, ou adopte une infrastructure préexistante.

Traduction pour les plugins du Console (keycloak, nexus, registry, gitlab, vault, sonarqube, argocd) :

• Chaque créateur impératif des services clients est exprimé comme un descripteur de ressource Alchemy dont le provider encapsule l'appel HTTP au service externe.
• Le moteur planifie (create / update / replace / delete / no-op) et pilote la réconciliation ; les allers-retours de type GET→CREATE→refetch disparaissent.
• La convention ensure* actuelle de la couche client devient l'implémentation du corps observe → ensure → sync du provider ; le nom physique déterministe remplace la lecture préalable redondante.
• Migration unitaire plugin par plugin, le moteur de réconciliation ne prenant en charge que les créateurs déjà idempotents.

Définition du fini

• Chaque problème d'idempotence listé dans les Issues liées est résolu selon la convention ensure*.
• La couche interface fournisseur (issue 💡 [REQUEST] - Abstraction plugins : interface fournisseur vs service externe #2427) définit le contrat consommé par le moteur déclaratif.
• Un plugin pilote (keycloak ou registry) est migré vers un provider Alchemy.run complet (plan + reconcile + delete), avec tests de non-régression.
• Les créateurs idempotents restants sont migrés unitairement vers des descripteurs déclaratifs.
• La logique impérative des créateurs est remplacée par des descripteurs déclaratifs traités par Alchemy.run.
• Les tests liés à cette migration ont été ajoutés.
• La documentation liée à cette migration a été ajoutée (cf. https://github.com/cloud-pi-native/documentation).
• La communication avec les autres équipes impliquées par cette fonctionnalité a été faite.