Mettre à niveau la Navin Platform

Cette page met à niveau la Navin Platform vers une nouvelle version. Les migrations SQL vont uniquement vers l'avant et restent compatibles avec la version précédente (extension puis contraction) : les anciens pods continuent de fonctionner pendant que les nouveaux démarrent. Elle est réalisée par l'administrateur de la plateforme, dans une fenêtre de changement pour la production.

Avant de commencer

• Lisez les notes de la version cible (Nouveautés de la version 1.0, Notes de version 1.0.0) : plage de migrations, réglages modifiés, problèmes connus.
• Vérifiez que les contrats d'API restent compatibles : aucun changement cassant dans contracts/v1.
• Vérifiez que l'installation actuelle est saine (Vérifier) et qu'aucune migration n'est changed ou unknown (navin-platform status, python -m eai.migrate --status).

Paquets OS

1. Sauvegarder la base. La mise à niveau applique les nouvelles migrations au premier démarrage de l'API.

   sudo -u postgres pg_dump --format=custom --file=/var/backups/navin_platform-<date>.dump navin_platform

   Pour un serveur externe, lancez le même pg_dump avec le compte administrateur et PGSSLMODE=verify-full.

   Résultat attendu : pg_restore --list /var/backups/navin_platform-<date>.dump affiche la table des matières.

2. Installer le nouveau paquet. Une mise à niveau garde les réglages, les données et la base ; le venv est reconstruit depuis le wheelhouse du nouveau paquet et les services en cours sont redémarrés.

   sudo apt update && sudo apt install --only-upgrade navin-platform    # Ubuntu
   sudo dnf upgrade navin-platform                                       # famille RHEL
   sudo pacman -Syu                                                      # Arch Linux

   Avec l'archive hors ligne : sudo ./navin-install standalone depuis l'archive de la nouvelle version.

   Résultat attendu : navin-platform version affiche la nouvelle version.

   En cas d'échec : journalctl -u navin-platform-api -n 100 donne la raison pour laquelle l'API ne démarre pas.

3. Contrôler les migrations.

   sudo navin-platform-db check

   Résultat attendu : code de sortie 0. Le worker refuse de démarrer tant qu'une migration est en attente.

4. Comparer les réglages. /etc/navin-platform/platform.env.example est rafraîchi par la mise à niveau ; comparez-le avec votre platform.env, puis lancez sudo navin-platform check.

Kubernetes

1. Sauvegarder. Prenez une sauvegarde Velero à la demande avant une mise à niveau de production :

   velero backup create pre-upgrade-<version> --from-schedule eai-platform-daily

   CloudNativePG garde aussi une archive WAL continue dans s3://eai-backups/cnpg (restauration à un instant donné).

2. Publier les nouveaux tags d'images. La CI pousse les images signées dans Harbor et met à jour deploy/gitops/<env>/image-tags.yaml.

3. Synchroniser. dev et staging se synchronisent automatiquement. La production est manuelle, hors de la fenêtre de gel de l'AppProject (à partir du vendredi 18 h, pendant 62 h) :

   argocd app sync -l eai.io/environment=prod,eai.io/layer=apps
   argocd app wait -l eai.io/environment=prod,eai.io/layer=apps --health --timeout 1800

   Le hook PreSync / pre-upgrade lance python -m eai.migrate avant que les Deployments ne changent. Sans Argo CD : helm upgrade enterprise-ai deploy/helm/enterprise-ai -n enterprise-ai -f <fichiers de valeurs>.

4. Contrôler. /readyz, l'onglet de surveillance des services du Navin Manager, l'écran Métriques en direct du portail, GET /v1/audit/verify, les tests de fumée k6 de deploy/loadtest.

5. Opérateurs. Changez chart_versions dans deploy/terraform/modules/platform-bootstrap/variables.tf, puis tofu plan et tofu apply, un opérateur à la fois.

Revenir en arrière

Installation	Commande	Base
Kubernetes	argocd app rollback enterprise-ai-prod <revision>	Conservée quand les migrations sont additives ; sinon restauration CloudNativePG à un instant donné
Paquets OS	Installez la version précédente du paquet (apt install navin-platform=<version>, dnf downgrade navin-platform)	Restaurez le dump de l'étape 1 quand la nouvelle version a appliqué des migrations : migrate --status signale les versions plus récentes comme unknown

Site isolé

Construisez, vérifiez et signez le bundle côté connecté, puis vérifiez-le sur site et comparez le manifeste release/manifests/<version>.json avec celui de la version installée : voir Installation déconnectée.

Dépannage

Symptôme	Cause	Correction
migrate --check signale changed	Un fichier de migration publié a été modifié	Restaurez le fichier publié ; ne modifiez jamais une migration appliquée
migrate --status signale unknown	La base est plus récente que le code (retour arrière)	Réinstallez la version plus récente, ou restaurez la sauvegarde
Des pods de l'ancienne et de la nouvelle version tournent ensemble	Mise à jour progressive en cours	Normal : les migrations sont compatibles avec la version précédente