アップグレードとロールバック

アップグレードとは固定する正確なイメージの変更であり、ロールバックとは以前のイメージに戻すことです。Community では、それはイメージの正確なバージョンタグと、固定している場合はそのダイジェストです。タグはそのバージョンが再ビルドされると新しいバイトに再びプッシュされることがありますが、ダイジェストは決して動きません（Docker → イメージを固定するを参照）。Enterprise では、リリースノートに記載されたダイジェストです（Enterprise で追加されるもの）。このページのそれ以外の内容は両方に共通です。Docker → アップグレードとロールバックに手順と各ステップの理由を記載しています。このページはそれをチェックリストとして繰り返し、特定のリリースが求める手順を追加します。

アップグレード

1. 実行中のバージョンから移行先のバージョンまでの、すべての ObjectStack リリースのノートを読み、後述のバージョン固有の手順を順に実施します。メジャーバージョンの移動は、下層に破壊的変更があることを意味します。
2. データベースをバックアップします。 スキーマのマイグレーションは前にしか進みません。イメージをロールバックしても、スキーマはロールバックされません。
3. イメージを新しい正確なバージョン（ダイジェストを固定している場合はそのダイジェスト）に変更し、再起動します。スキーマはランタイムが準備完了を報告する前に最新の状態にされます。破壊的な変更は、os migrate apply --allow-destructive で適用するまで、その変更を示して起動を拒否します。
4. readiness（/api/v1/ready）が 200 を返すことを確認します。

ロールバック

以前のバージョンと、固定している場合はそのダイジェストを残しておきます。それがロールバックです。ロールバックするには、それに戻して手順 3 を繰り返します。離れるバージョンが互換性のないスキーマ変更を行っていない限り有効です（行った場合はリリースノートに記載されています）。シークレットにも同じ一方通行の境界があります。ObjectStack 17.7 以降で設定またはローテーションしたシークレットは、17.7 より前のリリースでは読めません（後述の 17.7 を参照）。

アプリは別にバージョン管理される

アプリ自体は、公開済みアーティファクトとして提供される場合、イメージとは独立してバージョン管理されます。デプロイ → アプリの組み込み方を参照してください。公開したアーティファクトは不変として扱ってください。その場で上書きすると、データベースのバックアップが完璧でも、きれいにロールバックする能力を失います（バックアップ → アーティファクトのバージョン管理）。

バージョン固有の手順

上記の手順はすべてのリリースで同じです。ObjectOS の下層にある ObjectStack のリリースの中には、オペレーターに対応を求めるものもあります。新しいイメージが起動する前に変数を設定する、データマイグレーションを実行する、認証情報をローテーションする、などです。Community イメージのバージョンは ObjectStack のバージョンそのものです。Enterprise では、イメージのリリースマニフェストに、組み込まれた ObjectStack のバージョンが記載されています。通過するすべてのバージョンのサブセクションを、古いものから順に、上記の手順と並べて実施してください。

各サブセクションは、そのリリースのアップグレードチェックリストのうちオペレーターが担う部分であり、チェックリスト全体へのリンクがあります。リリースが実行中のアプリ（そのメタデータとコード）に対して変更する内容は、同じチェックリストと変更履歴にあります。os migrate コマンドは、新しいイメージが組み込むバージョンの ObjectStack CLI です。メタデータを読むためにアプリを起動するので、デプロイメントの起動時と同じ環境（同じデータベースと同じアプリ）で実行してください。CLI → データベースのマイグレーションを参照してください。

コピーで予行演習してください。 リリースノートでは、チェックリストのほとんどの行が not exercised とされています。実際のアップグレードを通して確認したものではなく、変更内容から導いたものです。各手順はまずデータベースのコピーに対して実行し、本番の前にバックアップを取ってください。

ObjectStack 17.0

• 2 つのデータマイグレーションを実行します。 os migrate files-to-references を実行してから --apply 付きでもう一度実行します。そして os migrate value-shapes を実行し、何も報告されなくなったら --apply を実行します。それぞれがフラグを記録するまで、17.0 より前に作成されたデータベースは不正な形式のファイル値と参照値を警告付きで受け入れ続けます。記録後は拒否します。期限までに修正できない連携については、抜け道を参照してください。
• アプリがバインドするすべてのデータソースが接続できなければなりません。 接続できないものがあると起動は失敗し、応答しなくなったものがある間、/api/v1/ready は 503 を返します。

チェックリスト全体：17.0.0。

ObjectStack 17.1

• アップグレードの前に、オフにされた権限セットとポジション（active: false）を一覧にします。 17.1 以降、それらは権限を付与しなくなり、無効化されたポジションを指定する共有ルールは共有が取り消されます。引き続き権限を付与すべきものは再度有効にしてください。
• isolated では API キーを再発行します。 17.1 より前に発行されたキーは組織を持たないため、OS_TENANCY_POSTURE=isolated では拒否されます。
• エクスポートはオブジェクトごとに付与されます。 標準の管理者権限セットは、すべてのオブジェクトをエクスポートできなくなりました。エクスポートを意図する場所では、アプリ自身の権限セットで allowExport を付与してください。

チェックリスト全体：17.1.0。

ObjectStack 17.2

• http_request_errors_total をキーとする監視を向け直します。 この系列は廃止され、常にゼロを示すため、正常なサーバーのように見えてしまいます。http_requests_total{status=~"5.."} を使ってください。
• 外部データソースのルートを呼び出す認証情報には、manage_platform_settings または manage_metadata を付与します。これらのルートは、それ以外の呼び出し元を 403 で拒否するようになりました。

チェックリスト全体：17.2.0。

ObjectStack 17.3

• 壁で区切られた姿勢では、新しいイメージが起動する前に OS_PLATFORM_OWNER_EMAIL を設定します。 そうしないと起動を拒否します。環境変数を参照してください。
• 新しい一意インデックスを構築できるように、自動採番の重複を解消します。 os migrate duplicates を実行し、報告された重複を修正してから、os migrate plan を再実行します。それまではインデックスは構築されず、一意性も強制されません。起動時にはログが出るだけなので、問題なく起動したことはインデックスが存在する証拠になりません。
• sys_record_share をバックフィルします。 17.3 より前に書き込まれた共有の付与は組織を持たず、テナントスコープの読み取りでは見つからなくなります。ObjectStack はこのバックフィルを、os コマンドではなく、@objectstack/plugin-sharing の 2 つの関数 planSysRecordShareOrganizationBackfill（ドライラン）と runSysRecordShareOrganizationBackfill として提供しており、起動時に自動実行されることはありません。
• オープンなサインアップは宣言が必要になりました。 対象者の姿勢を宣言しないアプリは招待制です。アドレスに保留中の招待がない限り、自己登録は 403 SELF_REGISTRATION_CLOSED で拒否されます（新規インストールの最初のアカウントは例外です）。

チェックリスト全体：17.3.0。

ObjectStack 17.4

• isolated では、組織を持たない API キーを再発行します。 それらは 200 から 401 に変わります。group では、そのようなキーは引き続き機能します。
• 認可ストアに到達できない間、ストレージのダウンロードと設定のルートは 503 を返します。以前は黙って劣化していました。

チェックリスト全体：17.4.0。

ObjectStack 17.5

アップグレードの前に：

• 壁で区切られた姿勢では、すべてのプラットフォーム管理者を OS_PLATFORM_OWNER_EMAIL に列挙します（カンマ区切り、確認済みのアドレス）。admin_full_access の付与はその地位を与えなくなり、宣言のないデプロイメントはプラットフォーム管理者なしで起動します。
• スケジュールされた処理について決めます。 時間で起動するフローとパッケージ化された cron ジョブは、デプロイメントが OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true を設定しない限り実行されなくなります。isolated では、まず各スケジュールフローの開始ノードに実行時の organization を指定し、中断中の実行を排出してください。フローと自動化を参照してください。
• アカウント識別情報の変更を事前確認します。 os migrate account-issuer を実行し（読み取り専用。2 つのアカウントが衝突する間はゼロ以外で終了します）、報告されたすべての衝突を解消します。衝突する行が自動的にマージされることはありません。

リリースへの移行：

os migrate account-issuer                     # expect: safe to drop
os migrate plan                               # read every destructive change first
os migrate apply --allow-destructive          # drops sys_account.issuer, after a backup
os migrate account-issuer                     # again: expect zero collisions

--allow-destructive は、これだけでなくプランに列挙されたすべての破壊的な変更を適用します。そのため、先にプランを確認します。

その後：

• 匿名の GET /api/v1/auth/get-session は、null 付きの 200 ではなく 401 を返します。
• Analytics は、オブジェクトを読めない呼び出し元を 403 で拒否します。
• 失敗した通知の配信は 90 日ではなく 7 日間保持されます。

チェックリスト全体：17.5.0。

ObjectStack 17.6

• アプリがオブジェクトを読み書きする匿名エンドポイント（authRequired: false）を宣言している場合は、アップグレードを保留します。 17.6 以降、そのエンドポイントはすべてのオブジェクトで拒否され、匿名の呼び出し元に権限セットを付与するサポートされた方法は、17.7 でもありません。公開フォームは別の入り口であり、引き続き機能します。
• /api/v1/meta を通じて datasource または external_catalog のメタデータを読む、あるいは datasource のメタデータを保存するすべてのユーザーまたは連携に、manage_platform_settings を付与します。
• パッケージ化されたフローと同じ名前を持つ保存済みのフローを見つけます（起動ログがそれぞれについて警告します）。17.6 以降はパッケージ化されたフローが優先され、保存済みのものは実行されなくなります。必要なものは新しい名前で複製してください。
• 保存されたメタデータ本体のコピーを書き換えます： os migrate audit-metadata-bodies を実行してから、--apply 付きでもう一度実行します。⚠️ 17.6.0 ではドライランでもデータベースに書き込みます。コピーに対して実行してください。
• 西暦 1000 年より前の datetime の値を見つけて書き換えます。アップグレード後は、そのような値を含む書き込みはすべて拒否されます。

チェックリスト全体：17.6.0。

ObjectStack 17.7

アップグレードの前に：

• 廃止されたフィールドの残りの列を読む変換は、そのフィールドがまだ宣言されている間に実行します。アップグレード後は、ランタイムのどの入り口もその列を返しません。読めるのは os migrate unmapped-columns --object NAME だけです。
• 公開のままにする必要があるすべての公開フォームに sharing.enabled: true を追加します。アプリと保存済みのオーバーレイの両方です。これがないと、フォームは 404 FORM_NOT_FOUND を返します。
• 17.7 より前にロールバックする可能性がある場合は、すべてのシークレットを再設定できる手段を残しておきます。 17.7 で設定、ローテーション、または再封印されたシークレットは、以前のリリースでは開けない形式で書き込まれます。
• インメモリの起動ストアを置き換えます（OS_DATABASE_DRIVER=memory または memory:// の URL）。これは拒否されます。

リリースへの移行：os migrate audit-metadata-bodies を実行してから --apply 付きでもう一度実行し、監査とアクティビティのコピーから保存されたコンテンツハッシュを削除します。17.7 のドライランは書き込みを行わなくなりました。アップグレード前から保持しているメタデータのバージョントークンは、一度だけ 409 METADATA_CONFLICT を返します。項目を読み直して新しいトークンを取得してください。

最初の起動の後：

• すべてのフローのシークレット（受信フックの secret と http ノードの signingSecret）をローテーションします。起動ログが sys_flow_credential に移動したと報告してから行い、署名または検証する人に新しい値を渡してください。
• JWT の署名キーをローテーションし、非公開のままにすべき共有リンクを取り消して再発行します。 以前の値は監査証跡にコピーが残っている可能性があり、アップグレードはそれを書き換えません。署名キーのローテーション方法は、デプロイメントが署名キーをどのように提供しているかによって異なるため、デプロイメント自身の手順に従ってください。
• アップグレード前に一時停止したフローの実行を、再開、キャンセル、またはパージします。 保存された変数には、まだ認証情報が平文で残っています。
• 任意。17.7 より前にロールバックしないと決めてから： os secret rewrap を実行してから --apply 付きでもう一度実行すると、古いシークレットが新しい形式で再封印されます。アップグレードの過程でこれが実行されることはありません。
• /api/settings/localization に書き込むクライアントから、廃止されたローカライズのキーを削除します：date_format、time_format、number_format、first_day_of_week。いずれかを指定したリクエストは、全体が 400 で拒否されます。
• 未確認のローカルメールアドレスへの外部サインインは拒否されます（account_not_linked）。そのアカウントに黙ってリンクされることはなくなりました。

チェックリスト全体：17.7.0。

Enterprise で追加されるもの

Enterprise イメージはタグではなく、常にダイジェストで固定します。したがって、アップグレードはダイジェストの変更であり、ロールバックは以前のダイジェストに戻すことです。

1. リリースノートから新しいダイジェストを取得し、ロールアウトの前にイメージのリリースマニフェストを読みます。製品のメジャーラインが現在のものと同じであることを確認し、組み込まれたランタイムの互換性範囲が動いたかどうかを確認します。
2. データベースをバックアップしてから、イメージのダイジェストを変更してスタックを再起動します。マイグレーションは、新しいレプリカがトラフィックを受ける前に完了まで実行されます。
3. readiness が 200 を返し、レプリカが正常と報告することを確認します。ロールバック先として以前のダイジェストを残しておいてください。

• Kubernetes：アップグレードは同じくイメージのダイジェストの変更であり、新しいレプリカが提供を始める前にマイグレーションの Job が完了まで実行されます。Kubernetes → ローリングアップグレードはダイジェストを変更するを参照してください。
• エアギャップ：新しいダイジェストを外部で検証し、内部に転送し、固定するダイジェストを変更して再起動します。以前のダイジェストは残しておいてください。エアギャップのネットワーク内では、それがロールバック先となる唯一のコピーかもしれません。エアギャップ → イメージをネットワーク内に持ち込むを参照してください。