コンテナ イメージに関する問題のトラブルシューティング

Artifact Registry でコンテナ イメージを管理する際に問題が発生した場合に役立つトラブルシューティング手順について説明します。

Docker CLI のプロジェクト ID の構文

Docker ではコロンが特殊文字として扱われるため、Docker CLI を使用する場合は、プロジェクト ID のコロン（:）をスラッシュ（/）に置き換える必要があります。 詳細については、ドメイン スコープのプロジェクトをご覧ください。

イメージの pull や a Google Cloud ランタイム環境へのデプロイができない

以下をご確認ください。

1. push するイメージのフルパスが正しいことを確認します。パスには、レジストリのホスト名、 Google Cloud プロジェクト ID、リポジトリ、イメージを含める必要があります。次に例を示します。

   us-west1-docker.pkg.dev/my-project/my-repo/my-image:v1

   詳細については、リポジトリとイメージ名をご覧ください。
2. イメージを pull するアカウントに、リポジトリから読み取るための正しい 権限があることを確認します。サービス アカウントへの ロールの自動付与を無効にしている場合は、 ランタイム サービス アカウントに Artifact Registry ロールを付与する必要があります。
• Compute Engine、Cloud Run、Google Kubernetes Engine のサービス アカウントの場合は、ランタイム サービス アカウントに Artifact Registry 閲覧者ロール（roles/artifactregistry.reader）を付与する必要があります。
• Cloud Build サービス アカウントの場合は、ビルドを実行するサービス アカウントに Artifact Registry 書き込みロール（roles/artifactregistry.writer）を付与する必要があります。
• Docker または他のサードパーティ ツールを使用している場合は、次の操作を行う必要があります。
  • 権限を付与するリポジトリとやり取りするアカウントに 。
  • リポジトリに対する認証を行うようにクライアントを構成する。
    • Docker 認証の手順
    • Google Kubernetes Engine での containerd ノードイメージのトラブルシューティング

イメージを Artifact Registry に push できない

次のようにしてください。

1. リポジトリが存在することを確認します。Container Registry とは異なり、リポジトリの作成は最初のイメージの push とは別の操作です。リポジトリが存在しない場合は、作成します。
2. push するイメージのフルパスが正しいことを確認します。パスには、レジストリのホスト名、 Google Cloud プロジェクト ID、リポジトリ、イメージを含める必要があります。次に例を示します。

   us-west1-docker.pkg.dev/my-project/my-repo/my-image:v1
     

   Artifact Registry の各リポジトリは個別のリソースであるため、リポジトリのないパスにイメージを push することはできません。たとえば、 us-west1-docker.pkg.dev/my-project/my-image:v1 は 無効なイメージパスです。

   詳細については、 リポジトリとイメージ名をご覧ください。

3. イメージを push するアカウントに、リポジトリへの書き込み権限があることを確認します。サービス アカウントへの ロールの自動付与を無効にしている場合は、 ランタイム サービス アカウントに Artifact Registry ロールを付与する必要があります。
• Compute Engine、Cloud Run、Google Kubernetes Engine のサービス アカウントの場合は、 ランタイム サービス アカウントに Artifact Registry 書き込みロール （roles/artifactregistry.writer）を付与する必要があります。
• Cloud Build サービス アカウントの場合は、ビルドを実行するサービス アカウントに Artifact Registry 書き込みロール（roles/artifactregistry.writer） を付与する必要があります。
4. Artifact Registry から「The repository has enabled tag immutability」というメッセージが返された場合は、リポジトリにタグの不変性が構成されています。リポジトリ内の同じイメージの別のバージョンですでに使用されているタグを使用してイメージを push することはできません。保存されている他のバージョンのイメージで使用されていないタグを使用して、イメージを再度 push してみてください。

   リポジトリが不変のイメージタグ用に構成されていることを確認するには、 コンソールの Google Cloud リポジトリのリストにある [Immutable image tags] 列を確認するか、次のコマンドを実行します。

   gcloud artifacts repositories describe REPOSITORY \
         --project=PROJECT-ID \
         --location=LOCATION
     

ImagePullBackOff メッセージと ErrImagePull メッセージ

ImagePullBackOff と ErrImagePull を含むメッセージは、GKE によってレジストリからイメージを pull できないことを示しています。

• Artifact Registry から pull するための要件 を確認する。
• GKE のドキュメントでイメージの pull のトラブルシューティング を確認する。