AWS ECRのプッシュエラー「no basic auth credentials」の解決方法

問題の発生docker pushを実行してイメージをクラウドに送信しようとした際、即座に失敗し、昨日までは問題なく動いていたのに「no basic auth credentials」というストレスの溜まるエラーが表示されることがあります。これは通常、ローカルのDocker環境とAWS間の認証が切れていることが原因です。

$ docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest
The push refers to repository [123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app]
Error response from daemon: no basic auth credentials

原因根本的な原因は単純で、Dockerクライアントの認証が切れていることです。多くの場合、セッショントークンの有効期限が切れたことを意味します。

AWS ECRの認証トークンは短命です。デフォルトでは12時間ごとに期限切れになります。これはセキュリティ機能であり、万が一認証情報が漏洩しても無期限にアクセスされるのを防ぐためのものです。Docker Hubのようにログインが数週間持続するのとは異なり、ECRでは頻繁にプッシュを行う場合、少なくとも1日2回は「パスワード」を更新する必要があります。

ステップバイステップの解決策### 1. AWSの識別情報を確認するまず、ターミナルで自分がどのユーザーとして認識されているかを確認します。AWSが想定とは異なる認証情報を使用しようとしている可能性があります。次のコマンドを実行して、現在アクティブなプロファイルを確認してください。

aws sts get-caller-identity

エラーが返される場合は、AWS CLIが設定されていません。先に進む前に aws configure を実行して、アクセスキーとシークレットキーを設定してください。

2. トークンの更新 (AWS CLI v2)最近の環境の多くはAWS CLI バージョン2を使用しています。get-login-password コマンドを使用して新しいトークンを取得し、Dockerに直接パイプするのが最もスマートなログイン方法です。

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

クイックチェックリスト:

• us-east-1 を実際のリージョン（ap-northeast-1 など）に置き換えます。
• 123456789012 をご自身の12桁のAWSアカウントIDに置き換えます。
• ユーザー名は AWS のままにします。これは静的な文字列であり、IAMユーザー名ではありません。

3. AWS CLI v1 (レガシー) の場合の解決策古いビルドサーバーなどでCLI v1を保守している場合、コマンドは少し異なります。サブシェルを使用して実行する必要がある完全なコマンド文字列が生成されます。

$(aws ecr get-login --no-include-email --region us-east-1)

4. 複数のプロファイルの管理仕事用と個人用のAWSアカウントを使い分けていますか？間違ったアカウントで認証されている可能性があります。フラグを追加して、特定のプロファイルを使用するようにCLIに強制します。

aws ecr get-login-password --region us-east-1 --profile work-profile | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

修正の確認Login Succeeded というメッセージが表示されることを確認してください。表示されたら、プッシュを再試行します。すぐに動作するはずです。それでも失敗する場合は、~/.docker/config.json ファイルを確認してください。Docker Desktop for MacやWindowsで一般的な外部のcredential helperが古いデータをキャッシュしていることがあります。auths セクションをチェックして、ECRレジストリのURLがプッシュ先と正確に一致しているか確認してください。

予防のためのプロのヒント### ECR Credential Helperによる自動化手動ログインは生産性を低下させます。docker-credential-ecr-login ヘルパーをインストールすれば、バックグラウンドで12時間の更新サイクルを自動的に処理してくれます。インストール後は、二度とログインコマンドを入力することなく、いつでも docker push を実行できるようになります。

IAM権限の確認IAMユーザーには ecr:GetAuthorizationToken 権限が必要です。これがないと、Dockerが試行する前にログインコマンド自体が「Access Denied」エラーで失敗します。GitHub ActionsなどのCI/CDツールを使用している場合は、ランナーのロールにこの権限が付与されていることを確認してください。

レジストリURLのタイポ一文字足りないだけで全てが壊れます。URLの形式は [account-id].dkr.ecr.[region].amazonaws.com である必要があります。dkr や ecr の部分を忘れると、Dockerはレジストリを認識できず、汎用的な no basic auth エラーに戻ってしまいます。

シークレットを安全に保つ自動プッシュ用にIAMユーザーを作成する際は、古いパスワードを使い回さないでください。私は通常、新しいサービスごとに32文字のランダムな文字列を生成しています。最近は ToolCraftのパスワード生成ツール を使っています。ブラウザ上で完全に動作するため、機密データを他人のサーバーに触れさせることなく、セキュリティ基準を維持するのに最適です。