Protocell への組織データ移行におけるロールバック戦略

定義

データロールバック: 組織のデータを、トポロジールーティング切り替え後に移行先 Cell で行われた最近の変更を含めて、移行先 Cell から移行元 Cell へ戻すこと。
トポロジールーティング切り替え: Topology Service は組織のトラフィックを該当する Cell へルーティングする制御を担います。データ移行が成功裏に完了した時点で、Topology Service はトラフィックのルーティングを移行元 Cell から移行先 Cell に切り替えます。
Fix-forward（前進修正）: 移行先 Cell で発見された問題を、移行を逆戻りさせるのではなく、その場で解決すること。これは本番システムにおける標準的な運用姿勢です。
Go/No-Go ゲート: トポロジールーティング切り替えを実行する前にクリアしなければならない正式な検証チェックポイント。ゲートをクリアできない場合、切り替えは行われず、組織は移行元 Cell に留まります。

コンテキスト

GitLab は Cell ベースアーキテクチャへの移行の一環として、顧客の組織を Legacy Cell から Protocell へ移行しています。移行ツールは、組織データ（PostgreSQL、Git リポジトリ、オブジェクトストレージ、Container Registry）を移行元 Cell から移行先 Cell へコピーします。移行が検証された後にのみ、Topology Service はルーティング切り替えを実行し、トラフィックを移行先 Cell へ向けます。

プロダクトとエンジニアリングから提起された重要な問いは次のものです: 組織を Protocell へ移行した後に問題が発見された場合、データを戻す機能を構築すべきか?

この問題は Rollback Options (#581028)、Protocells Steerco、および Cells Migration Rollback capabilities call で広く議論されました。4 つのロールバック選択肢が評価されました: Topology Flip、Full Migration Back、Direct Transfer、Congregate です。

重要

この ADR は移行ロールバックのみを扱います。標準的なバックアップおよびディザスタリカバリ手順の必要性に 代わる ものでは ありません。組織データは、移行プロセスとは独立して、移行元 Cell と移行先 Cell の両方でバックアップされる必要があります。ロールバックはデータ保護の仕組みではありません — 移行リカバリの概念であり、サポートしないと決定したものです。

決定

組織データ移行に対してデータロールバックはサポートしません。

トポロジールーティング切り替えは、移行が go/no-go ゲートをクリアした後にのみ実行されます。これは、不完全なデータやサポートされていない機能を持つ移行先 Cell へトラフィックがルーティングされる状況には決して陥らないことを意味します。ゲートがクリアされない場合、組織は移行元 Cell に留まります — 切り替えは行われず、ロールバックも不要です。

トポロジールーティング切り替えの後、移行先 Cell で発見された問題に対しては fix-forward の姿勢を取ります。

Go/No-Go ゲート

go/no-go ゲートは主要なリスク軽減メカニズムです。次の両方の基準が満たされない限り、トポロジールーティング切り替えは実行されません:

レプリケート済みデータの完全性 — 移行先 Cell 上のすべての組織データが、移行元 Cell と完全かつ整合的であることが検証されていること。これには PostgreSQL データ、Git リポジトリ、オブジェクトストレージ、および Container Registry データが含まれます。検証はチェックサム、行数カウント、移行元 Cell に対するスポットチェックを通じて実行されます。
機能互換性とサポート可能性 — 移行先 Cell が、組織が必要とするすべての機能をサポートしていること。これには、組織が移行先 Cell で利用不可またはサポートされていない機能（例: ホストランナー、特定のインテグレーション、CI/CD 機能）に依存していないことの確認が含まれます。移行先 Cell が組織のワークロードを完全にサポートできない場合、その組織は移行候補にはなりません。

いずれかの基準が満たされない場合、トポロジールーティング切り替えは行われません。組織は移行元 Cell に留まり、移行は失敗した試行として扱われ、ツールや Cell 構成を改良してから再試行されます。

Stage 1: カットオーバー検証（ユーザートラフィック前）

このステージは、データ移行完了後 かつ顧客トラフィックが移行先 Cell に書き込みを許可される前に発生します。移行元 Cell は引き続きアクティブな本番システムです。

続行する前の最低限のチェック:

ルーティングと接続性
- Topology Service が組織を移行先 Cell へ正しくルーティングしていること。
- 代表的なユーザーに対して、移行先 Cell からのリポジトリへの SSH/HTTP アクセスが機能していること。
認証とセッションフロー
- 主要な認証フロー（ユーザー名/パスワード、該当する場合は SAML/OmniAuth）がテストアカウントに対して end-to-end で成功すること。
データの完全性
- PostgreSQL データのチェックサムと行数が移行元 Cell と一致すること。
- Git リポジトリのチェックサムが一致すること。
- オブジェクトストレージと Container Registry のデータが存在しアクセス可能であること。
基本的な機能スモークテスト
- 移行された組織に対して、主要なデータタイプ（プロジェクト、Issue、パイプライン）の読み取り/書き込み操作が成功すること。
- 移行されたデータセットに明白なデータ破損や大きな欠落がないこと。

これらのチェックのいずれかが失敗した場合、トポロジールーティング切り替えは行われません。移行は失敗した試行（“go-around”）として扱われ、ツールとプロセスが改良され、新しいカットオーバーウィンドウがスケジュールされます。

Stage 1 が通過した後、顧客向け最終チェック のために、移行先 Cell に対して トポロジールーティング切り替え を実施し、制御された顧客アクセスが有効化されます:

認証とセッション — 顧客が想定される認証方法（該当する場合は SAML/SSO など）でサインインできること。
ランナー — 代表的な CI ジョブが、組織が構成したランナー（または該当する場合は共有ランナー）で正常に実行されること。
インテグレーション — クリティカルなインテグレーションの厳選セット（SCM フック、主要な webhook、外部 Issue トラッカー）が実行され成功すること。
Git 操作 — ユーザーが主要なリポジトリにコードをプッシュでき、パイプラインや MR フローで期待される動作を確認できること。

Stage 2 中のみのスイッチバック

スイッチバック — データを移動させずにトポロジールーティング切り替えを反転して、トラフィックを移行元 Cell に戻すこと — は go/no-go ゲートの Stage 2 中、すなわち顧客のスモークテストが進行中の間にのみ利用可能です。

Stage 2 中に顧客向けチェックが失敗した場合（例: ランナーが動作しない、クリティカルなインテグレーションが失敗する、git push が予期せぬ動作をする）、移行元 Cell へのスイッチバックを実行し、移行を失敗した試行として扱います。組織は移行元 Cell での運用を再開し、問題が解決された後に移行が再試行されます。

Stage 2 のスモークテストウィンドウ中に移行先 Cell で作成されたデータはすべて失われることが理解されています。 これが許容される理由は、スモークテストウィンドウが短いこと、データ量が最小限であること（検証活動に限定される）、顧客が制御された検証に参加していることを認識しているためです。

スイッチバックは Stage 2 完了後、移行がコミットされた後には利用 できません。go/no-go ゲートが完全にクリアされ、トポロジールーティング切り替えが確定すると、fix-forward の姿勢を取ります。

切り替え後: fix-forward

トポロジールーティング切り替えの後、組織は移行先 Cell でライブ稼働します。この時点で発見された問題はすべてその場で解決されます:

軽微なデータの欠落（例: 完了しなかったバックグラウンドジョブ）は、移行先 Cell で前進的にパッチが適用されます。
機能の問題 は本番のバグとして扱われ、GitLab.com のインシデントと同じ緊急度で修正されます。
パフォーマンスの問題 は、標準的なインフラストラクチャのチューニングとスケーリングを通じて対処されます。

コホート別の動作

コホート	説明	切り替え前	切り替え後
コホート 0	内部テスト組織	go/no-go ゲート; 破棄して再作成可能	fix-forward; 顧客への影響なし
コホート A	非アクティブな無料ユーザーのサブセット	go/no-go ゲート	fix-forward
コホート B	アクティブなオプトインベータ（最大 1,000 組織）	go/no-go ゲート; 機能パリティ必須	fix-forward
コホート C	データベース時間でトップ 1,000 組織	go/no-go ゲート; 機能パリティ必須	fix-forward

移行元データの保持

移行元 Cell 上の組織データは、トポロジールーティング切り替え後、定義された保持期間にわたって（読み取り専用で）保持されます:

コホート 0/A: プロセスが堅牢化される間、無期限に保持。
コホート B/C: 定義されたウィンドウ（プロダクトが DBRE および Tenant Scale と協議して決定）の間保持され、その後プルーニング。

この保持されたデータは調査やデータ照合のための参照として機能しますが、「戻す先」として意図されているわけではありません。

動機

データロールバックが実現可能ではない理由

ロールバックのコストは fix-forward のコストを上回ります。 トポロジールーティング切り替え後に移行先 Cell で 95% 機能している組織を考えてみてください — おそらく軽微なインテグレーションが正常に動作していないか、バックグラウンドジョブが完了していない、といった状況です。データロールバックには次のことが必要となります:

組織を移行先 Cell でメンテナンスモードに置く（ダウンタイム開始）。
すべてのデータ（移行先 Cell で作成された新しいデータを含む）を移行元 Cell に戻して移行する。これは順方向移行と同じオーダーの複雑さを持ちます。
両方の Cell に存在するようになったデータを、潜在的な競合とともに照合する。
移行元 Cell への別のトポロジールーティング切り替えを実行する。
ロールバック自体を検証する（独自の go/no-go ゲートを導入する）。
総ダウンタイム: データ量に応じて数時間から数日。

対照的に、95% 機能している組織を fix-forward で修正するということは、特定の問題をその場で特定してパッチを適用することを意味し、組織はその間も稼働し続けます。ターゲットを絞った fix-forward の顧客への影響は、完全なデータロールバックが課すダウンタイムのほんの一部です。

データの分岐がロールバックを運用上扱いにくいものにします。 顧客が移行先 Cell にデータを書き込むと — 新しいプロジェクト、Issue、マージリクエスト、パイプライン実行など — そのデータは移行先 Cell にのみ存在します。データロールバックは、この移行後の作業を破棄する（アクティブな顧客には受け入れられない）か、移行元 Cell にマージし戻す（既存のツールがなく技術的に複雑でエラーが起きやすい）必要があります。

Geo は一方向です。 現在の移行プロセスは、移行元 Cell から移行先 Cell へデータをレプリケートするために Geo を再利用しています。この関係を逆転させるには、両方の Cell が同時にプライマリとセカンダリの両方として動作する必要があり — これは構築もテストもされたことのない構成であり、大幅なインフラ投資を必要とします。

機能パリティが主要なロールバック要因を排除します。 顧客が「戻りたい」と思う主な理由は、移行先 Cell に機能が欠けていることです。go/no-go ゲートの一部として機能互換性を要件とすることで、トポロジールーティング切り替えが起こる前にこの要因を排除します。

エンジニアリングの労力は順方向移行の品質に投じる方が良いです。 完全な逆方向移行機能の構築、テスト、検証に必要な労力は相当なものであり、未知数です。この労力は、順方向移行ツールの堅牢化、go/no-go 検証の改善、fix-forward 機能の構築 — これらすべてはロールバックが必要となる可能性を低減するもの — と直接競合します。

前例: GitLab Dedicated の移行

Protocell の移行アーキテクチャは GitLab Dedicated とは異なりますが、運用パターンは示唆に富みます。これまでのすべての Dedicated 顧客の移行において、データロールバックを実行する必要は一度もありませんでした。移行はカットオーバー前に中止される（go/no-go ゲートをクリアしないことに相当）か、移行先環境で前進的に問題が修正されてきました。この実績は、ロールバックなしのゲートベースのアプローチの実現可能性を裏付けています。

結果

go/no-go ゲートは厳格でなければなりません。 トポロジールーティング切り替え後にフォールバックがないため、検証基準は包括的かつよくテストされている必要があります。チェックサム、自動検証、ゲームデーへの投資が極めて重要です。
アクティブなコホートにとって機能パリティはハードゲートになります。 コホート B と C は、機能互換性が確認されるまで移行できません。これは Organizations プロダクトチームと Cells インフラチームの間に依存関係を作り出します。
fix-forward 機能は堅牢でなければなりません。 データロールバックの選択肢なしで移行後の問題に対処するには、Protocell における強力な可観測性、インシデント対応、パッチ適用機能が必要です。
移行元データの保持はスケーリングのメリットを遅らせます。 移行元 Cell に組織データを保持することは、移行の動機となるデータベースのヘッドルームのメリットを遅らせます。後のコホートでは保持ウィンドウを意図的に短く保つ必要があります。
顧客とのコミュニケーションは明確でなければなりません。 移行にオプトインする顧客（コホート B/C）は、移行がトポロジールーティング切り替え後は不可逆であり、いかなる問題も fix-forward で解決されることを理解する必要があります。
将来の Org Mover は再検討する可能性があります。 任意の Cell 間で任意の方向に組織を移動できる、将来のフル機能の Org Mover は、この決定を再検討する可能性があります。ただしこれは近い将来のロードマップにはなく、Protocell 移行プログラムと混同されるべきではありません。

検討された代替案

Option 1: 完全データロールバック（逆方向移行）

順方向移行と同等の複雑さを持つ、組織データを移行先 Cell から移行元 Cell へ戻す完全なデータ移行プロセスを構築する。

長所: すべての移行後データを保持; 永続的なセーフティネットを提供。
短所: 未知ながら相当なエンジニアリング労力; 最初の移行を無期限に遅らせる; テストと検証の表面積を倍増させる; 双方向 Geo または同等のもの（構築されたことがない）が必要; ロールバック自体の間に大幅な顧客ダウンタイムを課す。
判定: 却下。ロールバックのダウンタイムと複雑さは fix-forward のコストを上回ります。エンジニアリング労力は go/no-go ゲートの品質により良く投資されます。

Option 2: コミット後のトポロジースイッチバック（go/no-go 後のルーティングのみの復帰）

go/no-go ゲートが完全にクリアされ移行がコミットされた後、データを移動せずにルーティングを移行元 Cell に戻す。

長所: 実行が高速（数分）; データ移行が不要。
短所: 移行コミット後に移行先 Cell で作成されたすべての本番データを破棄; 組織が移行先 Cell で長く運用するほど、より多くのデータが失われる; 根本原因に対処しない; fix-forward 機能への投資を弱める誤った安心感を生み出す。
判定: コミット後のメカニズムとしては却下。スイッチバックは Stage 2 のスモークテストウィンドウ中（上記参照）にのみサポートされ、データ損失は検証活動に限定されます。移行がコミットされた後は、fix-forward を行います。

Option 3: Direct Transfer（逆方向）

GitLab のネイティブなバルクインポートメカニズムを使用して、移行先 Cell から移行元 Cell へデータを戻して移行する。

長所: 既存のツールを活用; 完全な逆方向移行よりも労力が少ない。
短所: ゼロから完全なデータコピーが必要（増分ではない）、元の順方向移行に匹敵する大幅なダウンタイムを課す; リソース ID（グループ、プロジェクト）を変更し、外部インテグレーションやブックマークを破壊する; 特定のデータタイプ（CI/CD 変数、デプロイトークン、webhook）を除外する; データ整合性を検証しない; Cells でまだ実用的ではない。
判定: 却下。完全な再コピーのダウンタイムは復帰の利点を打ち消し、ID の変更はアクティブな顧客には受け入れられません。

Option 4: Congregate（逆方向）

Congregate（Direct Transfer の拡張ラッパー）を使用して、より広範なデータタイプのカバレッジでデータを戻して移行する。

長所: Direct Transfer よりも優れたデータタイプカバレッジ; CI/CD 変数、webhook、レジストリを処理。
短所: Direct Transfer と同様 — 同等のダウンタイムでゼロから完全なデータコピーが必要; 依然としてリソース ID を変更; 両方の Cell へのネットワークアクセスを持つ別のコンテナの実行が必要; 一部のデータタイプは引き続きサポートされない; データ整合性を検証しない。
判定: Direct Transfer と同じダウンタイムおよび ID 変更の理由により却下。

Option 5: 双方向 Geo レプリケーション

Geo を拡張して、移行元 Cell と移行先 Cell 間の双方向レプリケーションをサポートし、移行後に両方の Cell を同期した状態に保つ。

長所: いつでもデータ損失なしでシームレスなスイッチバックを可能にする。
短所: Geo は双方向レプリケーションをサポートしたことがない; これはコアシステムへの根本的な変更を必要とする net-new な機能; データ競合の重大なリスク; すべてのリクエストとバックグラウンドジョブが Cells 対応かつ Org Migration 対応である必要; 大規模なエンジニアリング投資。
判定: 却下。厳格な go/no-go ゲートと fix-forward によって不要となる機能に対して、不釣り合いな労力とリスクです。