Upgrade

Deux binaires à upgrader : le manager (stack docker-compose) et les edges (un par host). Tous deux suivent le même flux conceptuel : stage les nouveaux artefacts, swap atomiquement, retombe sur la version précédente automatiquement si la nouvelle ne se lève pas saine.

TL;DR

Manager :

VER=v0.7.160
gh release download "$VER" --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'
sha256sum -c "ongrid-${VER}-linux-amd64.tar.xz.sha256"
tar xf "ongrid-${VER}-linux-amd64.tar.xz"
cd     "ongrid-${VER}-linux-amd64"
sudo ./upgrade.sh

Edges (tous, en parallèle, depuis l'UI) :

• Edges → Upgrade all — le manager pousse MethodFetchPackage vers chaque edge connecté, chacun télécharge le bundle staged depuis https://<manager>/edge/, le stage, redémarre, swap, tourne. Les échecs auto-rollback au boot suivant.

Ou pour un seul edge depuis le shell :

sudo systemctl restart ongrid-edge
# The ExecStartPre runs apply-pending-upgrade.sh which picks up any
# staged bundle and applies it before the new agent starts.

Le reste de cette page explique comment tout ça marche vraiment, pour que vous puissiez debug quand ça ne marche pas.

Upgrade manager : upgrade.sh

upgrade.sh vit dans chaque tarball de release et est destiné à être exécuté à l'intérieur du tarball plus récent fraîchement extrait. Il suppose qu'il y a déjà une install à ${ONGRID_INSTALL_DIR:-/opt/ongrid}/.

Dans l'ordre :

1. Preflight. Vérifie docker + compose v2, trouve le .env existant. Bail s'il n'y en a pas.
2. Détermine version ancienne vs nouvelle depuis le .env existant et le fichier VERSION du nouveau tarball. Logge les deux — utile pour les tickets de support.
3. docker compose down pour relâcher les volumes de données pour toute étape de migration.
4. Ré-affirme l'ownership des dirs de données sous ${ONGRID_DATA_DIR}/ (mysql, prom, loki, tempo, grafana, embeddings, qdrant). Les uids d'image n'ont pas changé depuis longtemps mais c'est le seul défaut sûr — ré-affirmer est idempotent.
5. Re-stage les configs depuis le nouveau tarball dans /opt/ongrid/ : docker-compose.yml, prometheus.yml, prometheus-rules.yml, loki-config.yaml, tempo-config.yaml, grafana/, searxng/, nginx.conf, frontier.yaml, les nouveaux artefacts edge/, le nouveau fichier VERSION. .env est préservé — upgrade.sh n'écrase jamais l'env édité par l'opérateur.
6. Charge les nouvelles images docker (ongrid.tar, ongrid-web.tar, frontier.tar si présent).
7. Bump ONGRID_VERSION= dans .env pour que le prochain compose-up prenne le nouveau tag d'image.
8. docker compose up -d avec le nouvel env.
9. Sonde /healthz pendant 60s.
10. Bannière avec version ancienne → nouvelle, l'URL Web, des commandes utiles pour la prochaine étape.

Si quoi que ce soit échoue avant l'étape 8, l'opérateur peut ré-exécuter après avoir corrigé le problème sous-jacent — upgrade.sh est idempotent. Si l'étape 9 échoue (/healthz ne renvoie jamais 200), les logs du manager depuis docker compose logs ongrid vous diront ce qui est cassé.

Pour zéro downtime, exécutez un setup blue/green avec deux hosts manager devant un load balancer ; l'install OSS mono-host est brève indisponibilité pendant l'upgrade (~30-60s).

D'où viennent les artefacts d'upgrade : make package

C'est le chemin opérateur — comment vous construisez le tarball si vous construisez depuis les sources au lieu de tirer une release. Depuis un checkout de ongridio/ongrid :

make package

L'ordre importe ; voici ce que make package fait :

1. fetch-promtail — télécharge promtail-<os>-<arch>.zip depuis la release Grafana upstream, extrait dans bin/<os>-<arch>/promtail. Caché.
2. fetch-otelcol — pareil pour otelcol-contrib.
3. fetch-node-exporter — pareil pour node_exporter.
4. fetch-process-exporter — pareil pour process_exporter.
5. build-edge-all — cross-compile ongrid-edge pour linux/amd64, linux/arm64, darwin/amd64, darwin/arm64.
6. docker-build — build l'image ongrid:<version>.
7. docker-build-broker — build singchia/frontier:<ver> depuis $FRONTIER_SRC (ou skip si déjà dans le store d'images local).
8. docker-build-web — build ongrid-web:<version> (SPA frontend + nginx).
9. build-edge-bundle — assemble edge-bundle-linux-amd64-<ver>.tar.gz depuis les binaires en vrac.
10. dist/package.sh — stage tout dans dist/stage/ongrid-<version>-linux-amd64/, docker save les trois images, tar.xz le tout, calcule le sidecar sha256, dépose le tout sous dist/out/.

La sortie :

dist/out/ongrid-v0.7.160-linux-amd64.tar.xz
dist/out/ongrid-v0.7.160-linux-amd64.tar.xz.sha256

C'est l'artefact que vous scp vers l'host prod et nourrissez à ./upgrade.sh.

Modèle RAG offline

Le modèle d'embedding BGE n'est pas une dépendance de package — il est lent à fetcher sur les réseaux CN, donc il reste une étape ponctuelle. Exécutez make fetch-embedding-model une fois avant make package si vous voulez que ONGRID_EMBEDDING_PROVIDER=local fonctionne out of the box sur une restauration.

Upgrade edge : ADR-024 stage-then-swap

Le chemin utilisateur pour upgrader un edge est « cliquer sur Upgrade dans l'UI » ou systemctl restart ongrid-edge après qu'un bundle ait été staged. Ce qui se passe vraiment, de haut en bas :

1. Le manager déclenche, l'edge fetche

Sur « Upgrade all edges » (ou un seul edge) :

• Le manager lit dist/out/edge-bundle-<arch>-<ver>.tar.gz.sha256 depuis /opt/ongrid/edge/ (placé là par install.sh / upgrade.sh).
• Le manager envoie MethodFetchPackage(url=https://<manager>/edge/<bundle>, sha256=<sha>, version=<ver>) sur le tunnel aux edges cibles.
• nginx sert les octets du bundle depuis le même dir /edge/.

2. L'edge stage

L'edge récepteur :

• Télécharge le bundle dans /tmp/.
• Vérifie le sha256 contre le manifeste que le manager a envoyé.
• Untar dans /var/lib/ongrid-edge/.upgrade/incoming/.
• Valide chaque ligne <sha> <mode> <src> <dest> de MANIFEST.txt (sha matche, src existe).
• Écrit un marqueur « ready ».
• Exit propre. systemd redémarre l'unit par Restart=always.

3. L'ExecStartPre de systemd exécute le swap

L'unit est livrée avec :

ExecStartPre=-+/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh
ExecStart=/usr/local/bin/ongrid-edge

Le préfixe + exécute le hook comme root malgré User=ongrid-edge ; le - laisse un script manquant/qui échoue exit 0 sans bloquer l'unit pour que le binaire pre-upgrade démarre toujours.

apply-pending-upgrade.sh fait, dans l'ordre :

1. Mode 1 : auto-rollback si un upgrade précédent a tourné mais n'a jamais écrit healthy_marker matchant last_upgrade_ver. Restaure chaque <dest>.previous sur <dest>. Nettoie le dir de staging.
2. Mode 2 : apply de bundle — pour chaque ligne MANIFEST.txt :
   • re-vérifie le sha256,
   • cp -p $dest $dest.previous (snapshot pour rollback),
   • cp $src $dest.new sur le même filesystem pour que le rename final soit POSIX-atomique,
   • chmod $mode $dest.new,
   • mv -f $dest.new $dest.
3. Mode 3 : apply legacy mono-fichier pour la rétro-compat avec les edges qui n'ont pas encore été bundle-upgradés (juste le binaire agent, pas de manifeste).
4. Enregistre last_upgrade_at et last_upgrade_ver pour le check de santé au prochain boot.

Puis ExecStart=/usr/local/bin/ongrid-edge exécute le binaire fraîchement swappé.

4. Le nouvel agent reporte sain (ou pas)

Le nouvel agent, à la connexion réussie :

• Écrit /var/lib/ongrid-edge/.upgrade/healthy_marker avec la version qu'il exécute.
• Reporte register sur le tunnel avec sa nouvelle version.

Si ce fichier existe et matche last_upgrade_ver au prochain boot, apply-pending-upgrade.sh déclare succès, élague chaque .previous pour libérer du disque, nettoie le dir de staging.

Si non (agent crashé, ne peut pas joindre le manager, autre chose), le prochain boot déclenche le auto-rollback : chaque .previous est restauré, le dir de staging est wipé, l'edge exécute la précédente version fonctionnelle à nouveau. L'opérateur le voit dans l'UI (l'edge continue à reporter une « vieille » version après un upgrade déclenché — un indice que quelque chose ne va pas avec le nouveau bundle).

Invariants du bundle

Chaque fichier que l'edge swap est dans le bundle ; chaque fichier du bundle est un binaire ou script auto-contenu. C'est non négociable :

• Le binaire agent (ongrid-edge)
• Les binaires de plugin (promtail, otelcol-contrib, node_exporter, process_exporter)
• Le script hook (apply-pending-upgrade.sh)

Les configs de plugin (promtail.yaml, otelcol.yaml) ne sont pas dans le bundle — elles vivent dans /etc/ongrid-edge/ et sont livrées sur le tunnel comme config live. Comme ça un upgrade d'agent n'écrase pas une config que l'opérateur a éditée à la main.

Ne re-cuissez pas le bundle dans l'image docker

Si vous buildez depuis les sources, le bundle est construit par dist/build-edge-bundle.sh sur l'host au moment du package, pas dans le conteneur. ADR-032 impose ceci — le re-cuir dans l'image double-emballe ~120 Mo d'octets incompressibles et casse la chaîne sha.

Où vivent les rollbacks

/usr/local/bin/ongrid-edge              # current
/usr/local/bin/ongrid-edge.previous     # last known good

/usr/local/lib/ongrid-edge/promtail
/usr/local/lib/ongrid-edge/promtail.previous

...etc.

/var/lib/ongrid-edge/.upgrade/
  last_upgrade_at                       # ISO timestamp
  last_upgrade_ver                      # version string
  healthy_marker                        # written by the new agent

Une séquence de boot après un upgrade déclenché ressemble à :

boot 1 (pre-upgrade):
  apply-pending-upgrade.sh sees nothing staged; exit 0
  ongrid-edge v0.7.159 runs

(manager pushes bundle, edge stages it, edge exits clean)

boot 2 (apply):
  apply-pending-upgrade.sh
    mode 1: no healthy_marker yet, but no last_upgrade_at either → skip
    mode 2: applies bundle. /usr/local/bin/ongrid-edge.previous = v0.7.159
                            /usr/local/bin/ongrid-edge        = v0.7.160
            writes last_upgrade_at, last_upgrade_ver=v0.7.160
            clears healthy_marker
  ongrid-edge v0.7.160 runs
  v0.7.160 connects, writes healthy_marker=v0.7.160

(reboot, e.g. host updates)

boot 3 (settle):
  apply-pending-upgrade.sh
    mode 1: last_upgrade_ver=v0.7.160, healthy_marker=v0.7.160 → success
            prunes all .previous files
            clears last_upgrade_at, last_upgrade_ver
  ongrid-edge v0.7.160 runs

Un scénario d'échec :

boot 2 (apply):
  apply-pending-upgrade.sh: applies bundle as above
  ongrid-edge v0.7.160 crashes immediately (e.g. config drift)
  systemd restarts repeatedly per Restart=always

boot 3 (rollback):
  apply-pending-upgrade.sh
    mode 1: last_upgrade_ver=v0.7.160, healthy_marker missing
            → roll back: restore .previous over each dest
              (ongrid-edge.previous → ongrid-edge, etc.)
            : > last_upgrade_at, rm -rf incoming/
  ongrid-edge v0.7.159 runs again (working)

Downgrader

Downgrader le manager : extraire le tarball plus ancien, exécuter ./upgrade.sh dedans. Tant qu'aucune migration de schéma DB n'a eu lieu dans les releases intermédiaires, ça marche. Vérifiez les notes de release pour tout appel « breaking schema change » avant de downgrader.

Downgrader les edges : déclenchez un « upgrade » depuis l'UI vers la version de bundle plus ancienne. La logique du manager se moque de quelle direction la version va.

Et après

• Référence / env — noms de variables d'env dont les défauts changent entre les releases.
• Installation air-gappée — comment mirror les artefacts vers un webserver privé pour que apply-pending-upgrade.sh puisse encore tirer les bundles quand le manager lui-même n'est pas sur internet.