コンテナ仮想レジストリ

プラン: Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated
ステータス: 実験的機能

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

前提条件

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

仮想レジストリを使用するための前提条件を確認してください。

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

トップレベルグループごとに最大5個のコンテナ仮想レジストリを作成できます。
指定されたコンテナ仮想レジストリに設定できるアップストリームは5個だけです。
技術的な理由により、オブジェクトストレージ設定の値がどのように設定されていても、proxy_download設定は強制的に有効になります。
Geoサポートは実装されていません。

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

コンテナ仮想レジストリの作成、編集、削除については、コンテナ仮想レジストリAPIを参照してください。

コンテナ仮想レジストリに対して認証する

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

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

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

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

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

クライアント認証後、クライアントに発行されたJWTトークンは、クライアントがコンテナイメージをプルすることを認可します。
トークンは、その有効期限に準じて失効します。
トークンの有効期限が切れると、ほとんどのDockerクライアントはユーザー認証情報を保存し、それ以上の操作なしで、新しいトークンを自動的にリクエストします。

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

仮想レジストリを介してコンテナイメージをプルするには、次の手順に従います:

仮想レジストリに対して認証します。

仮想レジストリの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. イメージがキャッシュされていて、アップストリームのcache_validity_hours設定に基づいて引き続き有効な場合は、キャッシュからイメージが提供されます。
2. イメージがキャッシュされていないか、キャッシュが無効な場合は、設定されたアップストリームレジストリからイメージがフェッチされ、キャッシュされます。
Dockerクライアントにイメージを提供します。

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

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

代わりに、コンテナ仮想レジストリは次の操作を行います:

アップストリームのcache_validity_hours設定を確認して、イメージマニフェストがいつ無効になるかを判定します。
アップストリームに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)

これらのエラーを解決するには、次の手順に従います:

グループのゲストロール以上を持っていることを確認します。
仮想レジストリIDが正しいことを確認します。
仮想レジストリに少なくとも1つのアップストリームが設定されていることを確認します。
アップストリームレジストリにイメージが存在することを確認します。