Cells ADR 017: コンテナレジストリルーティングサービス
| Status | Authors | Coach | DRIs | Owning Stage | Created |
|---|---|---|---|---|---|
| accepted | @ayufan | ~devops::tenant scale | 2025-07-29 |
コンテキスト
GitLab コンテナレジストリは Cells アーキテクチャ内で動作する必要があります。このアーキテクチャでは、プロジェクトとリポジトリが複数の Cell に分散されています。HTTP Router はプロジェクトのオーナーシップに基づいてリクエストを正しい Cell にルーティングしながら、Docker クライアントとの互換性を維持し、Cell をまたいだパブリックリポジトリへのアクセスを可能にする必要があります。
決定事項
HTTP Router の分離デプロイ: コンテナレジストリはメイン GitLab Rails HTTP Router（
gitlab.com）とは別に、専用の HTTP Router デプロイ（registry.gitlab.com）を使用します。パスベースのルーティング: レジストリのリクエストは、URL から抽出されたプロジェクトパス（
/v2/{project_path}/...）および JWT 認証スコープ（repository:{project_path}:actions）に基づいてルーティングされます。ターゲットベースの分類: Topology Service はターゲットベースの分類（
webとregistry）をサポートし、サービスごとに適切な Cell アドレスを返します。JWT トークンの拡張: GitLab Rails は生成された JWT トークンに
organization_idを含めることで、トークン検証リクエスト（/v2/エンドポイント）を正しい Cell にルーティングできるようにします。パブリックリポジトリへのアクセス: プロジェクトパスに基づいた JWT 認証ルーティングにより、ユーザーの認証情報がターゲット Cell で有効でない場合でも、Cell をまたいでパブリックリポジトリへアクセスできます。
レガシー Cell へのフォールバック: 未分類のリクエスト（
/v2/_catalogなど）は、FIRST_CELL分類タイプを使用して最初の Cell にルーティングされます。
メリット
サービスの分離: 専用の HTTP Router により条件付きルーティングの複雑さがなくなり、不要なルール処理を回避してパフォーマンスが向上します。
Cell をまたいだパブリックアクセス: ユーザーはホスティング Cell の場所を知らなくても、どの Cell からでもパブリックコンテナリポジトリにアクセスできます。
Docker 互換性: 既存の Docker クライアントワークフローと認証フローとの完全な互換性を維持します。
Cell への変更が最小限: GitLab Rails やコンテナレジストリコンポーネントへの変更が不要（または最小限）で、すべてのルーティングの複雑さは HTTP Router が処理します。
スケーラブルなアーキテクチャ: 各サービスが独自のルールセットを維持し、独立してスケールできます。
フォールト分離: 各 Cell 内でコンテナレジストリを実行することでフォールト分離が実現されます。ある Cell が利用不可になっても、その Cell でホストされているリポジトリにのみ影響し、他の Cell は通常通りリポジトリを提供し続けます。
デメリット
JWT スコープへの依存: ルーティングは JWT リクエストの最初のリポジトリスコープに依存しており、Docker Registry の仕様がスコープの順序を定義していないため、問題が生じる可能性があります。
Cell をまたいだ制約: Cell をまたいだリポジトリのリンクやブロブのマウントは機能しないため、Docker の一部の高度な機能が制限されます。ただし、GitLab の使われ方を考慮すると、これは許容できるトレードオフです。
追加のインフラストラクチャ: 別の HTTP Router のデプロイと保守が必要です。
実装要件
HTTP Router の変更
- 分類リクエストにおける
targetパラメーターのサポート - 複数の分類マッチを順次処理
- コンテナレジストリ用の別ルールセット（
container_registry.json）
Topology Service の更新
targetフィールドを持つ拡張ClassifyRequestインターフェースFIRST_CELL分類タイプのサポート- Cell ごとのレジストリ固有のアドレス設定
GitLab Rails の変更
- ルーティング用に JWT トークンに
organization_idを含める - Cell 固有のレジストリエンドポイントのための最小限の設定変更
代替ソリューション
最初のスコープへの依存が問題となる場合、代替の JWT ルーティングアプローチには以下があります：
- クエリパラメーターアプローチ：
/jwt/auth?cell_id=X（推奨） - パスプレフィックスアプローチ：
/c/cell-id/jwt/auth - パスサフィックスアプローチ：
/jwt/auth/cell/cell_id
