停止要求の回避

必須ストップとは、GitLabをアップグレードする際に、特定のmajor.minor バージョンにアップグレードして停止する必要が生じるGitLabコンポーネントや依存関係の変更です。

開発者は3リリース（3ヶ月）のバックポートウィンドウを含むメンテナンスポリシーを維持していますが、GitLabは現在のメジャーバージョンと2つ前のメジャーバージョンを含む、より長いバージョンサポートのウィンドウを維持しています。過去のメジャーリリースのスケジュールから、GitLabの顧客は現在のリリースから最大3年遅れても、アップグレードのサポートを期待することができます。

例えば、GitLab 14.0.12からGitLab 16.1へアップグレードするGitLabユーザーは、完全にサポートされたアップグレードパスであり、次のような必要なストップがあるかもしれません：14.3.6,14.9.5,14.10.5,15.0.5,15.1.6,15.4.6, and15.11.11 最新の16.1.z バージョンにアップグレードする前に。

過去の必須ストップは、導入後数ヶ月間発見されませんでした。多くの場合、サポートエンジニア、カスタマーサクセスマネージャー、開発エンジニアによる広範なトラブルシューティングと支援の結果であり、ユーザーは1～3以上のマイナーリリースにまたがってアップグレードを行います。

可能な限り、必須停止は避けるべきです。回避できない場合は、必須停止を_スケジュールされた_必須停止に合わせるべきです。

予定外の必須停止を遡って宣言することを検討している場合は、ディストリビューションチームのプロダクトマネージャーに連絡し、次のステップについてアドバイスを受けてください。ディストリビューション・プロダクト・マネージャーは、最終的な判断を下すために、GitLabプロダクト・リーダーシップ（副社長または最高製品責任者）にエスカレーションすることがあります。これは、例えば、ある変更が非常に大規模な自己管理インストールの小さなサブセットに対して停止を必要とする可能性があり、顧客が問題に遭遇した場合に明確に定義された回避策がある場合に起こります。

スケジュールされた必要な停止は、多くの場合、major バージョンリリースの直前に以前のmajor.minor リリースに対して実施され、予定されている複数の非推奨事項や既知の変更に対応します。

さらに GitLab 16 では、scheduled major.minor required stops：

GitLab 16.xでは、2～3回の必須アップグレードストップを予定しています。

必須アップグレードの停止が予定されている場合は、少なくとも2つのマイルストーンでお知らせします。最初に予定されている必須アップグレード停止は、GitLab 16.3に予定されています。アップグレードストップを必要とするものが何も導入されなければ、GitLab 16.3は通常のアップグレードとして扱われます。 > > >

アップグレード停止の原因

完了したマイグレーションに関する不正確な仮定

必要な停止の大部分は、特定のリリースのデータモデルの状態に関する仮定によるものです。通常、相互に依存するデータベースマイグレーションや、コードがロードされるまでに以前のマイグレーションで導入されたスキーマの変更が完了していると仮定したコード変更の形で行われます。

バージョン間の後方互換性を考慮した変更とマイグレーションを設計することで、継続的なアップグレードや「ゼロダウンタイム」アップグレードによる停止懸念を軽減することができます。しかし、契約フェーズでは、バックグラウンドのマイグレーションが実行またはロードする前に完了していることを必要とするマイグレーション/コード変更が導入された場合、必要な停止が発生する可能性が高くなります。

caution
マイグレーションを追加したり削除したり、あるリリースでマイグレーションが完了していることを前提としたコードを導入することを検討している場合は、まず必須停止に関するデータベース関連のドキュメントをレビューしてください。

使用例

  • GitLab12.1:state 値によって stateMergeRequests のmerge_status を変更するバックグラウンドマイグレーションを導入しましたstate 。この state属性は12.10 で削除されました。 必要な停止を文書化するには13.6 までかかりました。
  • GitLab13.8: 重複するサービスレコードに対処するためのバックグラウンドマイグレーションを導入。13.9 では、バックグラウンドマイグレーション完了に依存する別のマイグレーションでユニークインデックスが適用されました。GitLabまで発見/文書化されていません。14.3
  • GitLab14.3:14.5 でフォアグラウンド化されたmerge_request_diff_commits に対して、長期化する可能性のあるバックグラウンドマイグレーションが含まれています。この変更は、大規模なGitLabインストールを持つユーザーにとって、大規模なダウンタイムとなりました。GitLabまで文書化されていません。15.1
  • GitLab14.9:namespaces とprojects に対するバッチ化されたバックグラウンドマイグレーションが含まれています。このマイグレーションは、14.10 で追加された別のバッチ化されたバックグラウンドマイグレーションが実行される前に終了する必要があり、必要な停止を余儀なくされます。大規模なGitLabインストールでは、マイグレーションが完了するまでに数時間から数日かかることがあります。

その他の詳細および関連するイシューやマージリクエストへのリンクは以下をご覧ください：イシューGitLab アップグレードパスの停止の追加や拡散を避けるための対策を講じましょう。

コードの回避策と緩和策の削除

データモデル/スキーマ/マイグレーション状態に関する仮定と同様に、以前に発見された問題を回避するために実装されたコードを意図的に削除したため、必要なmajor.minor 停止が導入されました。

使用例

  • GitLab13.1: Rails6.0.3.1 のセキュリティ修正により、CSRF トークンの変更が導入されました（canary 環境インシデントの原因）。以前に生成されたトークンの受け入れをメンテナーとするコードを導入し、13.2 のコードを削除して、13.1の既知の必須停止を作成しました。
  • GitLab15.4: GitLab14.9 以降のコードで緩和されていた、ジョブアーティファクトの不正確なexpires_at タイムスタンプを修正するマイグレーションを導入しました。この回避策はGitLab15.6で削除され、15.4 が必須停止となりました。

非推奨事項

非推奨の変更、特に破壊的な変更は、長いマイグレーション遅延を引き起こしたり、GitLab管理者側の手動アクションを必要としたりする場合、必要な停止を引き起こす可能性があります。

これらは一般的にメジャーリリースの前後で必要な停止として受け入れられており、major の新しいリリースの直後に最新のmajor.minor リリースで停止するか、潜在的にはmajor.0 パッチリリースで停止します。

使用例

非推奨事項の例は、ここでは紹介しきれませんが、バージョンごとの非推奨事項や削除事項、バージョンごとのアップグレード手順、GitLabパッケージ（Omnibus）のバージョンごとの変更点、GitLabチャートのアップグレードノートにあります。

さらに読む