Zum Hauptinhalt springen

Upgrade

Container-Modus (2026.05+, empfohlen)​

# 자동 (META-INF/VERSION.JSON 이 가리키는 빌드)
sudo bash /opt/kopens/install/upgrade.sh

# 특정 불변 태그 (YYYY.MM-YYYYMMDD-HHMM). 움직이는 태그는 거부합니다
sudo bash /opt/kopens/install/upgrade.sh --to 2026.11-20261103-1006

# 진행 중인 현재 업그레이드만 롤백 (trial · rollback_failed 상태에서만)
sudo bash /opt/kopens/install/upgrade.sh --rollback

# 사전 점검만 (0 최신, 10 새 빌드 있음)
sudo bash /opt/kopens/install/upgrade.sh --check
Kein Downgrade auf ältere Versionen

--rollback macht lediglich ein laufendes Upgrade rückgängig; ein Downgrade von einem bereits bestätigten Build auf einen älteren Build ist nicht möglich. Eine Zuweisung eines älteren Tags über --to wird ebenfalls abgelehnt (Exit-Code 3).

Air-Gap-Box

Boxen, die keine Verbindung zur Registry haben, werden über eine einzelne Image-Datei aktualisiert — siehe unten Air-Gap-Upgrade.

Ablauf (automatisch):

  1. Vorab-Inspektion — Es wird geprüft, ob es sich um einen unveränderlichen Tag handelt, ob der Build neuer als der aktuelle ist sowie ob Signatur-Tools, Backup-Tools und genügend Festplattenplatz vorhanden sind. Wenn eine Bedingung nicht erfüllt ist, wird der Vorgang gestoppt, ohne Änderungen vorzunehmen.
  2. Download — docker pull <태그>
  3. Validierung — Überprüfung der cosign-Signatur und des build_date des Images. Wenn die Signatur nicht validiert werden kann, wird der Vorgang abgebrochen. Der Vorgang wird fortgesetzt, indem das System durch das im validierten Image enthaltene Upgrade-Tool ersetzt wird.
  4. Snapshot — /data1/pp-backups/pe-backup-pre-upgrade-<ts>.tar.zst Backup, flankierend ein CQL-Dump (siehe unten <아카이브>.cql/) und Cassandra-Snapshot. Dies ist obligatorisch und kann nicht übersprungen werden. Schlägt ein Schritt fehl, wird der Vorgang gestoppt, ohne Änderungen vorzunehmen (snapshot_failed, Exit-Code 4).
  5. Umschaltung — /etc/kopens/version.env wird durch den validierten Digest ersetzt und neu gestartet.
  6. Testbetrieb — Es wird gewartet, bis /api/health?verdict=upgrade&expect_build=<빌드일> den Wert 200 zurückgibt. Standardmäßig 300 Sekunden (HEALTH_TIMEOUT), bei laufender Migration bis zu 2400 Sekunden (MIGRATION_TIMEOUT).
  7. Bestätigung oder automatischer Rollback — Bei Erfolg committed. Bei Fehlschlag wird Cassandra auf den Snapshot zurückgesetzt und es erfolgt eine Rückkehr zum vorherigen Image (rolled_back). Schlägt auch diese Rückkehr fehl, erfolgt rollback_failed.

Bei einem Stromausfall während des Testbetriebs bewertet kopens-upgrade-resume.service beim Booten erneut über --resume. Wenn das System mehr als 3-mal ohne Bestätigung bootet (OTA_MAX_TRIAL_BOOTS), erfolgt ein Rollback ohne weitere Bewertung.

Status des Fortschritts: cat /etc/kopens/upgrade.status — JSON. Die Zustände sind idle · downloading · verified · snapshot · switching · trial · committed · rolling_back · rolled_back · rollback_failed.

Exit-Codes: 0 Bestätigt oder bereits aktuell · 10 --check Neuer Build verfügbar · 3 Anfrage für Downgrade auf alten Build abgelehnt · 4 Keine Änderungen vorgenommen · 5 Download oder Validierung fehlgeschlagen · 6 Rollback abgeschlossen · 7 Rollback fehlgeschlagen · 75 Ein anderes Upgrade wird ausgeführt.

UI / API Trigger: POST /api/v1/system/upgrade schreibt in /etc/kopens/upgrade.request, was vom Host über kopens-upgrade.path erkannt wird, woraufhin upgrade.sh --from-trigger ausgeführt wird.

Detaillierter Leitfaden: Abschnitt „OTA-Upgrade“ im Dokument Betrieb des Container-Modus.

CQL-Dump vor dem Upgrade​

Zusätzlich zum tar-Archiv und Cassandra-Snapshot wird als Vorab-Backup eine engine-unabhängige Kopie erstellt — das Schema als CQL-Text (schema.cql) und die Zeilen pro Tabelle als CSV. Dies ist notwendig, da bei Upgrades mit Engine-Wechsel nicht garantiert ist, dass Engine-Dateien vom neuen Engine-Typ gelesen werden können.

  • Speicherort: <아카이브에서 .tar.zst 를 뗀 이름>.cql/ neben dem Archiv. Es werden nur die letzten 3 Versionen zusammen mit dem Archiv aufbewahrt.
  • Zeilen von Zeitreihe- und Monitoring-Tabellen werden nicht erfasst (nur das Schema bleibt erhalten, die Tabellen bleiben leer). Die Ausschlussliste findet sich in BACKUP_CQL_EXCLUDE_TABLES.
  • Wenn der Dump nicht erstellt werden kann, gilt das Backup als fehlgeschlagen und das Upgrade wird nicht gestartet. Wenn ein Upgrade ohne Dump erzwungen werden soll, muss BACKUP_CQL=0 angegeben werden — dies hinterlässt eine Warnung, und das Archiv kann nur auf derselben Engine wiederhergestellt werden.

Die Wiederherstellung ist beschrieben in pe restore --cql unter Backup und Wiederherstellung.

Air-Gap-Upgrade​

Ohne Registry und Internet wird mit einer Image-Datei dasselbe Upgrade-Verfahren durchlaufen (Vorab-Inspektion → Snapshot → Umschaltung → Testbetrieb → Bestätigung oder Rollback).

sudo pe upgrade --bundle /media/usb/plantpulse-edge-2026.12.tar.zst
# 박스에 cosign 3 이 없으면 바이너리를 같이 넘깁니다
sudo pe upgrade --bundle <파일> --cosign /media/usb/cosign-linux-amd64
  • Drei Dateien müssen am selben Ort vorliegen: <파일>, <파일>.sha256, <파일>.sha256.sig. Es wird entweder der Inhalt aus images/ eines Air-Gap-Bundles oder die Datei aus plantpulse-edge-<YYYY.MM>.tar.zst der Distributionsquelle verwendet.
  • Zuerst erfolgt die Signaturprüfung. Die Signatur von .sha256 wird offline mit /etc/kopens/cosign.pub der Box validiert. Nur wenn der sha256-Wert der Datei mit dem signierten Wert übereinstimmt, erfolgt docker load. Wenn die Signaturdatei fehlt, die Signatur nicht stimmt oder der sha256-Wert abweicht, wird das Image nicht geladen (unabhängig von COSIGN_REQUIRE).
  • cosign: Wenn cosign 3 nicht auf der Box vorhanden ist, wird --cosign <파일> oder cosign-linux-<arch> neben der Datei bzw. tools/cosign-linux-amd64 aus dem Bundle installiert. Abweichungen von der Prüfsumme der Fixversion (3.1.3) führen zur Ablehnung.
  • Es werden nur neuere Builds installiert. Bei identischem Build erfolgt up_to_date, bei älterem Build refused_downgrade.
  • --bundle kann nicht zusammen mit --to · --check verwendet werden (Exit-Code 2). Die Schaltfläche «SW-Upgrade» im Web nutzt ausschließlich Registry-Pfade.
Erstes Air-Gap-Upgrade bei Boxen vor 2026.11-20261103-1006

Die in Versionen ohne diese Funktion installierte upgrade.sh kennt --bundle nicht. Das erste Mal muss die Ausführung direkt über das im Bundle enthaltene neue Skript erfolgen.

sudo bash <번들>/repo/bin/upgrade.sh --bundle <번들>/images/<파일>

Wenn nur die Image-Datei vorliegt, müssen zusätzlich die Speicher-Tarballs (plantpulse-edge-docker.tar.gz und .sig) mitgebracht, entpackt und auf die gleiche Weise ausgeführt werden. Danach ist dies über pe upgrade --bundle möglich.

Rollback-Nachweis vor Release​

Bevor ein neues Release an die Boxen vor Ort gemeldet wird, wird an einer Staging-Box geprüft, ob ein absichtlich fehlschlagendes Upgrade tatsächlich rückgängig gemacht wird. Es wird ein Upgrade mit einem Test-Image durchgeführt, das eine Migration fehlschlagen lässt, um einen automatischen Rollback auszulösen. Anschließend wird geprüft, ob der vorherige Build, das Schema und die Daten unverändert sind. Diese Prüfung ist ein obligatorischer Schritt in der Release-Kette; erst nach Bestehen wird VERSION.JSON veröffentlicht und die Box erkennt dieses Release als «aktuell». Szenarien für Health-Fehler und Boot-Schleifen werden gemeinsam in dem Release ausgeführt, in dem das Upgrade-Tool geändert wurde.

2. Vorab-Inspektion​

Vor Beginn des Upgrades:

# 1. 외부 망이 충분히 빠른지 — 회선이 느리면 download 만 수십 분
$PE_HOME/bin/network-speed-test.sh

# 2. 디스크 여유 (산출물 크기의 2–3배는 있어야)
df -h /opt /data1

# 3. 살아있는 백업이 있는지
ls -lt /data1/pp-backup | head -3

3. Validierung der Upgrade-Ergebnisse​

$PE_HOME/bin/ps.sh                              # 모든 컴포넌트 살아있는지
curl -s http://127.0.0.1/api/v1/edge | jq      # 버전/엣지 ID 새 값 확인
curl -s http://127.0.0.1/ui/opcua/tree | jq '.data.tree | length'  # 사이트/태그 정상
$PE_HOME/bin/log-viewer.sh                      # 30초 정도 봐서 SEVERE 없는지
# (Ctrl+C)

Zusätzlich ist an der externen SCADA / Sparkplug-Empfängerseite zu prüfen, ob die Daten korrekt ankommen.

4. Häufige Fehlerquellen​

SymptomUrsache / Lösung
Stoppt bei download install.shExternes Netzwerk / product.kopens.io prüfen. Direkte Prüfung via curl -v http://product.kopens.io/...
Neue Artefakte nach extracting beschädigtAbbruch während des Downloads. Festplattenplatz prüfen + erneuter Versuch
Nur einige Komponenten nach Upgrade aktivSchrittweises Scheitern in start.sh — Über log-viewer.sh prüfen, an welcher Stelle der Stopp erfolgte
cosign 3 or later is not installed and could not be installed (Exit-Code 4)Box kann github.com nicht erreichen und cosign nicht beziehen. Keine Änderungen vorgenommen. Netzwerk öffnen oder cosign 3.x vorinstallieren und erneut versuchen
Rollback auf ältere Version nach UpgradeWiederherstellung aus Backup → Backup / Wiederherstellung

5. firmware.sh — OS-Paketaktualisierung​

$PE_HOME/bin/firmware.sh

Intern:

dnf update -y
dnf clean all

Wird für die Anwendung von quartalsweisen Sicherheits-Patches verwendet. Wenn Kernel-Updates enthalten sind, ist ein Reboot erforderlich.

$PE_HOME/bin/firmware.sh
needs-restarting -r              # 새 커널이 깔렸는지 확인
# 결과가 "Reboot is required" 이면
$PE_HOME/bin/stop.sh
$PE_HOME/bin/reboot.sh

Weiterführende Informationen​

  • Integrierte Upgrade-Szenarien (Sicherheitsverfahren) → Betriebsszenarien — Deployment neuer Versionen
  • Artefakte werden durch die GitLab-Release-Kette (edge:libs → edge:deploy-dev → edge:image → edge:sign → edge:staging → verify:staging-evidence → verify:ota-rollback:image → verify:ota-rollback → edge:version) erstellt.
  • Installation / Deployment (für Entwickler): Installation / Deployment