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

アップグレード運用手順

MERLON_MIGRATION_DATABASE_URL の専用接続で checksum ledger 付きの make migrate を実行する。台帳がない既存データベースでは、確認済みの最終ファイル名を MERLON_MIGRATION_BASELINE に指定し、自動推測を行わない。

アップグレード前​

  1. 現在稼働中のバージョンから移行先バージョンまでのすべての リリースノートを読み、PostgreSQL データベースと 暗号鍵材料をバックアップする。
  2. 本番環境を代表する設定とデータのコピーを含む環境でアップグレードを試験する。
  3. 現在のアプリケーションバージョンとネイティブエンジン設定ダイジェストを記録する （GET /api/v1/system/config-digests）。

リリース成果物の検証​

タグ付けされた各リリースは、コンテナイメージとともに、デプロイしようとしている ものがプロジェクトのビルド成果物であることを確認するための証跡を公開している。 ロールアウト前に検証すること。未検証のイメージをデプロイすることは、 プロベナンス（来歴）の連鎖全体を捨てることに等しい。

GitHub リリースから release-manifest.json・sbom-image.cdx.json・SHA256SUMS をダウンロードし、以下を実行する。

# 1. 添付ファイルが公開されたチェックサムと一致することを確認する。
sha256sum -c SHA256SUMS

# 2. マニフェストから不変のイメージダイジェストを読み取る。
#    可変タグではなくダイジェストでデプロイすること。
IMAGE=$(jq -r .image release-manifest.json)
DIGEST=$(jq -r .image_digest release-manifest.json)

# 3. このダイジェストが本リポジトリのリリースワークフローでビルドされたことを
#    GitHub が証明していることを確認する。
gh attestation verify "oci://${IMAGE}@${DIGEST}" --repo ksuk/merlon

# 4. 検証済みのダイジェストを取得する。
docker pull "${IMAGE}@${DIGEST}"

${IMAGE}@${DIGEST} をデプロイし、そのダイジェストをデプロイ記録に残すこと。 リリースマニフェストにはリリースコミットも記載されているため、デプロイされた 成果物はソースまで追跡できる。

マイグレーションの適用​

MERLON_DATABASE_URL を対象データベースに設定し、以下を実行する。

make migrate

対象コマンドは migrations/*.sql を辞書順に適用し、最初の SQL エラーで停止する。psql がインストールされた運用者のワークステーションまたはデプロイジョブでの実行を想定している。未検証の本番バックアップに対して実行してはならない。

ロールバック​

リリース固有のロールバック手順が提供されない限り、SQL マイグレーションは前方向のみである。検証に失敗した場合は、ロールアウトを停止し、アップグレード前のバックアップをリストアしてから再試行前に調査する。マイグレーション履歴を削除したり、既に適用済みのマイグレーションを編集したりしないこと。