# Reprendre une passerelle existante

> 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…

Guide - Depuis la version 1.2.0 - Flexway v1.6.3 - https://flexway.io/docs/operations-import/

> Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la capacité côté produit : [guide produit](https://flexway.io/docs/product-overview/) ; l'appeler : [guide développeur](https://flexway.io/docs/developer-overview/).

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`.

```bash
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 :

```bash
krakend check -d
```

*Disponible depuis `1.2.0`.*