メインコンテンツまでスキップ

オンプレミスのアップグレードランブック

事前確認​

  1. 新しいバージョンでライセンスが有効であることを確認します。コマンドは curl gateway:8082/healthz です。
  2. バックアップ PVC のディスク容量が、DB サイズの 2 倍以上であることを確認します。
  3. メンテナンスの時間帯をユーザーに通知します。

アップグレード​

helm upgrade yabanin deploy/helm/yabanin-onprem \
-f deploy/helm/yabanin-onprem/values-airgap.yaml \
--set image.tag=1.1.0

チャートは次を自動で実行します。

  1. アップグレード前の Job: pg_dump → /backup
  2. ゲートウェイ、loggerd、admin のローリングアップデート(レプリカ数 ≥ 2 でダウンタイムなし)
  3. アップグレード後の 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

アプリケーションに触れずに、次のことを証明します。

  1. マイグレーションのミラー — migrations/ と pkg/migrate/migrations/ は同一の集合を持ちます(乖離があると、スタンドアロンの migrate バイナリが統合バイナリからずれます)。
  2. アップグレード前のバックアップ — sha256 付きの ENT-05 backup_all.sh(RPO の成果物)です。
  3. マイグレーションの up — ソースから新規にビルドした yabanin-migrate です。スキーマが最新なら no-op になり、そうでなければ未適用のファイルを適用します。
  4. オフラインのライセンス有効化 — 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 を通じてマイグレーションします。