# Mettre à jour

> Passer d'une version mineure à une autre : valider la configuration avec la nouvelle image avant de déployer, puis mettre à jour passerelle et console.

Guide - Depuis la version 1.0.0 - Flexway v1.7.1 - https://flexway.io/docs/operations-upgrade/

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

Depuis `1.0.0`, une version mineure (`1.x.0`) est **additive** : ce qui est écrit pour `1.0.0` se lit en
`1.x` sans édition, une clé nouvelle a un défaut qui reproduit le comportement précédent, et une fonctionnalité
ne se retire qu'après une dépréciation annoncée **deux** mineures à l'avance. Six surfaces sont tenues
par cette promesse : le schéma de `flexway.yaml`, les extensions `x-flexway-*`, le catalogue de
politiques, les noms et dimensions des métriques, les codes d'erreur RFC 9457 et le contrat
d'administration. Une version majeure (`2.0.0`) est la seule qui puisse les casser.

## Étapes

1. Lire les notes de version de **chaque** mineure entre la vôtre et la cible : nouveautés,
   dépréciations, corrections.

2. Valider la configuration en cours avec l'image de la **nouvelle** version, avant tout déploiement -
   le validateur est le chargeur du démarrage :

   ```bash
   docker run --rm -v "$PWD:/etc/flexway:ro" ghcr.io/flexwiz/flexway:<nouvelle-version> validate -v
   ```

3. Mettre à jour la passerelle. En Kubernetes, le chart porte la même version que l'image :

   ```bash
   helm upgrade orders oci://ghcr.io/flexwiz/charts/flexway --version <nouvelle-version> -f values.yaml
   ```

   Chaque réplique remplacée sort d'abord de la rotation (`/readyz` passe à `503`), puis draine ses
   requêtes en cours (`server.shutdown.drain`, 20 s par défaut). Hors Kubernetes : remplacer le binaire
   ou l'image, puis redémarrer - `SIGTERM` draine de même.

4. Mettre à jour la console, si elle est déployée - ses comptes sont gardés :

   ```bash
   helm upgrade console oci://ghcr.io/flexwiz/charts/flexway-console --version <nouvelle-version> -f console-values.yaml
   ```

5. Seulement ensuite, écrire dans la configuration les clés ou extensions apportées par la nouvelle
   version.

## Vérifier

```bash
curl -s http://localhost:9090/config | jq '.build'       # {"version":"v<nouvelle-version>","commit":"..."}
curl -s http://localhost:9090/readyz                     # {"status":"ready","operations":...}
```

Chaque réplique annonce la nouvelle version dans `build` ; le pied de la console affiche la version de
la console et celle de la passerelle.

## À savoir

| Le chargeur refuse | Pourquoi c'est utile pour une mise à jour |
| --- | --- |
| Une clé inconnue de `flexway.yaml` | Le décodage est strict : une clé apportée par une version plus récente est refusée par une plus ancienne - c'est ce que l'étape 2 détecte dans l'autre sens |
| `version` autre que `1` | La valeur est vérifiée, jamais supposée |
| Une extension `x-flexway-*` inconnue, pas encore servie, ou écrite là où elle n'est pas lue | Une extension prévue pour une version future est refusée avec la version qui l'apportera |

> [!WARNING]
> **Retour arrière** : `helm rollback`, ou l'image précédente. Si la configuration utilise déjà une clé
> ou une extension de la nouvelle version, l'ancienne la refuse : revenez d'abord à la configuration
> d'avant. Une configuration refusée au rechargement ne remplace jamais celle qui sert ; au démarrage,
> elle empêche de démarrer.

> [!NOTE]
> Les réglages lus au seul démarrage ([liste](https://flexway.io/docs/operations-live-config/)) s'appliquent naturellement :
> une nouvelle image est un redémarrage. Pendant la mise à jour progressive de la console, une réplique
> de l'ancienne version garde intactes les données qu'elle ne connaît pas ; un retour arrière les laisse
> en place, ignorées.

Les versions `0.x` ne promettaient rien : passer d'une `0.x` à `1.0.0` demande de relire la
configuration contre la [référence de la configuration](https://flexway.io/docs/operations-configuration-reference/).