Migrer de gateway sans couper le trafic

Toute migration de gateway d'API commence par la même phrase en comité : « on bascule pendant la fenêtre de maintenance de Pâques ». Et elle finit à peu près toujours de la même manière : la fenêtre est trop courte, on annule au bout de trois heures, on repart en arrière, et le projet est reporté d'un an.

Le problème n'est pas la fenêtre. Le problème est de croire qu'une migration de gateway est un événement, alors que c'est un régime transitoire qu'il faut savoir tenir plusieurs mois.

Pourquoi le big bang ne marche pas ici

Une gateway n'est pas une base de données. Elle ne contient pas d'état à transférer : elle contient des règles, et ces règles ont été écrites sur plusieurs années par des gens qui sont partis, en réaction à des incidents que personne n'a documentés.

C'est ce qui rend la migration atypique :

• Vous ne pouvez pas tester ce que vous ne savez pas qui existe. La configuration contient des cas particuliers dont plus personne ne connaît la raison, une transformation d'en-tête pour un consommateur unique, une exception de quota, un routage vers un backend de secours.
• Les consommateurs ne sont pas tous joignables. Sur une plateforme un peu ancienne, une fraction des appelants correspond à des applications dont plus personne n'assume la propriété.
• Le retour arrière est facile techniquement et impossible politiquement. Après trois reculs, la migration est morte, quel que soit le mérite du plan.

La méthode qui fonctionne consiste donc à faire coexister les deux gateways, à déplacer le trafic par tranches, et à garder la capacité de revenir en arrière par consommateur, pas globalement.

La méthode : six phases

1. Inventorier ce qui passe réellement

Avant toute chose : la liste des routes réellement appelées sur 90 jours glissants, avec leur volumétrie, leur taux d'erreur, et l'identité de l'appelant.

Ce n'est pas la liste des API déclarées. C'est presque toujours une liste plus courte, et elle contient trois ou quatre entrées que personne n'attendait.

Ce qui n'a pas été appelé depuis 90 jours ne se migre pas : on l'annonce en dépréciation et on le laisse sur l'ancienne gateway jusqu'à extinction. C'est le seul moment du projet où l'on peut réduire le périmètre sans négociation, et d'expérience c'est le quart au tiers des routes.

2. Reconstruire les règles, ne pas les traduire

La tentation est d'écrire un convertisseur automatique de l'ancienne configuration vers la nouvelle. C'est presque toujours une erreur : les modèles de policy ne se correspondent pas un pour un, et un convertisseur reproduit fidèlement les erreurs historiques.

La bonne approche est de reconstruire à partir de l'intention : pour chaque route, quelle est la règle métier ? Le résultat est plus court, compréhensible, et il exclut les cas particuliers devenus sans objet.

Concrètement : une feuille par route, trois colonnes, authentification attendue, limites et quotas, transformations. Si personne ne sait remplir une case, c'est une question à poser, pas une case à copier.

3. Faire tourner les deux gateways en parallèle, sans trafic réel

La nouvelle gateway est déployée, configurée, et reçoit une copie du trafic, soit par duplication (shadow traffic), soit en rejouant les journaux d'accès.

On ne compare pas les réponses fonctionnelles à ce stade : on compare les codes de retour et les latences. Un écart de code de retour révèle une règle manquante. Un écart de latence révèle un problème de dimensionnement ou de résolution DNS qu'il vaut mieux découvrir maintenant.

4. Basculer par consommateur, pas par route

C'est le point qui distingue une migration qui aboutit d'une migration qui s'enlise.

L'intuition pousse à migrer route par route : « on commence par les API les moins critiques ». Mais un incident sur une route touche alors tous ses consommateurs, y compris ceux qu'on n'avait pas prévenus.

L'ordre correct est l'inverse : on bascule un consommateur à la fois, sur toutes ses routes. On commence par un consommateur interne, coopératif, joignable, avec un volume significatif mais pas critique. En cas de problème, une seule équipe est touchée, elle est au courant, et le retour arrière ne concerne qu'elle.

La bascule elle-même se fait au niveau du DNS ou du load balancer, avec une répartition pondérée : 5 %, puis 25 %, puis 50 %, puis 100 %.

Le critère de franchissement s'écrit avant le premier palier, sinon il se négocie sous pression. Trois conditions suffisent : le taux d'erreurs 5xx ne dépasse pas celui de l'ancienne gateway sur la même période, la latence au centile 99 reste dans une marge annoncée, aucun écart de code de retour n'est apparu.

Le temps d'observation compte autant que les seuils. Un palier franchi un mardi à quinze heures n'a rien vu du batch de fin de mois : comptez au moins un cycle métier complet par palier, davantage sur le passage à 100 %.

Le retour arrière se prépare, il ne s'improvise pas. Un basculement DNS n'est pas réversible en une minute. Les résolveurs, et surtout les clients qui gardent une résolution en mémoire, continuent d'envoyer du trafic pendant la durée de vie de l'enregistrement. Abaissez-la à une minute plusieurs jours avant le premier palier, le temps que l'ancienne valeur expire partout.

Et quand la reprise doit être immédiate, ne passez pas par le DNS : la pondération au load balancer se change en quelques secondes, sans dépendre de personne. Annoncez le délai réel aux consommateurs concernés. C'est ce qui sépare un retour arrière d'un incident.

5. Tenir le régime transitoire

Pendant plusieurs mois, deux gateways sont en production. Il faut donc :

• Un tableau de bord unique qui agrège les deux, sinon personne ne sait où regarder pendant un incident.
• Une règle explicite sur l'endroit où se fait un changement pendant la transition. La réponse par défaut doit être « sur la nouvelle uniquement », avec une exception documentée.
• Une date de fin annoncée, sans quoi la transition devient permanente. C'est le scénario le plus fréquent : le dernier dixième de trafic reste sur l'ancienne plateforme pendant des années, avec deux plateformes à maintenir pour lui seul.

6. Éteindre, vraiment

L'ancienne gateway ne s'arrête pas : on la met d'abord en refus explicite (410 Gone avec un message qui nomme la nouvelle URL et un contact), pendant quatre à six semaines, avant de la débrancher.

Cette étape révèle les consommateurs fantômes, ceux qui n'apparaissaient dans aucun inventaire et qui se manifestent seulement quand ça casse.

Les cinq pièges

Le TLS et les certificats clients. C'est le premier poste d'incidents. Les consommateurs en mTLS ont épinglé quelque chose quelque part : une autorité, un certificat, parfois une adresse IP. Traitez-les comme un chantier séparé, en amont, et jamais dans le même palier de bascule que le reste.

Les adresses IP sortantes. Les backends et les partenaires filtrent souvent par IP. La nouvelle gateway sort par d'autres adresses. Cette liste doit être communiquée plusieurs semaines à l'avance, et vérifiée, pas annoncée.

Les différences de comportement par défaut. Deux gateways ne traitent pas de la même façon les en-têtes en double, la casse, les caractères encodés dans les chemins, les requêtes sans Host, ou la taille maximale d'un corps. Ces écarts ne se voient pas en recette et cassent en production sur un appelant exotique.

Le fournisseur d'identité. Si la validation des jetons change de mécanisme, cache de clés, tolérance d'horloge, audiences acceptées, vous découvrirez le problème sous charge, pas en test.

L'organisation. Deux gateways signifient deux astreintes, ou une astreinte qui doit connaître les deux. Ce point ne figure jamais dans le plan de migration et c'est celui qui fatigue l'équipe.

Ce que ça coûte vraiment

Le coût affiché d'une migration est celui de la reconstruction des règles. Elle n'en est qu'un quart. La répartition que nous constatons, en part de la charge totale :

La conséquence pratique tient dans la première ligne : le chemin critique n'est pas votre calendrier, c'est celui de vos consommateurs. Une migration se planifie donc à l'envers, à partir des fenêtres de recette des équipes qui devront basculer. Le nombre de consommateurs basculables par trimestre est la seule donnée qui prédise la date de fin.

Si vous préparez une migration et voulez un regard extérieur sur le plan avant de l'engager, c'est exactement ce que couvre l'audit flash.