Dans beaucoup d'organisations, quelle que soit la passerelle (webMethods, Kong, Apigee, Azure API Management, MuleSoft ou autre), la promotion d'une API de la recette vers la production ressemble encore à ceci : un export depuis la console, un fichier transmis par ticket, un import manuel par une autre équipe, puis quelques clics pour ajuster les paramètres d'environnement et activer l'API. Ça marche, jusqu'au jour où personne ne sait plus dire quelle version tourne où, ni pourquoi la production diffère de la recette.

Cet article décrit l'architecture de chaîne que nous mettons en place pour remplacer ce circuit par un pipeline versionné. Notre terrain de preuve est webMethods API Gateway, mais l'architecture ne dépend pas de l'éditeur. Les outils sont volontairement classiques, ceux qu'on trouve déjà dans la plupart des DSI : GitLab pour le code et la revue, Jenkins pour l'orchestration, Ansible pour l'exécution sur les environnements. Le sujet n'est pas l'outil, mais la discipline qui l'entoure.

Le principe : Git décide, le pipeline exécute, la relecture prouve

Trois règles structurent toute la chaîne :

  1. Git est la seule source de vérité. Ce qui n'est pas dans Git n'existe pas. Aucune modification manuelle en console sur les environnements cibles, sauf procédure d'urgence tracée.
  2. Le pipeline est le seul chemin vers un environnement. Pas d'import manuel « juste pour cette fois ».
  3. Chaque déploiement se termine par une vérification de l'état réel. Un déploiement est réussi quand on a relu l'environnement et constaté qu'il correspond à Git, pas quand la dernière commande a renvoyé 0.

Ce qu'on met dans Git

Un dépôt par projet d'API (ou par domaine fonctionnel, selon la taille du patrimoine) contient :

  • la définition de l'API : spécification OpenAPI ou WSDL, et métadonnées webMethods utiles ;
  • une description lisible des policies : authentification, routage, limites de trafic, transformations. On ne versionne pas des identifiants techniques, qui changent d'un environnement à l'autre ;
  • les valeurs par environnement : endpoints de backend, alias, paramètres. Aucun secret : les secrets sont référencés par leur nom et lus à l'exécution depuis un coffre-fort (HashiCorp Vault, par exemple) ;
  • le numéro de version visé par environnement : c'est ce fichier qu'on modifie pour promouvoir.

Avec cette organisation, une promotion devient une merge request : on change la version visée pour l'environnement suivant, un pair relit, on fusionne.

Le rôle de chaque outil

GitLab : la revue et la traçabilité

GitLab porte les dépôts, les merge requests et les règles de protection de branches. C'est là que s'applique le « quatre yeux » : aucune modification d'un environnement de production sans relecture et approbation d'une seconde personne. L'historique Git répond naturellement à la question « qui a changé quoi, quand, et qui l'a validé ».

Selon les contextes, GitLab CI peut aussi porter les étapes de validation statique (lint de la spécification, contrôle de la structure des fichiers), au plus près du développeur.

Jenkins : l'orchestration

Jenkins enchaîne les étapes du pipeline et porte les gates. Il est souvent déjà connecté aux outils ITSM et aux annuaires de l'entreprise, ce qui en fait un bon chef d'orchestre pour les environnements réglementés. Un Jenkinsfile versionné dans le dépôt décrit :

  • les étapes et leur ordre ;
  • les environnements autorisés pour chaque branche ;
  • les points d'approbation : validation manuelle, contrôle d'un numéro de changement ITSM avant la production ;
  • l'identité utilisée : chaque exécution est rattachée à un utilisateur nommé, pas à un compte technique partagé.

Ansible : l'exécution idempotente

Ansible exécute les opérations sur API Gateway via son API REST d'administration : créer ou mettre à jour l'API, appliquer les policies, positionner les alias, activer. Son intérêt principal est l'idempotence : rejouer un playbook sur un environnement déjà conforme ne doit rien changer. C'est aussi ce qui rend le retour arrière simple : redéployer la version précédente, c'est rejouer le même playbook avec l'ancienne version.

L'API d'administration a ses particularités (réponses enveloppées, alias encodés, codes 200 qui ne garantissent rien). Nous les avons détaillées dans webMethods 10.15 : les pièges de l'API REST d'administration. La couche Ansible doit les absorber, pas les ignorer.

Les étapes du pipeline

Voici l'enchaînement type que nous mettons en place, à adapter au contexte :

  1. Validation statique : la spécification est valide, les fichiers d'environnement sont complets, aucune valeur sensible n'apparaît en clair.
  2. Contrôle de conformité : les règles de gouvernance sont vérifiées avant le déploiement (authentification obligatoire, conventions de nommage, policies minimales). Une API non conforme ne part pas : le pipeline refuse, il ne se contente pas de signaler.
  3. Résolution par environnement : les identifiants techniques sont résolus sur l'environnement cible, les secrets sont lus depuis le coffre-fort.
  4. Déploiement : Ansible applique la configuration. Pour une nouvelle version d'une API en service, la nouvelle version est déployée à côté de l'ancienne plutôt qu'à sa place.
  5. Relecture et comparaison : l'état réel de l'environnement est relu, normalisé et comparé à l'état attendu. Le moindre écart fait échouer le pipeline.
  6. Tests de fumée : quelques appels réels sur l'API déployée, avec les vraies règles d'authentification.
  7. Bascule et retrait : le trafic passe sur la nouvelle version ; l'ancienne n'est retirée qu'une fois la nouvelle vérifiée.
  8. Trace : le pipeline publie un rapport (version, environnement, auteur, approbateur, résultat de chaque contrôle) rattaché au changement.

La durée d'une promotion avec cette chaîne dépend du contexte et se mesure une fois le pipeline en place.

Le retour arrière en une commande

Un retour arrière qu'on n'a jamais testé n'existe pas. Dans cette chaîne, revenir en arrière consiste à remettre la version précédente dans le fichier de l'environnement, ou à rejouer le pipeline sur le tag précédent. Comme tout est idempotent et vérifié par relecture, le retour arrière passe par exactement le même chemin qu'un déploiement normal, avec les mêmes contrôles.

Nous recommandons de le jouer volontairement en recette avant la mise en service de la chaîne, puis régulièrement. C'est un scénario de test à part entière, au même titre que le déploiement nominal et le refus d'une API non conforme.

Les erreurs qu'on voit le plus souvent

  • Versionner l'export binaire comme source de vérité. L'archive est un format de transport, pas un format de revue. Personne ne relit un diff binaire.
  • Garder un compte technique partagé dans la CI. On perd la traçabilité nominative, et la rotation du mot de passe devient un projet en soi.
  • Faire confiance au code retour. Sans relecture de l'état final, un pipeline vert ne prouve rien.
  • Laisser la console ouverte en production. Une seule modification manuelle suffit à faire diverger l'environnement de Git. Le pipeline doit au minimum détecter cette dérive.
  • Commencer par la production. La chaîne se rode d'abord entre deux environnements hors production, puis s'étend.

Ce qui vaut pour toute passerelle

Seule la couche d'exécution est propre à webMethods : les playbooks qui parlent à son API d'administration. Tout le reste (Git comme source de vérité, merge request pour promouvoir, gates avant la production, relecture de l'état réel, retour arrière par le même chemin) se transpose tel quel à une autre passerelle ou plateforme d'intégration, et même à un parc qui en mélange plusieurs. C'est d'ailleurs ce qui rend un futur changement de passerelle moins risqué : les contrats et la chaîne restent, seul l'adaptateur change.

Par où commencer

Inutile de tout migrer d'un coup. Une démarche qui fonctionne, quelle que soit la plateforme :

  1. choisir une API représentative, ni triviale ni critique ;
  2. décrire son état actuel dans Git, à partir de l'existant ;
  3. construire le pipeline entre deux environnements hors production, avec relecture et retour arrière testé ;
  4. ajouter les gates (quatre yeux, changement ITSM) avant d'ouvrir la production ;
  5. étendre API par API, en mesurant le temps gagné et les écarts détectés.

À côté du conseil, CAB Ingénierie édite STOA, iPaaS souverain, plateforme d'API et d'intégration.

Parlons de votre projet

Vous partez d'imports manuels, ou votre chaîne de déploiement d'API actuelle ne vous inspire plus confiance ? Décrivez-nous votre contexte en quelques lignes : cab-ingenierie.com · contact@cab-ingenierie.com