flexway
FRENParler à un expert

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.

GuideExploitationDepuis la version 1.0.0

Markdown

Sur cette page

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

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 :

    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 :

    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 :

    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

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

Attention

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

Étapes suivantes