Content last updated 2026-04-19

Artifact Registry と Infrastructure のインターフェース合意

Artifact Registry チームと Infrastructure チームの間のインターフェース合意

概要

Artifact Registry (AR) は、最初のステートフルなモジュラーサービスです。本ドキュメントは、AR のインフラ要件をインターフェース合意として定義し、両チームが必要なものについて整合した上でそれぞれ独立して作業を進められるようにします。

目標は、インフラがどのようにプロビジョニングされるかを規定することではなく、AR が必要とするもの、推奨するもの、そしてリスクのある箇所を明確に示すことです。インフラチームが「どのように」を決定し、本ドキュメントは「何を」必要とするかを定義します。

バージョン履歴

バージョン	日付	著者	承認者	概要
0.1	2026-04-13	@jdrpereira	@jdrpereira @glopezfernandez	初版。Google ドキュメントから移行

タイムライン

AR は、Q2 FY27 末（2026 年 7 月 31 日）までに .com での公開を目指しています。本ドキュメントの MUST 要件を満たすインフラを .com 向けに用意するには、統合テスト、ステージング検証、段階的ロールアウトに約 6 週間を確保するため、2026 年 6 月 15 日までに各環境で準備が整う必要があります。最終形・洗練された状態である必要はなく、形式や形態を問わず MUST 要件を満たすことが求められます。

要件レベル

本ドキュメントでは RFC 2119 のキーワードを使用します。MUST、MUST NOT、SHOULD、SHOULD NOT、MAY が要件レベルを示します。

インフラ要件

カーディナリティ

1 つの AR アプリケーションは、各々ちょうど 1 つに接続します。

コンポーネント	互換性	カーディナリティ
リレーショナルデータベース	PostgreSQL 互換	1:1
オブジェクトストレージ	GCS または S3 互換	1:1
キーバリューストア	Redis 互換	1:1

AR は、アプリケーションレベルで複数のデータベース、バケット、キーバリューインスタンスにシャードする必要が MUST NOT あってはなりません。インフラレイヤーが単一の論理エンドポイントの背後で複数の物理バックエンド（プロキシ、コネクションプーラーなど）を提供する場合、それは AR にとって透過的であり、調整なしに MAY 行われてよいものとします。

分離レベル

コンポーネント	MUST	SHOULD
オブジェクトストレージ	専用バケット。他のモジュールとバケットを共有しては MUST NOT いけません。	N/A
リレーショナルデータベース	独自のスキーマ、マイグレーション、認証情報を持つ専用の論理データベース。他のモジュールはクロスデータベースアクセスを MUST NOT 持ってはいけません。	別個の物理インスタンス。
キーバリューストア	別個の論理キースペース（独自のデータベースインデックスまたは ACL）。他のモジュールは AR のキーに MUST NOT アクセスしてはいけません。	別個の物理インスタンス。

MVP のスコープには含まれませんが、AR は可用性、フォールトトレランス、パフォーマンス向上のため、データベースロードバランシング用のリードオンリーレプリカへのアクセスを必要とします。後のマイグレーションを避けるため、データベースをプロビジョニングする際にこれを SHOULD 考慮してください。

バケットを共有してはいけない理由

理由	詳細
ライフサイクルポリシー	AR はアプリケーションレベルの保持（有効期限、クリーンアップ）を管理します。インフラチームは、他のモジュールに影響を与えずに、AR 固有のプラットフォームレベルのバケットポリシー（例: コールドティアリング、ストレージクラス遷移）を MUST 設定できる必要があります。バケットレベルのポリシーはプレフィックスにスコープできません。
CDN 構成	CDN 署名付き URL は、バケットごとのオリジン、キャッシュ動作、署名キーを必要とします。
IAM 分離	アクセスポリシーはバケットレベルです（GCS にはプレフィックスレベルの IAM がありません）。

物理データベースと KV ストアを別途プロビジョニングすべき理由

以下のリスクは、物理バックエンドを他のモジュールと共有する場合の、リレーショナルデータベースとキーバリューストアの両方に当てはまります。

リスク	詳細
リソース競合	AR のバックグラウンド操作（GC、ライフサイクル適用、ストレージアカウンティングのセルフヒーリング）は、長時間トランザクションとテーブルスキャンを伴い、I/O、CPU、メモリで競合します。
ノイジーネイバー	長時間実行の AR マイグレーションや GC スイープは同居モジュールを劣化させ、その逆も成り立ちます。
独立スケーリング	AR のデータはアーティファクトメタデータの量に応じて成長し、他のモジュールとはスケール特性が異なります。共有バックエンドだと独立したスケーリングが困難になります。
マイグレーションリスク	共有で開始して後から分離する場合、負荷下でのデータマイグレーションが必要になり、最初から個別にプロビジョニングするよりはるかにコストが高くリスクも大きくなります。
メモリ圧迫（KV）	AR のキャッシュはアクティブな namespace と並行セッションに応じてスケールします。共有インスタンスでは、モジュール間で予測不能な追い出しが発生します。

決定の如何にかかわらず、AR は共有サーバーから専用サーバーへデータを移動するためのレプリケーション、抽出、マイグレーションロジックを提供する必要が MUST NOT あってはなりません。これはインフラの責務であり、アプリケーションの責務ではありません。モジュールはエンドポイントに接続し、そのエンドポイントの背後でデータがどう移動するかは AR にとって透過的です。

コンピュート

AR は単一の Go バイナリ（API サーバー + バックグラウンドワーカー）で、水平スケールします。

要件	レベル	詳細
別個のデプロイ	MUST	専用の Pod、専用のレプリカ数。他のモジュールと Pod を共有しては MUST NOT いけません。
リソースクォータ	MUST	AR は同居モジュールによってリソースを枯渇させられたり、逆に枯渇させたりしては MUST NOT いけません。
ネットワークポリシー	MUST	モノリス、トポロジサービス、ロードバランサーからの HTTPS インバウンド。データベース、オブジェクトストレージ、KV ストア、CDN、リモートレジストリへのアウトバウンド。

CDN

CDN はすべてのインストールタイプで利用可能とは限りませんが、.com では利用される予定です。AR は AR バケットをオリジンとして CDN 署名付き URL を使用します。CDN が提供される場合、以下の要件が適用されます。

要件	レベル	詳細
モジュールごとのオリジン	MUST	オリジンは AR の専用バケットで MUST あり、共有オリジンであってはいけません。
署名キー	MUST	AR は署名付き URL を生成するために秘密鍵を MUST 必要とします。
キャッシュ無効化	MAY	Blob はコンテンツアドレッサブルかつ不変です。TTL ベースの有効期限で十分と想定されます。

.com への推奨: エンジニアリングチームは、.com に対して GCS + Cloud CDN の組み合わせを強く推奨します。これは GitLab コンテナレジストリを長年にわたり大規模に運用してきた、実績のあるスタックです。GCS は強い整合性保証とパフォーマンス特性（書き込み後即時整合性、単一オブジェクトの compose 操作など）を提供しており、その一部は S3 では利用できません。

DNS と TLS

AR は専用のドメイン（例: artifact-registry.gitlab.com、TBD）でサービスを提供し、メインの GitLab アプリケーションとは別になります。インフラはこのドメインの DNS レコード、TLS 証明書、証明書ローテーションを MUST プロビジョニングする必要があります。

構成とシークレット

AR はすべての設定（エンドポイント、認証情報、機能フラグ）を構成ファイルから読み取ります。シークレット管理は AR にとって透過的で MUST あるべきです。インフラレイヤーが構成ファイルにシークレットを含む正しい値を投入します。AR は特定のシークレットバックエンド（Vault、KMS など）と統合する必要が MUST NOT あってはなりません。シークレットを構成にどう注入するかはインフラの責務です。

データベースコネクションプーリング

データベースの前段にコネクションプーラー（PgBouncer など）を配置しても MAY 構いません。AR は、.com で PgBouncer の背後で動作している GitLab コンテナレジストリと同じパターンに従って、トランザクションモードのプーラーと互換性があるよう設計されています。AR はトランザクションレベルのアドバイザリロック（pg_advisory_xact_lock）を使用し、デフォルトでプリペアドステートメントを無効化してシンプルクエリプロトコルを採用します。

バックアップとディザスタリカバリ

データベースのバックアップ、オブジェクトストレージの耐久性（バージョニング、クロスリージョンレプリケーションなど）、KV ストアの永続化はインフラの責務です。AR は独自のバックアップやリカバリの仕組み、インフラレベルのデータ保護を実装する必要が MUST NOT あってはなりません。関連する詳細は可観測性とレプリケーションとゾーン可用性のセクションを参照してください。

可観測性

AR は LabKit を介してメトリクス、ログ、トレースを発行します。AR は、同居モジュールから独立してトラッキングされるモジュールごとのダッシュボード、アラート、SLI/SLO を MUST 持つ必要があります。

インフラチームはすべてのコンポーネントの健全性、可用性、復旧可能性のオーナーです。AR チームはアプリケーションレベルのインシデントのオーナーであり、モジュールの SLI/SLO を定義します。

キャパシティプランニング

現在の .com ベースラインメトリクスとワークロードプロジェクションは、インフラ契約書に文書化されています。元データは内部キャパシティプランニングノートから得られています。

AR はゼロから開始します: データもユーザーもいません。 コンピュートはレプリカを追加することで水平スケールします。具体的な VM／ノードのサイジング、レプリカ数、リーダー構成はオーナーチームが決定します。MVP 後、AR はロードバランシング用のデータベースリードレプリカが必要になります（分離レベルを参照）。

ルーティングとトポロジ

AR は、ネットワークトポロジを認識する必要が MUST NOT あってはなりません。リクエストルーティングは動的、外部的、アプリケーションに対して透過的で MUST あるべきです。AR はそのエンドポイントでリクエストを受け取り、リクエストがそこに到達する経路はインフラの責務です。

機能	詳細	必要な整合
リクエストルーティング	トポロジサービス（または同等のもの）が URL パス内のスラグに基づいて、インバウンドリクエストを正しい AR デプロイにルーティングします。	ルーティング設定および統合
スラグ要求	唯一の例外: AR は ClaimService gRPC API を介してグローバルに一意なスラグを要求します。これは AR がルーティングレイヤーと相互作用する唯一の地点です。フローは #594637 で議論中です。	Proto 変更および統合タイムライン

継続的デリバリーとリリース

AR は、すべてのインストールタイプ（.com、Dedicated、Self-Managed）にわたって自動化された一貫したリリース・デプロイプロセスを MUST 持つ必要があります。Runway が以前から候補として挙げられており、初期調査では実現可能性が示されています（ソース）。ただし、プロセスが以下の要件を満たす限り、具体的なツール選定は AR にとって関心事ではありません。

要件	レベル	詳細
自動デプロイ	MUST	.com へのデプロイに手動ステップは MUST NOT ありません。
段階的ロールアウト	MUST	リングベースまたは同等のもの。モジュールはステージを独立して進みます。
インストールタイプ間の一貫性	MUST	同じバイナリ、同じリリース成果物を .com、Dedicated、Self-Managed にデプロイします。
独立したリリースサイクル	MUST	AR は、モノリスのリリースサイクルから独立してデプロイ可能で MUST あるべきです。

レプリケーションとゾーン可用性

AR は、自身の物理的な配置、ゾーントポロジ、レプリケーション機構を認識する必要が MUST NOT あってはなりません。AR は単一のデータベース・KV ストアエンドポイントと単一のバケットに接続します。それらのエンドポイントの背後でデータがどうレプリケート・分散・フェイルオーバーされるかは、AR にとって透過的です。

コンポーネントごとの詳細:

オブジェクトストレージ: AR は単一のバケットにコンテンツアドレッサブルな Blob（不変、ダイジェストで識別）を書き込みます。書き込みは冪等です。バケットにクロスリージョンレプリケーション（マルチリージョン GCS バケットでは「無料」）やバージョニングが構成されている場合、それは AR にとって透過的です。AR は、バケットの切り替えやレプリケーションの開始を要求されては MUST NOT いけません。バケットレベルの双方向レプリケーションは互換性があります（不変な Blob にはコンフリクト解決不要）が、それを行うかどうかはプラットフォームの関心事です。

データベース: AR は書き込み用にプライマリ 1 台に接続します。MVP 後、AR は内部的にリードレプリカに読み取りをルーティングします。これらのレプリカのプロビジョニングとレプリケーションはインフラの責務です。AR はレプリカエンドポイントを構成内で必要とします。

KV ストア: AR は単一のエンドポイントに接続します。永続化とレプリケーションはインフラの責務です。

Geo スタイルのレプリケーションは、初期リリースのスコープから外されました。Geo にはマルチテナントモデルがありません。モジュラー機能向けの正しいレプリケーションモデルは、本番での学習に基づいて後で設計されます。