Reprendre une passerelle existante

Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la capacité côté produit : guide produit ; l'appeler : guide développeur.

La configuration d'une passerelle existante se reprend une fois, hors ligne : Flexway n'en lit jamais au démarrage - deux sources de vérité finissent toujours par diverger. Le contrat reste la source : l'import le complète, il n'en invente rien.

Format d'entrée pris en charge : le fichier de configuration JSON de KrakenD (krakend.json), lu par la commande flexway import krakend.

flexway import krakend --config krakend.json --contract openapi.yaml --out ./import
# ou, depuis l'image publiée (le dossier de sortie appartient à l'utilisateur courant) :
docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/w" -w /w ghcr.io/flexwiz/flexway:<version> \
  import krakend --config krakend.json --contract openapi.yaml --out import

--out est un dossier vide ou absent : l'import n'écrase jamais. Il y écrit quatre fichiers, après les avoir passés au chargeur du démarrage - jamais une configuration qui refuserait de démarrer :

Fichier	Contenu
flexway.yaml	Amonts, délai global, émetteurs, politiques ; aucune opération listée
openapi.yaml (le nom du contrat lu)	Le contrat annoté : x-flexway-* et, au besoin, security ajoutés ; commentaires gardés, JSON resté JSON
contract.patch.json	Les mêmes ajouts en JSON Patch (RFC 6902), pour qui garde son contrat ailleurs
coverage.md	Chaque élément de la configuration importée classé repris, repris autrement (avec l'équivalent) ou sans équivalent (avec la raison), un total par catégorie ; les endpoints absents du contrat ; les opérations qu'aucun endpoint ne couvre

Code de sortie	Sens
0	Tout est repris
3	Repris, avec des éléments sans équivalent : lire coverage.md avant de servir
1	Refus, rien n'est écrit : fichier illisible, contrat invalide, résultat que le chargeur refuse (le message dit pourquoi)
2	Ligne de commande mal formée

Correspondance - le rapport est en anglais, comme le reste du produit :

Clé de la configuration importée	Flexway	Catégorie
endpoint + method	L'opération du contrat de même méthode et même gabarit, noms de paramètres mis à part ({id} = {orderId}) ; absente : listée, jamais inventée	repris
backend[0].host + url_pattern	upstreams.<hôte> (un par hôte distinct) + x-flexway-upstream ; une politique rewrite-path si le chemin diffère, paramètres renommés	repris, repris autrement
Plusieurs host	Le premier ; répartir est l'affaire de la plateforme (un Service, le maillage)	sans équivalent
Plusieurs backend (agrégation), sd: dns, {JWT.sub} dans url_pattern	Aucun amont donné : le chargeur refuse, code 1	sans équivalent
timeout (global, endpoint)	server.timeouts.total ; celui d'un endpoint qui diffère -> x-flexway-timeout	repris
input_headers, input_query_strings	Rien : fermé par défaut, le contrat déclare ; un nom qu'il ne déclare pas est signalé (un en-tête n'est plus relayé, un paramètre est refusé)	repris autrement, sans équivalent
auth/validator	auth.issuers (découverte depuis issuer, audience, alg, roles_key, scopes_key) ; security ajoutée à une opération qui n'en déclare pas, une alternative par rôle ; un contrat moins strict que la configuration importée est signalé, jamais modifié	repris autrement
qos/ratelimit/router	client_max_rate -> politique rate-limit, par appelant et opération ; max_rate (tous appelants) : sans équivalent	repris, sans équivalent
qos/circuit-breaker	upstreams.<nom>.circuit_breaker : failure_ratio: 1, min_requests: max_errors + 1, window, cooldown ; un par amont	repris autrement
output_encoding, encoding : no-op, json	Relais tel quel	repris autrement
allow	transform-body, project, on_missing: omit	repris autrement
deny, flatmap_filter del	redact, remove: true	repris autrement
mapping, group, target, is_collection, flatmap_filter move	-	sans équivalent
validation/json-schema	Le schéma du contrat valide le corps	repris autrement
modifier/lua-*, plugin/*	Aucun : greffon natif ou script refusé	sans équivalent
Toute autre clé	Signalée, avec l'équivalent à écrire à la main quand il existe (security/cors -> politique cors, qos/http-cache -> x-flexway-cache)	sans équivalent

Ensuite : relire coverage.md, recopier le contrat annoté là où vit le contrat, puis flexway validate. Une configuration flexible (gabarits Go) se rend d'abord avec l'outil de la passerelle d'origine ; c'est le fichier rendu qui s'importe :

krakend check -d

Disponible depuis 1.2.0.