Aller au contenu principal

Mise à jour

Mettre à jour un déploiement Avatar installé avec Helm consiste en un seul helm upgrade avec le même fichier de valeurs que celui de l'installation. Ce guide décrit la procédure sûre, ainsi que le seul point où Kubernetes diffère du chemin Docker d'une manière qu'il faut connaître avant de commencer.

La reprise passe par une réinstallation, pas par un retour arrière

helm rollback n'est pas testé sur ce chart. Prévoyez la reprise autour d'une réinstallation de la version précédente depuis une sauvegarde de base de données — voir Retour à la version précédente.

Prérequis​

Avant de commencer la mise à jour, assurez-vous de disposer de :

  • un accès kubectl et helm au cluster et au namespace de la release
  • le fichier de valeurs utilisé à l'installation, à jour de toute modification ultérieure
  • la version cible du chart et les tags d'images correspondants, fournis par Octopize
  • une connectivité réseau permettant de récupérer les nouvelles images (ou des images déjà recopiées pour les déploiements en environnement isolé) :
    • flux sortant sur le port 443 vers quay.io pour les images Avatar et l'artefact du chart
    • flux sortant sur le port 443 vers docker.io pour les images de support
    • flux sortant sur le port 443 vers ghcr.io pour les images Authentik
  • une marge d'ordonnancement suffisante pour la mise à jour progressive des déploiements web et Dask

Liste de contrôle avant mise à jour​

Tous les points doivent être vérifiés avant de continuer.

  • Version actuelle du chart et tags d'images documentés (helm -n avatar list)
  • Notes de version de la version cible consultées
  • Sauvegarde complète de la base PostgreSQL effectuée
  • Fichier de valeurs sauvegardé, et sa différence avec la release déployée relue (helm -n avatar get values avatar)
  • Fenêtre de maintenance planifiée et communiquée aux utilisateurs
  • Plan de reprise consulté et compris (voir Retour à la version précédente)

Vérifier la version actuelle​

helm -n avatar list
kubectl -n avatar get deploy -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.template.spec.containers[0].image}{"\n"}{end}'

Sauvegarder la base de données​

Prenez un instantané, ou un pg_dump sur database.host. Sauvegardez à la fois la base Avatar (database.name) et celle d'Authentik (authentik.authentik.postgresql.name) — restaurer l'une sans l'autre laisse les connexions cassées.

Si vous utilisez le SeaweedFS du chart, prenez également un instantané de ses PersistentVolumes.

Définir le mot de passe d'administration SeaweedFS​

Les versions du chart postérieures à 0.0.97 exigent un mot de passe d'administration SeaweedFS. Sans lui, le chart ne se rend pas. Avant la mise à jour, ajoutez storage.seaweedfsAdminPassword au fichier de secrets générés que vous conservez, par exemple avatar-secrets.yaml :

storage:
  seaweedfsAdminPassword: "<sortie de : openssl rand -hex 32>"

Pour lire le mot de passe depuis votre propre Secret, voir SeaweedFS.

Passer au chart 0.1.0 par le chart 0.0.102​

Le chart 0.1.0 exécute Authentik 2026.8, qui ne démarre que sur une base de données ayant déjà exécuté Authentik 2026.5. Authentik met à jour sa base de données une ligne de version à la fois, et ne peut pas revenir en arrière.

  • Depuis le chart 0.0.101 ou antérieur, passez d'abord au chart 0.0.102, qui exécute Authentik 2026.5. Attendez qu'Authentik soit prêt :

    kubectl -n avatar rollout status deploy/avatar-authentik-server

    Passez ensuite au chart 0.1.0, avec la même procédure.

  • Une nouvelle installation peut installer directement le chart 0.1.0.

  • Si vous sautez le chart 0.0.102, le serveur Authentik s'arrête au démarrage avec Major version skips are not allowed, avant de modifier la base de données. Passez au chart 0.0.102, laissez Authentik démarrer, puis passez de nouveau au chart 0.1.0.

  • Sauvegardez la base de données d'Authentik avant chacune des deux mises à jour.

Le chart 0.1.0 donne aussi à Authentik son URL de base, AUTHENTIK_WEB__BASE_URL, à partir de ingress.authentikHost ou de ingress.host. Authentik exige une URL de base à partir de 2026.11.

Redémarrer Authentik après la version qui ajoute sso.trustedProxyCidrs​

La version du chart qui ajoute sso.trustedProxyCidrs donne à Authentik les réseaux dont il accepte X-Forwarded-Proto et X-Forwarded-For. Ses notes de version la signalent. Authentik ne lit cette valeur qu'au démarrage, et helm upgrade ne le redémarre pas. Après être passé à cette version, et après chaque modification de sso.trustedProxyCidrs, redémarrez le serveur Authentik :

kubectl -n avatar rollout restart deploy/avatar-authentik-server
kubectl -n avatar rollout status deploy/avatar-authentik-server

Tant qu'il n'a pas redémarré, un serveur Authentik sur un réseau de pods hors de la valeur par défaut d'Authentik, par exemple 100.64.0.0/10 sur Scaleway Kapsule, prend chaque requête pour du HTTP simple, et la connexion revient à son premier écran. Voir La connexion revient à son premier écran.

Dérouler la mise à jour​

Étape 1 : mettre à jour les tags d'images dans le fichier de valeurs​

Trois valeurs évoluent ensemble à chaque changement de version :

api:
  image:
    tag: "<nouvelle-version-api>"

web:
  image:
    tag: "<nouvelle-version-web>"

dask:
  scheduler:
    image:
      tag: "<nouvelle-version-api>" # doit être égale à api.image.tag
  worker:
    image:
      tag: "<nouvelle-version-api>" # doit être égale à api.image.tag

Si vous utilisez le connecteur de bases de données, son image a sa propre ligne de versions : connector.image.tag ne suit pas api.image.tag. Augmentez-le quand les notes de version vous le demandent.

Étape 2 : prévisualiser le changement​

Rendre le nouveau chart avec votre fichier de valeurs met au jour une valeur manquante ou contradictoire avant que quoi que ce soit ne change dans le cluster :

helm upgrade avatar oci://quay.io/octopize/helm/services-api/avatar \
  --version <nouvelle-version> \
  --namespace avatar \
  --values my-values.yaml \
  --dry-run

Étape 3 : mettre à jour​

helm upgrade avatar oci://quay.io/octopize/helm/services-api/avatar \
  --version <nouvelle-version> \
  --namespace avatar \
  --values my-values.yaml

Deux choses se produisent automatiquement au déploiement des nouveaux pods :

  • Les migrations de base de données, exécutées par l'init container de l'API. Un échec se manifeste par un pod de l'API qui reste en Init, l'ancien pod continuant de servir le trafic.
  • Le Job d'amorçage Authentik est réexécuté. Il ne fait rien lorsque la base existe déjà.

Étape 4 : suivre le déploiement​

kubectl -n avatar get pods -w
kubectl -n avatar rollout status deploy/avatar-api
kubectl -n avatar logs deploy/avatar-api -c init-avatar-api

Étape 5 : vérifier le déploiement​

Déroulez les vérifications de Vérification et dépannage — au minimum le contrôle de santé de l'API, le test du flux de connexion et une avatarisation d'essai.

Liste de contrôle après mise à jour​

  • Tous les pods en Running, aucun en boucle de redémarrage
  • Job avatar-authentik-db-init-<nouvelle-version-du-chart> en Complete
  • Serveur Authentik redémarré, si la version ajoute sso.trustedProxyCidrs ou si vous l'avez modifié
  • Le point de contrôle de santé de l'API répond OK avec la bonne version
  • La connexion utilisateur réussit via Authentik
  • Un traitement d'avatarisation d'essai se termine correctement
  • Si le connecteur de bases de données est activé, son pod est en Running et Tester réussit sur une connexion de démonstration
  • Le stockage objet est accessible, sans erreur SSE-S3
  • La génération de rapports PDF fonctionne
  • L'envoi d'emails fonctionne

Garder l'API à un seul réplica​

Laissez api.replicaCount à 1 pendant la mise à jour, et en général. Plus d'un pod d'API n'est pas pris en charge actuellement.

Retour à la version précédente​

Prévoyez la reprise comme une réinstallation de la version précédente :

  1. Restaurez les bases PostgreSQL depuis la sauvegarde prise avant la mise à jour. Les migrations ne sont pas réversibles : une base migrée vers l'avant ne fonctionnera pas avec l'ancienne image de l'API.
  2. Relancez helm upgrade avec la version précédente du chart et les tags d'images précédents, depuis le fichier de valeurs sauvegardé.
  3. Vérifiez avec les contrôles de Vérification et dépannage.

Avant tout cela, collectez les informations de diagnostic afin que le problème puisse être analysé par la suite.

attention

Si vous êtes sur un PostgreSQL managé où la restauration en place est impossible, restaurez vers une nouvelle base et repointez database.host / database.name plutôt que de mettre à jour par-dessus une base déjà migrée vers l'avant.

Bonnes pratiques​

  • Testez les mises à jour sur un cluster de préproduction en premier
  • Mettez à jour pendant les périodes de faible utilisation
  • Conservez le fichier de valeurs sous gestion de version, afin que l'écart entre deux releases soit relisible
  • Conservez la sortie de la mise à jour et les journaux de l'init container pour le dépannage

Obtenir de l'aide​

Si vous rencontrez des difficultés pendant la mise à jour :

  1. Consultez les journaux : d'abord l'init container de l'API, puis le Job d'amorçage Authentik
  2. Vérifiez la configuration : helm -n avatar get values avatar face à votre fichier de valeurs
  3. Collectez les diagnostics : suivez la procédure de collecte de diagnostics
  4. Contactez le support : adressez-vous au support Octopize avec les messages d'erreur précis et les fichiers de diagnostic

Pour une assistance de reprise en urgence, contactez immédiatement le support Octopize avec vos fichiers de sauvegarde à disposition.