Theseus ADR 002：1 つの宣言的インターフェース、複数のプラットフォームバインディング
状態
提案中。
コンテキスト
GitLab は、運用面でほとんど共通点のない一連のターゲットに提供されています。
対象は、開発者ワークステーション（Caproni）、
GitLab.com、
Cells、
Dedicated、
Dedicated for Government、
Enterprise バインディング（customers.gitlab.com など、GitLab Inc. が運用するサービス）、
Self-Managed Advanced、
Self-Managed Foundation（Omnibus、レガシー）です。
各ターゲットには、独自のオーケストレーター、ストレージ層、シークレットバックエンド、監視システム、リリース頻度があります。 設計領域の両極端は明確ですが、どちらも適切ではありません。
- ターゲットを 1 つのデプロイ経路に統合する。 Kubernetes + Helm + ArgoCD を選び、すべてのターゲットに同じ構成を求めます。 実際には不可能です。顧客環境は均一ではなく、 VM 上の Omnibus は Self-Managed Foundation にとって譲れない要件であり、 Dedicated のコンプライアンス方針は GitLab.com と異なります。
- 各ターゲットが独自のコントラクトを再構築する。 これは現状の姿です。 コンポーネントチームはターゲット固有のデプロイコードやツールの断片を作成し、 開発者体験はデプロイ先ごとに異なります。
プラットフォームは、この両者の間に位置する必要があります。
決定
コンポーネントは、抽象的な依存関係
（Postgres データベース、キーバリューストア、オブジェクトストレージなど）を記述した
単一の FairwayManifestを宣言します。
このマニフェストがコントラクトです。
各ターゲットには、マニフェストをターゲット固有のインフラストラクチャへ解決する プラットフォームバインディングがあります。
- Enterprise バインディング → Google Cloud 上の CloudSQL、GCS、Memorystore。
- Cells / Dedicated バインディング → Instrumentor を介した AWS 上の RDS、S3、ElastiCache。
- Caproni バインディング →
gitlab-dev-stackを介したクラスター内オペレーター。 - Self-Managed バインディング → Helm values。インフラストラクチャは顧客が用意します。
同じコンポーネントは、ソースを変更せず、 そのコンポーネント向けに存在するすべてのバインディングで動作します。 新しいターゲットは、新しいコンポーネントではなく新しいバインディングとして追加されます。
結果
メリット
- 一度書けば、どこにでもデプロイできます。 コンポーネントチームはバインディングではなくマニフェストを対象とします。
- ターゲットは独立して進化できます。 バインディングは、すべてのコンポーネントを再リリースせずに 依存関係の実現方法を変更できます。
- 新しいターゲットは追加によって対応できます。 新しいデプロイモデルは、 カタログ内のすべてのチャートのフォークではなく、新しいバインディング実装です。
デメリット
- すべてのバインディングには、継続的なエンジニアリング上の責任が伴います。 バインディングには、オーナー、SLA、マニフェストコントラクトとの同等性が必要です。
- ターゲット固有の機能は自動的には利用できません。 あるクラウドの新しいマネージドサービスは、 該当するバインディングがマニフェストを介して公開するまで、コンポーネントからは見えません。
- 抽象化は漏れます。
コンポーネントがマニフェストでモデル化されていないものを必要とする場合、
ターゲット固有のコードに切り替えるのではなく、スキーマを拡張する必要があります。
このために
infrastructure:エスケープハッチが存在します （セクション 7.3）が、使用にはコストが伴います。
検討した代替案
代替案：すべてのターゲットで 1 つのデプロイ経路を使用する
アプローチ
あらゆる場所で Kubernetes + Helm + ArgoCD（または同様のもの）を必須とし、 適合しないターゲットを移行します。
採用しなかった理由
Self-Managed Foundation は VM 上の Omnibus であり、 意図的な製品上の選択として今後もその形を維持します。 Dedicated for Government には、SAAS 側の運用上の柔軟性を制限する FedRAMP 要件があります。 顧客環境は変更を強制できません。 現在の状態から、単一のデプロイ経路を実現することはできません。
代替案：サービスごとに、ターゲット別の専用実装を用意する
アプローチ
現状を継続します。 各コンポーネントは、対象とするターゲットごとに独自のデプロイ基盤を作成します。
採用しなかった理由
コストは、コンポーネントとターゲットの組み合わせごとに発生し、 結果として断片化を招きます。 ツールに一貫性がなく、 共通の開発者体験がなく、 可観測性やリリースツールに規模の経済が働きません。 プラットフォームの目的は、まさにこの作業のコストを全体に分散することです。
参考資料
- セクション 4 — 1 つのプラットフォーム、複数のバインディング — この ADR が正式に定める方針。
- セクション 4.1 — ターゲットマトリックス — バインディングとその役割の標準一覧。
- セクション 4.2 — 単一の宣言的インターフェース — コントラクトの中心となるマニフェスト。
- セクション 7.3 — 未解決の緊張関係：Runway の「漏れのある抽象化」をめぐる議論 —
このアプローチで既知の障害モードと、
infrastructure:エスケープハッチによる対応。
a1f3c26a)