GitLabコンテナレジストリのトラブルシューティング

GitLabコンテナレジストリに関するほとんどのイシューをトラブルシューティングするには、管理者権限でGitLabにサインインする必要があります。

GitLab Container Registryの管理ドキュメントに、その他のトラブルシューティング情報があります。

GitLab Container Registry への OCI コンテナイメージのマイグレーション

GitLab レジストリへのコンテナイメージのマイグレーションはサポートされていませんが、エピックはこの動作を変更することを提案しています。

サードパーティのツールを使ってコンテナイメージをマイグレーションすることができます。例えば、skopeo は様々なストレージ機構間でコンテナイメージをコピーすることができます。skopeo を使って、コンテナレジストリ、コンテナストレージバックエンド、ローカルディレクトリ、ローカル OCI-layout ディレクトリから GitLab コンテナレジストリにコピーすることができます。

Docker接続エラー

Docker接続エラーは、グループ名、プロジェクト名、ブランチ名のいずれかに特殊文字が含まれている場合に発生する可能性があります。特殊文字には以下のようなものがあります：

  • 先頭のアンダースコア。
  • 末尾のハイフンまたはダッシュ

このエラーを解決するには、グループパス、プロジェクトパス、ブランチ名を変更してください。

Docker Engine 17.11以前を使用している場合、404 Not Found またはUnknown Manifest のエラーメッセージが表示されることがあります。現在のバージョンのDocker Engineはv2 APIを使用しています。

GitLabコンテナレジストリ内のイメージは、Docker v2 APIを使用する必要があります。バージョン1のイメージをバージョン2にアップデートする方法については、Dockerのドキュメントを参照してください。

Blob unknown to registry マニフェストリストをプッシュする際のエラー

DockerマニフェストリストをGitLabコンテナレジストリにプッシュする際に、manifest blob unknown: blob unknown to registry というエラーを受け取ることがあります。このエラーは、アーキテクチャの異なる複数のイメージが、同じリポジトリではなく複数のリポジトリに分散しているために発生する可能性があります。

例えば、2つのイメージがあり、それぞれがアーキテクチャを表しているとします：

  • amd64 。
  • arm64v8 。

これらのイメージを使って multi-arch イメージを構築するには、それらを multi-arch イメージと同じリポジトリにプッシュする必要があります。

Blob unknown to registry のエラーにアドレスするには、個々のイメージのタグ名にアーキテクチャを含めます。たとえば、mygroup/myapp:1.0.0-amd64 とmygroup/myapp:1.0.0-arm64v8を使用します。次に、マニフェストリストにmygroup/myapp:1.0.0をタグ付けします。

プロジェクトのパスを変更できない、またはプロジェクトを転送できない

プロジェクト・パスを変更したり、プロジェクトを新しいネームスペースに転送しようとすると、以下のエラーのいずれかが発生することがあります：

  • コンテナ・レジストリにタグが存在するため、プロジェクトを転送できません。
  • 少なくとも 1 つのプロジェクトがコンテナ・レジストリにタグを持っているため、ネームスペースを移動できません。

このエラーは、プロジェクトがコンテナ・レジストリにイメージを持っている場合に発生します。パスを変更したりプロジェクトを転送したりする前に、これらのイメージを削除または移動する必要があります。

以下の手順では、これらのサンプルプロジェクト名を使用します：

  • 現在のプロジェクトの場合：gitlab.example.com/org/build/sample_project/cr:v2.9.1.
  • 新しいプロジェクトについて:gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1.

  1. Dockerイメージをコンピューターにダウンロードします：

    docker login gitlab.example.com
docker pull gitlab.example.com/org/build/sample_project/cr:v2.9.1
    note
    個人アクセストークンまたはデプロイトークンを使用して、ユーザーアカウントを認証します。

  2. 新しいプロジェクト名に合わせてイメージの名前を変更します：

    docker tag gitlab.example.com/org/build/sample_project/cr:v2.9.1 gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1
  3. UIまたはAPIを使って、古いプロジェクトの画像を削除します。画像がキューに入れられ、削除されるまでに時間がかかる場合があります。

  4. パスを変更するか、プロジェクトを転送してください：

    1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
    2. 設定] > [全般]を選択します。
    3. 詳細」セクションを展開します。
    4. Change path（パスの変更）テキストボックスで、パスを編集します。
    5. パスの変更］を選択します。

  5. 画像を復元します：

    docker push gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1

詳しくはイシューをご覧ください。

unauthorized: authentication required 大きな画像をプッシュする場合

大きな画像をプッシュする際、以下のような認証エラーが表示されることがあります：

docker push gitlab.example.com/myproject/docs:latest
The push refers to a repository [gitlab.example.com/myproject/docs]
630816f32edb: Preparing
530d5553aec8: Preparing
...
4b0bab9ff599: Waiting
d1c800db26c7: Waiting
42755cf4ee95: Waiting
unauthorized: authentication required

このエラーは、イメージのプッシュが完了する前に認証トークンが切れてしまった場合に発生します。デフォルトでは、セルフマネージドGitLabインスタンスのコンテナレジストリのトークンは5分ごとに期限が切れます。GitLab.comでは、トークンの有効期限は15分に設定されています。

セルフマネージド GitLab を使用している場合は、管理者がトークンの有効時間を長くすることができます。