オンプレミスのアップグレードランブック
事前確認
- 新しいバージョンでライセンスが有効であることを確認します。コマンドは
curl gateway:8082/healthzです。 - バックアップ PVC のディスク容量が、DB サイズの 2 倍以上であることを確認します。
- メンテナンスの時間帯をユーザーに通知します。
アップグレード
helm upgrade yabanin deploy/helm/yabanin-onprem \
-f deploy/helm/yabanin-onprem/values-airgap.yaml \
--set image.tag=1.1.0
チャートは次を自動で実行します。
- アップグレード前の Job:
pg_dump→ /backup - ゲートウェイ、loggerd、admin のローリングアップデート(レプリカ数 ≥ 2 でダウンタイムなし)
- アップグレード後の Job:
YABANIN_REGION=onprem yabanin-migrate
ロールバック(マイグレーションが失敗した場合)
helm rollback yabanin
ロールバック後の Job は、最新の /backup ダンプを復元します。
マイグレーションの規律
- 新しい列は nullable であるか、デフォルト値を持たなければなりません(ローリングアップデート中の後方互換のためです)。
- 破壊的な変更は
IF EXISTS/IF NOT EXISTSで包みます。 - 列の名前を 1 ステップで変更してはなりません。新しい列を追加し、二重に書き込み、バックフィルし、古い列を削除します。
自動化されたアップグレード前ドリル(ENT-06)
実際の導入に触れる前に、オフラインのドリルを実行します。
bash scripts/airgap/upgrade_drill.sh \
"postgres://yabanin:…@localhost:5432/yabanin?sslmode=disable" /tmp/upgrade-drill
アプリケーションに触れずに、次のことを証明します。
- マイグレーションのミラー —
migrations/とpkg/migrate/migrations/は同一の集合を持ちます(乖離があると、スタンドアロンの migrate バイナリが統合バイナリからずれます)。 - アップグレード前のバックアップ — sha256 付きの ENT-05
backup_all.sh(RPO の成果物)です。 - マイグレーションの up — ソースから新規にビルドした
yabanin-migrateです。スキーマが最新なら no-op になり、そうでなければ未適用のファイルを適用します。 - オフラインのライセンス有効化 — PKI の一連の往復です(gen-root → issue-intermediate → issue → verify)。
LICENSE VALIDは、ネットワークなしのエアギャップでの有効化を証明します。
最新のローカルエビデンス(2026-09-13)では、4 つのステップがすべて成功し、バックアップは 152,416 B、migrate は no-op、ライセンスチェーンは検証済みです。
既知の失敗モード: 古い migrate バイナリ
squash 前のツリーからビルドした yabanin-migrate バイナリは、古い 37 ファイルのカタログを埋め込み、不正な schema_migrations (37, dirty) レコードを書き込みます(2026-09-13 のドリルで観測)。そのためドリルは、現在のソースから migrate バイナリを作業ディレクトリへビルドします。破損した追跡テーブルの修復は、スキーマを実際に適用済みの集合まで戻してから、UPDATE schema_migrations SET version=<head>, dirty=false を実行します。
既知の失敗モード: 手動の psql マイグレーション
.sql ファイルを手動でパイプしてマイグレーションしたデータベースには、schema_migrations の行がありません。ランナーはそれらを未マイグレーションとして扱い、最初のオブジェクトで失敗します。常に yabanin-migrate を通じてマイグレーションします。