アップグレード
コンテナモード (2026.05+, 推奨)
# 자동 (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
--rollback は進行中のアップグレードを差し戻すだけであり、既に確定したビルドから旧ビルドへ戻すことはありません。--to で旧タグを指定しても拒否されます(終了コード 3)。
レジストリに到達できないボックスは、イメージファイル一つでアップグレードします — 下記の 閉域網アップグレード。
実行順序 (自動):
- 事前点検 — 対象が不変タグであるか、現在のビルドより新しいか、署名ツール・バックアップツール・ディスク空き容量があるかを確認します。一つでも不整合があれば、何も変更せずに停止します。
- ダウンロード —
docker pull <태그> - 検証 — cosign 署名とイメージの build_date を確認します。署名を検証できない場合は進行しません。検証されたイメージに含まれるアップグレードツールで自身を置換して継続します。
- スナップショット —
/data1/pp-backups/pe-backup-pre-upgrade-<ts>.tar.zstバックアップ、およびその横の CQL ダンプ(<아카이브>.cql/, 下記)、Cassandra スナップショット。必須であり、スキップできません。一つでも失敗すれば何も変更せずに停止します(snapshot_failed, 終了コード 4)。 - 切り替え —
/etc/kopens/version.envを検証済みダイジェストに置き換えて再起動。 - 試運転 —
/api/health?verdict=upgrade&expect_build=<빌드일>が 200 を返すまで待機します。デフォルトは 300 秒(HEALTH_TIMEOUT)、マイグレーションが進行中の場合は最大 2400 秒(MIGRATION_TIMEOUT)。 - 確定または自動ロールバック — 通過すれば
committed。失敗すれば Cassandra をスナップショットに戻し、直前のイメージに戻ります(rolled_back)。その復帰にも失敗した場合はrollback_failed。
試運転中に電源が切れた場合、ブート時に kopens-upgrade-resume.service が --resume として再判定します。確定なしにブートが 3 回を超えると(OTA_MAX_TRIAL_BOOTS)、判定なしにロールバックします。
進行状態: cat /etc/kopens/upgrade.status — JSON。状態は idle · downloading · verified · snapshot · switching · trial · committed · rolling_back · rolled_back · rollback_failed です。
終了コード: 0 確定または既に最新 · 10 --check 新ビルドあり · 3 旧ビルドへ戻すリクエストを拒否 · 4 何も変更せず · 5 ダウンロードまたは検証失敗 · 6 ロールバック完了 · 7 ロールバック失敗 · 75 他のアップグレードが進行中。
UI / API トリガー: POST /api/v1/system/upgrade が /etc/kopens/upgrade.request を使用し、ホストの kopens-upgrade.path が検知して upgrade.sh --from-trigger を実行します。
詳細ガイド: コンテナモード運用 の「OTA アップグレード」節。
アップグレード前 CQL ダンプ
事前バックアップは、tar アーカイブと Cassandra スナップショット以外に、エンジンに依存しないコピーをさらに一つ作成します — スキーマは CQL テキスト(schema.cql)、行はテーブルごとに CSV。DB エンジンが変更されるアップグレードにおいて、エンジンファイルが新しいエンジンで読み込める保証がないためです。
- 位置: アーカイブ横の
<아카이브에서 .tar.zst 를 뗀 이름>.cql/。アーカイブと共に最新 3 つのみ保持されます。 - 時系列・モニタリング表の行は含めません(スキーマのみが残り、空の状態で戻ります)。除外リストは
BACKUP_CQL_EXCLUDE_TABLES。 - ダンプを作成できない場合はバックアップ失敗となり、アップグレードは開始しません。ダンプなしで更新する必要がある場合は
BACKUP_CQL=0を明記します — 警告が残り、そのアーカイブは同じエンジンでのみ復元されます。
復元は バックアップおよび復旧 の pe restore --cql。
閉域網アップグレード
レジストリ・インターネットなしに、イメージファイルで同じアップグレード手順(事前点検 → スナップショット → 切り替え → 試運転 → 確定またはロールバック)を辿ります。
sudo pe upgrade --bundle /media/usb/plantpulse-edge-2026.12.tar.zst
# 박스에 cosign 3 이 없으면 바이너리를 같이 넘깁니다
sudo pe upgrade --bundle <파일> --cosign /media/usb/cosign-linux-amd64
- 3つのファイルが同一場所になければなりません:
<파일>,<파일>.sha256,<파일>.sha256.sig。閉域網バンドルのimages/内にあるもの、または配信先のplantpulse-edge-<YYYY.MM>.tar.zstを使用します。 - 署名を先に検証します。 ボックスにある
/etc/kopens/cosign.pubで.sha256の署名をオフライン検証し、ファイルの sha256 が署名された値と一致する場合のみdocker loadします。署名ファイルがない、または署名が不一致、あるいは sha256 が異なる場合は イメージを読み込みません(COSIGN_REQUIREとは無関係)。 - cosign: ボックスに cosign 3 がない場合は
--cosign <파일>、またはファイル横のcosign-linux-<arch>· バンドルのtools/cosign-linux-amd64をインストールします。固定バージョン(3.1.3)のチェックサムと異なる場合は拒否します。 - より新しいビルドのみを上げます。同じビルドの場合は
up_to_date、旧ビルドの場合はrefused_downgrade。 --bundleは--to·--checkと併用できません(終了コード 2)。Web の「SW アップグレード」ボタンはレジストリパスのみを使用します。
この機能がないリリースにインストールされた upgrade.sh は --bundle を知りません。最初の一回は バンドルに含まれる新スクリプト で直接実行します。
sudo bash <번들>/repo/bin/upgrade.sh --bundle <번들>/images/<파일>
イメージファイルのみを持ってきた場合は、リポジトリ tarball(plantpulse-edge-docker.tar.gz および .sig)を併せて持参して展開し、同様に実行します。それ以降は pe upgrade --bundle となります。
リリース前ロールバック実証
新リリースは現場ボックスに通知される前に、ステージングボックスで 意図的に失敗させたアップグレードが実際に差し戻されるか を確認します。マイグレーションが失敗する試験イメージでアップグレードして自動ロールバックを発生させ、直前のビルド・スキーマ・データが保持されているか検査します。この検査はリリースの必須段階であり、通過して初めて VERSION.JSON が発行され、ボックスがそのリリースを「最新」として認識します。ヘルス失敗とブート繰り返しシナリオは、アップグレードツールが変更されたリリースで併せて実行します。
2. 事前点検
アップグレードを開始する前に:
# 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. アップグレード結果検証
$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)
外部 SCADA / Sparkplug 受信側でも正常に到着しているかを確認してください。
4. よくある落とし穴
| 症状 | 原因 / 解決策 |
|---|---|
download install.sh で停止 | 外部網 / product.kopens.io 点検。curl -v http://product.kopens.io/... で直接確認 |
extracting 後に新成果物が破損している | ダウンロード中の遮断。ディスク空き容量確保 ＋ 再試行 |
| アップグレード後、一部のコンポーネントのみ動作している | start.sh の段階的失敗 — log-viewer.sh でどこで停止したか確認 |
cosign 3 or later is not installed and could not be installed (終了コード 4) | ボックスが github.com に到達できず cosign を取得できない。何も変更されない。網を開放するか、cosign 3.x を事前にインストールして再試行 |
| アップグレード後 過去バージョンへロールバック | バックアップから復旧 → バックアップ / 復旧 |
5. firmware.sh — OS パッケージアップデート
$PE_HOME/bin/firmware.sh
内部的に:
dnf update -y
dnf clean all
四半期単位でセキュリティパッチを適用する際に使用。カーネルアップデートが含まれる場合は reboot が必要 です。
$PE_HOME/bin/firmware.sh
needs-restarting -r # 새 커널이 깔렸는지 확인
# 결과가 "Reboot is required" 이면
$PE_HOME/bin/stop.sh
$PE_HOME/bin/reboot.sh
さらに詳しく
- アップグレード統合シナリオ (安全な手順) → 運用シナリオ — 新バージョン配備
- 成果物は GitLab リリースチェーン(
edge:libs→edge:deploy-dev→edge:image→edge:sign→edge:staging→verify:staging-evidence→verify:ota-rollback:image→verify:ota-rollback→edge:version)で作成される。 - インストール / 配備 (開発者向け): インストール / 配備