Artifact Registry でコンテナ イメージを管理する際に問題が発生した場合に役立つトラブルシューティング手順について説明します。
イメージの pull や Google Cloud ランタイム環境へのデプロイができない
以下をご確認ください。
push するイメージのフルパスが正しいことを確認します。パスには、レジストリ ホスト名、Google Cloud プロジェクト ID、リポジトリ、イメージを含める必要があります。次に例を示します。
us-east1-docker.pkg.dev/my-project/my-repo/my-image:v1
詳細については、リポジトリとイメージの名前をご覧ください。
イメージを pull しているアカウントに、リポジトリから読み取る権限があることを確認します。
- Cloud Build のデフォルトのサービス アカウントには、同じ Google Cloud プロジェクト内のリポジトリに対する読み取りと書き込みの権限があります。ユーザー指定のサービス アカウントを使用している場合、またはプロジェクト間でイメージを push および pull する場合は、ビルドを実行するサービス アカウントに Artifact Registry 書き込みロールを付与します。
- デフォルトでは、Compute Engine、Cloud Run、Google Kubernetes Engine には、同じプロジェクト内のリポジトリに対する読み取り権限があります。Artifact Registry がランタイム環境とは異なるプロジェクトにある場合、ランタイム サービス アカウントに Artifact Registry 読み取りロールを付与する必要があります。
Docker や他のサードパーティ ツールを使用している場合は、次のことを行う必要があります。
- リポジトリを操作するアカウントに権限を付与します。
リポジトリに対する認証を行うようにクライアントを構成します。
イメージを Artifact Registry に push できない
以下をご確認ください。
リポジトリが存在することを確認します。Container Registry とは異なり、リポジトリの作成は、最初のイメージを push するオペレーションとは別のものです。ログが存在しない場合は、作成します。
push するイメージのフルパスが正しいことを確認します。パスには、レジストリ ホスト名、Google Cloud プロジェクト ID、リポジトリ、イメージを含める必要があります。次に例を示します。
us-east1-docker.pkg.dev/my-project/my-repo/my-image:v1
それぞれの Artifact Registry リポジトリは個別のリソースであるため、リポジトリのないパスにイメージを push することはできません。たとえば、
us-east1-docker.pkg.dev/my-project/my-image:v1
は無効なイメージパスです。詳細については、リポジトリとイメージの名前をご覧ください。
イメージを push するアカウントに、リポジトリへの書き込み権限があることを確認します。
- Cloud Build のデフォルトのサービス アカウントには、同じ Google Cloud プロジェクト内のリポジトリに対する読み取りと書き込みの権限があります。ユーザー指定のサービス アカウントを使用している場合、またはプロジェクト間でイメージを push および pull する場合は、ビルドを実行するサービス アカウントに Artifact Registry 書き込みロールを付与します。
- デフォルトでは、Compute Engine、Cloud Run、Google Kubernetes Engine には、同じプロジェクト内のリポジトリに対する読み取り権限があります。これらの環境でサードパーティのツールを使用してイメージを push している場合は、Artifact Registry 書き込みロールをランタイム サービス アカウントに付与する必要があります。
Artifact Registry から「
The repository has enabled tag immutability
」というメッセージが返された場合は、リポジトリにタグの不変性が構成されています。リポジトリ内の同じイメージの別のバージョンですでに使用されているタグを使用してイメージを push することはできません。保存されている他のバージョンのイメージで使用されていないタグを使用して、イメージを再度 push してみてください。リポジトリが不変のイメージタグ用に構成されていることを確認するには、Google Cloud コンソールのリポジトリのリストにある [不変のイメージタグ] 列を確認するか、次のコマンドを実行します。
gcloud artifacts repositories describe REPOSITORY --project=PROJECT-ID --location=LOCATION
ImagePullBackOff メッセージと ErrImagePull メッセージ
ImagePullBackOff
と ErrImagePull
を含むメッセージは、GKE によってレジストリからイメージを pull できないことを示しています。
- Artifact Registry から pull するための要件を確認する。
- GKE のドキュメントのトラブルシューティングの手順を確認します。