コンテナ仮想レジストリ

GitLabコンテナ仮想レジストリは、アップストリームレジストリからコンテナイメージをキャッシュするために使用できるローカルプロキシです。これはプルスルーキャッシュとして機能し、頻繁にアクセスされるイメージをローカルに保存して、帯域幅の使用量を削減し、ビルドパフォーマンスを向上させます。

前提条件

コンテナ仮想レジストリを使用する前に:

• 仮想レジストリを使用するための前提条件を確認してください。
• バーチャルレジストリへの認証を設定します。詳細については、仮想レジストリへの認証を参照してください。

コンテナ仮想レジストリを使用する場合は、次の制限事項に注意してください:

• トップレベルグループごとに最大5個のコンテナ仮想レジストリを作成できます。
• 指定されたコンテナ仮想レジストリに設定できるアップストリームは5個のみです。
• Geoサポートは実装されていません。

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

グループのコンテナバーチャルレジストリを管理します。

APIを使用することもできます。

コンテナバーチャルレジストリの作成

コンテナバーチャルレジストリを作成するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. デプロイ > バーチャルレジストリを選択します。
3. 次のいずれかの場合:
   • 既存のレジストリがある場合は、レジストリを作成を選択します。ドロップダウンリストから、コンテナを選択します。
   • 既存のレジストリがない場合は、ドロップダウンリストからコンテナを選択します。次に、レジストリを作成を選択します。
4. 名前とオプションの説明を入力します。
5. レジストリを作成を選択します。

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

バーチャルレジストリ内のアップストリームコンテナレジストリを管理します。

コンテナアップストリームレジストリの作成

バーチャルレジストリに接続するためのコンテナアップストリームレジストリを作成します。

前提条件:

• コンテナバーチャルレジストリが必要です。詳細については、バーチャルレジストリの作成を参照してください。

コンテナアップストリームレジストリを作成するには:

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

2. デプロイ > バーチャルレジストリを選択します。

3. レジストリタイプで、レジストリの表示を選択します。

4. レジストリタブで、レジストリを選択します。

5. アップストリームの追加を選択します。バーチャルレジストリに既存のアップストリームがある場合は、ドロップダウンリストから次のいずれかを選択します:

   • 新しいアップストリームを作成を選択して、アップストリームを設定します。
   • 既存のアップストリームをリンク > Select existing upstream。
     1. ドロップダウンリストからアップストリームを選択します。
     2. オプション。オプション。アップストリームのテストを選択して、アップストリーム接続を作成する前にテストします。
     3. アップストリームの追加を選択します。

6. フィールドに入力します。

   • ユーザー名とpasswordの両方、またはどちらも指定しません。設定されていない場合、パブリック（匿名）リクエストを使用してアップストリームにアクセスします。

   • アップストリームをDocker Hardened Imagesに接続する場合は、アップストリームのURLとして以下を使用します:

     https://dhi.io

   • アーティファクトのキャッシュ期間は24時間にデフォルト設定されています。0に設定すると、キャッシュエントリのチェックが無効になります。

   • アップストリーム接続を作成する前にテストする場合は、アップストリームのテストを選択します。

7. アップストリームを作成を選択します。

キャッシュの有効期間設定の詳細については、キャッシュの有効期間を設定を参照してください。

コンテナ仮想レジストリで認証

コンテナ仮想レジストリは、トップレベルグループに関連付けられたレジストリにコンテナイメージを保存して関連付けます。コンテナイメージにアクセスするには、グループのコンテナ仮想レジストリで認証する必要があります。

手動で認証するには、次のコマンドを実行します:

echo "$CONTAINER_REGISTRY_PASSWORD" | docker login gitlab.example.com/virtual_registries/container/1 --username <your_username> --password-stdin

または、仮想レジストリへの認証で説明されているいずれかの方法で設定を行います。

コンテナ仮想レジストリは、Docker v2トークン認証フローに従います:

1. クライアント認証後、クライアントに発行されたJWTトークンは、クライアントがコンテナイメージをプルすることを承認します。
2. トークンは、その有効期限に従って有効期限が切れます。
3. トークンの有効期限が切れると、ほとんどのDockerクライアントはユーザー認証情報を保存し、それ以上の操作なしに自動的に新しいトークンを要求します。

仮想レジストリからコンテナイメージをプルする

仮想レジストリを介してコンテナイメージをプルするには:

1. 仮想レジストリで認証します。

2. コンテナイメージをプルするには、仮想レジストリのURL形式を使用します:

   gitlab.example.com/virtual_registries/container/<registry_id>/<image_path>:<tag>

例:

• タグでイメージをプル:

  docker pull gitlab.example.com/virtual_registries/container/1/library/alpine:latest

• ダイジェストでイメージをプル:

  docker pull gitlab.example.com/virtual_registries/container/1/library/alpine@sha256:c9375e662992791e3f39e919b26f510e5254b42792519c180aad254e6b38f4dc

• Dockerfileでイメージをプル:

  FROM gitlab.example.com/virtual_registries/container/1/library/alpine:latest

• .gitlab-ci.ymlファイルでイメージをプル:

  image: gitlab.example.com/virtual_registries/container/1/library/alpine:latest

コンテナイメージをプルすると、仮想レジストリは次のようになります:

1. イメージが既にキャッシュされているかどうかを確認します。
   1. イメージがキャッシュされていて、アップストリームのcache_validity_hours設定に基づいてまだ有効な場合、イメージはキャッシュから提供されます。
   2. イメージがキャッシュされていないか、キャッシュが無効な場合、設定されたアップストリームレジストリからイメージがフェッチされ、キャッシュされます。
2. Dockerクライアントにイメージを提供します。

コンテナイメージの仮想レジストリキャッシュ検証

alpine:latestのようなイメージタグは、常に最新バージョンのイメージをプルします。新しいバージョンには、更新されたイメージマニフェストが含まれています。コンテナ仮想レジストリは、マニフェストが変更されても新しいイメージをプルしません。

代わりに、コンテナ仮想レジストリは次のようになります:

1. アップストリームのcache_validity_hours設定を確認して、イメージマニフェストが無効になる時期を判断します。
2. アップストリームにHEADリクエストを送信します。マニフェストが無効な場合、新しいイメージがプルされます。

たとえば、パイプラインがnode:latestプルし、cache_validity_periodを24時間に設定した場合、仮想レジストリはイメージをキャッシュし、キャッシュが期限切れになるか、アップストリームでnode:latestが変更されたときにイメージを更新します。

トラブルシューティング

認証エラー：HTTP Basic: Access Denied

仮想レジストリに対して認証を行うときにHTTP Basic: Access deniedエラーが発生した場合は、2要素認証のトラブルシューティングを参照してください。

仮想レジストリ接続失敗

サービスエイリアスが設定されていない場合、docker:20.10.16イメージはdindサービスを見つけることができず、次のようなエラーがスローされます:

error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host

このエラーを解決するには、Dockerサービスのサービスエイリアスを設定します:

services:
  - name: docker:20.10.16-dind
    alias: docker

CI/CDジョブからの仮想レジストリ認証の問題

GitLab Runnerは、CI/CDジョブトークンを使用して自動的に認証します。ただし、基盤となるDockerエンジンは、引き続き承認解決プロセスの対象となります。

認証メカニズムの設定ミスにより、HTTP Basic: Access deniedおよび403: Access forbiddenエラーが発生する可能性があります。

ジョブログを使用して、仮想レジストリに対する認証に使用される認証メカニズムを表示できます:

Authenticating with credentials from $DOCKER_AUTH_CONFIG

Authenticating with credentials from /root/.docker/config.json

Authenticating with credentials from job payload (GitLab Registry)

想定される認証メカニズムを使用していることを確認してください。

イメージのプル時のNot Foundまたは404エラー

このようなエラーは、次のことを示している可能性があります:

• ジョブを実行しているユーザーが、バーチャルレジストリを所有するグループのゲスト、プランナー、レポーター、デベロッパー、メンテナー、またはオーナーのロールを持っていません。
• URL内の仮想レジストリIDが正しくありません。
• アップストリームレジストリにリクエストされたイメージが含まれていません。
• 仮想レジストリに設定されたアップストリームがありません。

エラーメッセージの例:

ERROR: gitlab.example.com/virtual_registries/container/1/library/alpine:latest: not found

ERROR: Job failed: failed to pull image "gitlab.example.com/virtual_registries/container/1/library/alpine:latest" with specified policies [always]:
Error response from daemon: error parsing HTTP 404 response body: unexpected end of JSON input: "" (manager.go:237:1s)

これらのエラーを解決するには:

1. グループのゲスト、プランナー、レポーター、デベロッパー、メンテナー、またはオーナーのロールを持っていることを確認します。
2. 仮想レジストリIDが正しいことを確認します。
3. 仮想レジストリに、少なくとも1つの設定されたアップストリームがあることを確認します。
4. イメージがアップストリームレジストリに存在することを確認します。