仮想レジストリ

複数のアップストリームレジストリからのパッケージを、単一のよく知られたURLの背後でプロキシおよびキャッシュするためにGitLabバーチャルレジストリを使用します。

このアプローチにより、複数のアップストリームレジストリの代わりに、単一のバーチャルレジストリを使用するようにアプリケーションを設定できます。

前提条件

バーチャルレジストリを設定するには:

• トップレベルグループでメンテナーまたはオーナーのロールが必要です。
• バーチャルレジストリの設定を有効にしてください。デフォルトで有効になっていますが、管理者はオフにすることができます。
• 依存プロキシの設定を有効にしてください。デフォルトで有効になっていますが、管理者はオフにすることができます。
• サポートされているパッケージフォーマットの認証を設定する必要があります。

バーチャルレジストリをオフにする

バーチャルレジストリはデフォルトでオンになっています。

前提条件:

• バーチャルレジストリをオフにするには、管理者である必要があります。

バーチャルレジストリをオフにするには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 設定 > パッケージとレジストリを選択します。
3. Virtual Registryの下で、Enable Virtual Registryトグルをオフにします。

サポートされているパッケージフォーマット

• Mavenパッケージ
• コンテナイメージ

バーチャルレジストリに認証する

バーチャルレジストリエンドポイントは、以下のトークンのいずれかで使用できます:

• パーソナルアクセストークン。
• 検討対象のバーチャルレジストリをホストするトップレベルグループのグループデプロイトークン。
• 検討対象のバーチャルレジストリをホストするトップレベルグループのグループアクセストークン。
• CI/CDジョブトークン。

トークンには、以下のスコープのいずれかが必要です:

• api
• read_virtual_registry

アクセストークンとCI/CDジョブトークンはユーザーに解決されます。解決されたユーザーは次のいずれかである必要があります:

• ゲスト、プランナー、レポーター、デベロッパー、メンテナー、またはオーナーのロールを持つトップレベルグループの直接のメンバー。
• GitLabインスタンス管理者。
• トップレベルグループに含まれるプロジェクトのいずれかの直接のメンバー。

仮想レジストリを管理する

トップレベルグループのバーチャルレジストリを管理します。

バーチャルレジストリの作成

サポートされているパッケージフォーマットのいずれかについてバーチャルレジストリを作成できます。

バーチャルレジストリを作成すると:

• レジストリは、特定のパッケージフォーマットのトップレベルグループでホストされます。プロジェクトとサブグループはサポートされていません。
• バーチャルレジストリオブジェクトは、利用可能なアップストリームの順序付きリスト (最大20) にリンクします。各アップストリームは外部レジストリを指します。
• 外部レジストリは公開または非公開にできます。プライベートレジストリの認証情報はアップストリーム自体に保存されるため、パッケージマネージャーの設定に保存する必要はありません。

バーチャルレジストリの表示

バーチャルレジストリを表示するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. デプロイ > バーチャルレジストリを選択します。

バーチャルレジストリの編集

既存のバーチャルレジストリを編集するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプの下で、レジストリの表示を選択します。
4. 編集したいレジストリの行で、編集 ( ) を選択します。
5. 変更を加えて変更を保存を選択します。

仮想レジストリを削除する

バーチャルレジストリを削除するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプの下で、レジストリの表示を選択します。
4. レジストリタブの下で、削除したいレジストリの行で、編集 ( ) を選択します。
5. レジストリの削除を選択します。
6. 確認ダイアログで、削除を選択します。

アップストリームレジストリを管理する

トップレベルグループのバーチャルレジストリでアップストリームレジストリを管理します。

アップストリームレジストリの表示

アップストリームレジストリを表示するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプの下で、レジストリの表示を選択します。
4. 利用可能なすべてのアップストリームを表示するには、アップストリームタブを選択します。

アップストリームレジストリの編集

アップストリームレジストリを編集するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプの下で、レジストリの表示を選択します。
4. アップストリームタブを選択します。
5. 編集したいアップストリームの行で、編集 ( ) を選択します。
6. 変更を加えて変更を保存を選択します。

アップストリームレジストリの順序変更

アップストリームレジストリの順序は、パッケージがクエリされる際の優先順位を決定します。

アップストリームレジストリの順序を変更するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. デプロイ > Virtual registriesを選択します。
3. レジストリタイプの下で、レジストリの表示を選択します。
4. レジストリタブの下で、レジストリを選択します。
5. アップストリームの下で、アップストリームを並べ替えるためにアップストリームを上に移動またはアップストリームを下に移動を選択します。

アップストリームの順序付けに関するベストプラクティス:

• 内部パッケージを優先するために、公開レジストリの前にプライベートレジストリを配置します。
• 最も多くのパッケージを持つレジストリをリストの最上位に優先します。このアプローチは次のことを可能にします。
  • 高優先度のレジストリがリクエストを満たす可能性が高まります。
  • 有効なアップストリームレジストリを見つけるために、順序付けされたリスト全体をたどることを防ぎます。
• より高速または信頼性の高いレジストリをリストの上位に配置します。
• 公開依存のフォールバックとして、公開レジストリを最後に配置します。
• 最も少ないパッケージを持つレジストリをリストの最下部に配置します。

アップストリームの順序の詳細については、アップストリームの優先順位を参照してください。

キャッシュシステム

すべてのアップストリームレジストリには、以下のキャッシュシステムがあります:

• リクエストをキャッシュエントリに保存します。
• 同じリクエストに対するレスポンスをGitLabバーチャルレジストリから提供します。

このようにして、同じパッケージがリクエストされたときに、バーチャルレジストリがアップストリームに再度連絡する必要がなくなります。

リクエストされたパスが利用可能なアップストリームのいずれにもキャッシュされていない場合:

1. バーチャルレジストリは、リクエストを満たすことができるアップストリームを見つけるために、順序付けされたアップストリームのリストをたどります。
2. リクエストを満たすことができるアップストリームが見つかった場合、バーチャルレジストリは必要に応じて提供された認証情報を使用して、アップストリームからレスポンスをプルします。

リクエストされたパスが利用可能なアップストリームのいずれかにキャッシュされている場合:

1. バーチャルレジストリは、レスポンスを転送する前に、キャッシュエントリが更新する必要があるかどうかを確認するためにキャッシュの有効期間をチェックします。
2. キャッシュが有効な場合、アップストリームのキャッシュエントリがリクエストを満たします。
   • 低い優先順位のアップストリームがキャッシュ内にリクエストを持ち、高い優先順位のアップストリームがファイルを含むがリクエストをキャッシュしていない場合、低い優先順位のアップストリームがリクエストを満たします。バーチャルレジストリは、順序付けされたアップストリームのリストを再度たどることはありません。

バーチャルレジストリは、リクエストを満たすアップストリームを見つけられない場合、404 Not Foundエラーを返します。

キャッシュの有効期間

キャッシュの有効期間は、キャッシュエントリがリクエストを満たすために有効とみなされる時間（時間単位）を設定します。

バーチャルレジストリは、既存のキャッシュエントリからプルする前に、キャッシュの有効期間をチェックして、エントリが更新される必要があるかどうかを判断します。

エントリが有効期間外の場合、バーチャルレジストリはアップストリームのレスポンスがキャッシュ内のものと同一であるかどうかをチェックします。もし:

• レスポンスが同一の場合、そのエントリがリクエストを満たすために使用されます。
• レスポンスが同一でない場合、アップストリームのキャッシュエントリを上書きするために、レスポンスはアップストリームから再度ダウンロードされます。

ネットワーク状況によりバーチャルレジストリがアップストリームに接続できない場合、アップストリームは利用可能なキャッシュエントリでリクエストに応答します。

バーチャルレジストリがキャッシュ内にリクエストに関連するレスポンスを持っている限り、そのリクエストは有効期間外であっても満たされます。

キャッシュの有効期間を設定する

キャッシュの有効期間は、リクエストを満たすためのバーチャルレジストリの全体的なパフォーマンスにおいて重要です。外部レジストリへの連絡はコストのかかる操作です。有効期間が短いほどチェックの回数が増え、長いほど減ります。

キャッシュの有効性チェックを0に設定することでオフにできます。

キャッシュ有効期間のデフォルト値は24時間です。

アップストリームによってターゲットとされた外部レジストリがイミュータブルなレスポンスを持つことが分かっている場合、キャッシュの有効期間を0に設定する必要があります。これは公式の公開レジストリでよくあるケースです。詳細については、サポートされているパッケージフォーマットを確認してください。

アップストリームを作成または編集する際に、キャッシュの有効期間を設定します。

キャッシュされたパッケージの表示

アップストリームレジストリからキャッシュされたパッケージを表示するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプの下で、レジストリの表示を選択します。
4. アップストリームタブの下で、アップストリームを選択します。
5. キャッシュされたパッケージのキャッシュメタデータを表示します。

キャッシュエントリの削除

キャッシュエントリを削除するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプの下で、レジストリの表示を選択します。
4. レジストリタブの下で、レジストリを選択します。
5. アップストリームの横にある全てのキャッシュのクリアを選択します。
   • 特定のキャッシュエントリを削除するには、アップストリームの横にあるキャッシュをクリアを選択します。

キャッシュエントリを削除すると、次回バーチャルレジストリがそのファイルに対するリクエストを受信したときに、リクエストを満たすことができるアップストリームを見つけるために、アップストリームのリストを再度たどります。

オブジェクトストレージの使用量

キャッシュエントリは、ファイルをオブジェクトストレージのdependency_proxyバケットに保存します。

オブジェクトストレージの使用量は、トップレベルグループのオブジェクトストレージの使用制限としてカウントされます。

クリーンアップポリシー

バーチャルレジストリは、パフォーマンスと可用性を向上させるために、アップストリームレジストリからパッケージをキャッシュします。時間が経つにつれて、これらのキャッシュエントリは蓄積され、かなりのストレージスペースを消費する可能性があります。クリーンアップポリシーを使用して、キャッシュされたコンテンツを自動的に管理し、ストレージの使用量を削減します。

クリーンアップポリシーは、設定可能なルールに基づいてキャッシュエントリを削除するスケジュールされたジョブです。クリーンアップポリシーが実行されると、最近ダウンロードされていないキャッシュエントリを特定し、ストレージから削除します。

クリーンアップポリシーは、トップレベルグループ内のすべてのバーチャルレジストリに対して設定されます。

クリーンアップポリシーワークフロー

バーチャルレジストリでは、クリーンアップポリシーは次のとおりです:

1. 指定された保持期間内にダウンロードされていないキャッシュエントリを特定します。
2. 未使用のキャッシュエントリをオブジェクトストレージから削除します。
3. パフォーマンスを維持するために、頻繁にアクセスされるキャッシュエントリを保持します。

クリーンアップポリシーは、アップストリームレジストリからのキャッシュされたコンテンツのみに影響します。以下のものには影響しません:

• バーチャルレジストリ設定
• アップストリームレジストリ設定
• プロジェクトのパッケージレジストリに保存されているパッケージ

クリーンアップポリシーの管理

トップレベルグループのバーチャルレジストリのクリーンアップポリシーを管理します。各トップレベルグループには、そのグループ内のすべてのバーチャルレジストリに適用されるクリーンアップポリシーを1つまで持つことができます。

クリーンアップポリシーを作成する

クリーンアップポリシーを作成し、実行頻度を設定します。

前提条件:

• トップレベルグループのオーナーロールが必要です。
• グループに対してバーチャルレジストリがオンになっている必要があります。

クリーンアップポリシーを作成するには:

1. 上部のバーで、検索または移動先を選択し、グループを見つけます。このグループはトップレベルにある必要があります。
2. 設定 > パッケージとレジストリを選択します。
3. バーチャルレジストリキャッシュのクリーンアップポリシーの横にあるポリシーの設定を選択します。
4. クリーンアップポリシーを有効化トグルをオンにします。
5. クリーンアップポリシーの設定を構成します:
   • クリーンアップの実行ドロップダウンリストから、クリーンアップポリシーの実行頻度を選択します。デフォルトは毎日です。
   • **アクセスされていないキャッシュを削除(日数)**の下で、未使用のキャッシュエントリが削除される頻度を設定するための数値を入力します。デフォルトは7日です。1から365の間である必要があります。
   • オプション。オプション。メール通知の下で、メールでの通知を受け取るために、以下のチェックボックスのいずれかまたは両方を選択します:
     • クリーンナップを実行したときにメールで通知する
     • クリーンアップが失敗したときにメールで通知する
6. 変更を保存を選択します。

クリーンアップポリシーの編集

クリーンアップポリシーを編集して、ポリシーの実行頻度を決定します。

前提条件:

• トップレベルグループのオーナーロール。

クリーンアップポリシーを編集するには:

1. 上部のバーで、検索または移動先を選択し、グループを見つけます。このグループはトップレベルにある必要があります。
2. 設定 > パッケージとレジストリを選択します。
3. バーチャルレジストリキャッシュのクリーンアップポリシーの横にあるポリシーを編集を選択します。
4. クリーンアップポリシーに変更を加えます。
5. 変更を保存を選択します。

クリーンアップポリシーをオフにする

トップレベルグループのクリーンアップポリシーをオフにします。オフにすると、クリーンアップポリシーは設定を保持しますが、実行されません。既存のキャッシュエントリは保持されます。

前提条件:

• トップレベルグループのオーナーロール。

クリーンアップポリシーをオフにするには:

1. 上部のバーで、検索または移動先を選択し、グループを見つけます。このグループはトップレベルにある必要があります。
2. 設定 > パッケージとレジストリを選択します。
3. バーチャルレジストリキャッシュのクリーンアップポリシーの横にあるポリシーを編集を選択します。
4. クリーンアップポリシーを有効化トグルをオフにします。
5. 変更を保存を選択します。

クリーンアップポリシー設定

クリーンアップポリシーを制御するために、以下の設定を使用します:

• ケイデンス: クリーンアップポリシーの実行頻度を制御します。利用可能なオプションには、毎日、毎週、毎月の間隔が含まれます。
• 保持期間: キャッシュエントリが最後にダウンロードされてから保持される期間を決定します。この期間内にダウンロードされていないエントリは削除の対象となります。

クリーンアップポリシーの実行を監視する

クリーンアップポリシーが実行された後、以下の実行メトリクスを表示できます:

• ポリシーが最後に実行された日時。
• ポリシーが次に実行される予定日時。
• 削除されたキャッシュエントリの数。
• 解放されたストレージスペースの合計。
• 実行中に発生したエラー。

これらのメトリクスは、クリーンアップポリシーの有効性を理解し、必要に応じて設定を調整するのに役立ちます。

パフォーマンスに関する考慮事項

バーチャルレジストリのパフォーマンスは、次のような要因によって異なる場合があります:

• 要求されたファイルがアップストリームレジストリからキャッシュされているかどうか。
• アップストリームレジストリがファイルが存在するかどうかにどれだけ迅速に応答できるか。
• どのクライアントが依存をプルしているか、およびクライアントとGitLabインスタンスとの近接性。

トレードオフ

バーチャルレジストリは公開レジストリよりも高度です。バーチャルレジストリで依存をプルする場合、公開の公式レジストリなど、他のレジストリよりも時間がかかる場合があります。

公開レジストリと比較して、バーチャルレジストリは複数のアップストリームレジストリと認証もサポートしています。

アップストリームの優先順位

アップストリームレジストリは順序付けられたリストで構成されています。バーチャルレジストリがパッケージに対するリクエストを受信すると:

• レジストリは、リクエストを満たすことができるアップストリームを見つけるために、順序付けされたアップストリームのリストをたどります。
• 要求されたファイルがアップストリームで見つかった場合、バーチャルレジストリはそのファイルを返し、将来のリクエストのためにキャッシュします。バーチャルレジストリを介して少なくとも一度プルした場合、キャッシュは依存の可用性を高めます。
• 要求されたファイルがキャッシュで見つからない場合、バーチャルレジストリは、リクエストを満たすことができる最も高い優先順位のアップストリームを見つけるために、順序付けされたリストをたどります。

このシステムは、バーチャルレジストリのパフォーマンスに顕著な影響を与えます。

使用によるパフォーマンス向上

バーチャルレジストリを作成すると、設定された各アップストリームのキャッシュは空になります。各リクエストは、リクエストを満たすために、バーチャルレジストリが利用可能なアップストリームレジストリのリストをたどる必要があります。これらの最初のリクエストは、満たすまでにより時間がかかります。

アップストリームレジストリがリクエストをキャッシュすると、同じリクエストを満たすまでの時間が短縮されます。時間が経つにつれて、より多くのアップストリームレジストリがより多くのリクエストをキャッシュするため、バーチャルレジストリの全体的なパフォーマンスが向上します。

CI/CDキャッシュを使用する

GitLab CI/CDでのキャッシュを使用することで、ジョブがバーチャルレジストリから依存をダウンロードする必要がなくなります。

この方法は実行時間を改善しますが、各依存のストレージを複製することにもなります（依存はCI/CDキャッシュとバーチャルレジストリに保存されます）。