Amazon ECR 使用時の Docker コマンドのエラーのトラブルシューティング - Amazon ECR

Amazon ECR 使用時の Docker コマンドのエラーのトラブルシューティング

場合によっては、Amazon ECR に対して Docker コマンドを実行すると、エラーメッセージが表示されることがあります。一般的なエラーメッセージと考えられる解決策を以下に説明します。

Amazon ECR レポジトリからイメージをプルするときのエラー: "ファイルシステムの検証に失敗しました" または "404: イメージが見つかりません"

docker pull コマンドを使用すると、Docker 1.9 以降で Amazon ECR レポジトリからイメージをプルするときにエラー Filesystem verification failed が表示されます。Docker 1.9 より前のバージョンを使用するときはエラー 404: Image not found が表示される場合があります。

考えられる理由とその説明を以下に示します。

ローカルディスクがいっぱいである

docker pull を実行しているローカルディスクがいっぱいである場合、ローカルファイルで計算された SHA-1 ハッシュは、Amazon ECR で計算されたものとは異なる可能性があります。ローカルディスクに、プルしている Docker イメージを保存するのに十分な空き容量があることを確認します。新しいイメージの容量を確保するために、古いイメージを削除することもできます。docker images コマンドを使用して、ローカルにダウンロードしたすべての Docker イメージのリストとそのサイズを表示します。

ネットワークエラーにより、クライアントがリモートリポジトリに接続できない

Amazon ECR レポジトリへの呼び出しでは、インターネットへの機能している接続が必要です。ネットワーク設定を確認し、他のツールやアプリケーションがインターネット上のリソースにアクセスできることを確認します。プライベートサブネットの Amazon EC2 インスタンスで docker pull を実行している場合は、そのサブネットにインターネットへのルートがあることを確認します。ネットワークアドレス変換 (NAT) サーバーまたはマネージド NAT ゲートウェイを使用します。

現時点では、Amazon ECR リポジトリへの呼び出しでは、会社のファイアウォールから Amazon Simple Storage Service (Amazon S3) へのネットワークアクセスも必要です。組織で、サービスエンドポイントを許可するファイアウォールソフトウェアまたは NAT デバイスを使用している場合、現在のリージョンの Amazon S3 サービスエンドポイントが許可されていることを確認します。

HTTP プロキシの背後で Docker を使用している場合は、適切なプロキシ設定を使用して Docker を設定できます。詳細については、Docker ドキュメントの「HTTP プロキシ」を参照してください。

Amazon ECR からイメージをプルする際のエラー: "ファイルシステムレイヤーの検証に失敗しました"

image image-name not found コマンドを使用してイメージをプルするときに、エラー docker pull が表示される場合があります。Docker のログを調べると、次のようなエラーが見つかる場合があります。

filesystem layer verification failed for digest sha256:2b96f...

このエラーは、イメージの 1 つ以上のレイヤーがダウンロードに失敗したことを示します。考えられる理由とその説明を以下に示します。

古いバージョンの Docker 使用している

このエラーは、Docker 1.10 より前のバージョンを使用している場合に、まれに発生することがあります。Docker クライアントを 1.10 以降にアップグレードします。

クライアントでネットワークエラーまたはディスクエラーが発生した

Filesystem verification failed メッセージについて前に説明したように、ディスクがいっぱいであるか、ネットワークの問題により、1 つ以上のレイヤーをダウンロードできない可能性があります。上記の推奨事項に従って、ファイルシステムがいっぱいでないこと、およびネットワーク内から Amazon S3 へのアクセスを有効にしたことを確認します。

プルスルーキャッシュルールを使用してプルするとエラーが発生する

プルスルーキャッシュルールを使用してアップストリームイメージをプルする際に、最もよく発生する可能性のある一般的なエラーは次のとおりです。

リポジトリが存在しない

リポジトリが存在しないことを示すエラーは、ほとんどの場合、Amazon ECR プライベートレジストリにリポジトリが存在しないか、アップストリームイメージをプルする IAM プリンシパルに ecr:CreateRepository アクセス許可が付与されていないのが原因です。このエラーを解決するには、プルコマンドのリポジトリ URI が正しいこと、必要となる IAM アクセス許可がアップストリームイメージをプルする IAM プリンシパルに付与されていること、またはアップストリームのイメージをプルする前に、プッシュされるアップストリームイメージのリポジトリが Amazon ECR プライベートレジストリに作成されていることを確認します。必要となる IAM アクセス許可の詳細については、「必要な IAM 許可」を参照してください。

このエラーの例を以下に示します。

Error response from daemon: repository 111122223333.dkr.ecr.us-east-1.amazonaws.com/ecr-public/amazonlinux/amazonlinux not found: name unknown: The repository with name 'ecr-public/amazonlinux/amazonlinux' does not exist in the registry with id '111122223333'
リクエストされたイメージが見つからない

イメージが見つからないことを示すエラーは、ほとんどの場合、アップストリームレジストリにイメージが存在しないか、アップストリームイメージをプルする IAM プリンシパルに ecr:BatchImportUpstreamImage アクセス許可が付与されておらず、Amazon ECR プライベートレジストリ内にレポジトリがすでに作成されているのが原因です。このエラーを解決するには、アップストリームイメージとイメージタグ名が正しく、それが存在し、アップストリームイメージをプルする IAM プリンシパルに必要な IAM アクセス許可が付与されていることを確認する必要があります。必要となる IAM アクセス許可の詳細については、「必要な IAM 許可」を参照してください。

このエラーの例を以下に示します。

Error response from daemon: manifest for 111122223333.dkr.ecr.us-east-1.amazonaws.com/ecr-public/amazonlinux/amazonlinux:latest not found: manifest unknown: Requested image not found

レポジトリへのプッシュの際の HTTP 403 エラー、または "基本的な認証情報がありません" エラー

HTTP 403 (Forbidden) コマンドを使用して Docker に対して正常に認証されても、no basic auth credentials エラーが発生したり、docker push コマンドまたは docker pull コマンドからのエラーメッセージ aws ecr get-login-password が表示されたりする場合があります。この問題の既知の原因をいくつか次に示します。

別のリージョンに対して認証されている

認証リクエストは特定のリージョンに関連付けられていて、リージョン間では使用できません。たとえば、米国西部 (オレゴン)リージョン から認証トークンを取得する場合、これを使用して、米国東部 (バージニア北部) リージョンのリポジトリに対して認証を行うことはできません。この問題を解決するには、リポジトリが存在する同じリージョンから認証トークンを取得したことを確認してください。詳細については、「プライベートレジストリの認証」を参照してください。

プッシュ先として認証したリポジトリに対するアクセス許可がない

プッシュ先のリポジトリに対するアクセス許可がありません。詳細については、「プライベートリポジトリポリシー」を参照してください。

トークンの有効期限が切れた。

GetAuthorizationToken オペレーションを使用して取得した認証トークンのデフォルトの有効期限は 12 時間です。

wincred 認証情報マネージャーのバグ

一部のバージョンの Docker for Windows では、wincred という認証情報マネージャーを使用します。この認証情報マネージャーは、aws ecr get-login-password によって生成された Docker ログインコマンドを正しく処理しません (詳細については、https://github.com/docker/docker/issues/22910 を参照)。出力される Docker ログインコマンドは実行できますが、イメージをプッシュまたはプルしようとすると、コマンドは失敗します。これに対処するには、https:// から出力される Docker ログインコマンドのレジストリ引数から aws ecr get-login-password スキームを削除します。HTTPS スキームのない Docker ログインコマンドの例を次に示します。

docker login -u AWS -p <password> <aws_account_id>.dkr.ecr.<region>.amazonaws.com