Amazon EKS のポッドステータス ErrImagePull エラーと ImagePullBackoff エラーをトラブルシューティングする方法を教えてください。

簡単な説明

kubectl の get pods コマンドを実行する際にポッドが ImagePullBackOff ステータスになっていると、ポッドは正しく動作しません。magePullBackOff ステータスは、イメージを取得またはプルできなかったためにコンテナが起動しなかったことを示しています。この問題のトラブルシューティングを行うには、次の解決策を使用してください。

詳細については、「Amazon EKS connector Pods are in ImagePullBackOff state」を参照してください。

解決策

イメージの情報を確認する

以下の手順を使用して、ポッドステータスについてのエラーメッセージを確認し、イメージの名前、タグ、およびセキュアハッシュアルゴリズム (SHA) が正しいことを確認します。

1. 次のコマンドを実行し、Pod のステータスを取得します。

   $ kubectl get pods -n defaultNAME                              READY   STATUS             RESTARTS   AGE
   nginx-7cdbb5f49f-2p6p2            0/1     ImagePullBackOff   0          86s

2. 次のコマンドを実行し、ポッド障害の詳細を取得します。

   $ kubectl describe pod nginx-7cdbb5f49f-2p6p2
   ...
   Events:
     Type     Reason     Age                   From               Message
     ----     ------     ----                  ----               -------
     Normal   Scheduled  4m23s                 default-scheduler  Successfully assigned default/nginx-7cdbb5f49f-2p6p2 to ip-192-168-149-143.us-east-2.compute.internal
     Normal   Pulling    2m44s (x4 over 4m9s)  kubelet            Pulling image "nginxx:latest"
     Warning  Failed     2m43s (x4 over 4m9s)  kubelet            Failed to pull image "nginxx:latest": rpc error: code = Unknown desc = Error response from daemon: pull access denied for nginxx, repository does not exist or may require 'docker login': denied: requested access to the resource is denied
     Warning  Failed     2m43s (x4 over 4m9s)  kubelet            Error: ErrImagePull
     Warning  Failed     2m32s (x6 over 4m8s)  kubelet            Error: ImagePullBackOff
     Normal   BackOff    2m17s (x7 over 4m8s)  kubelet            Back-off pulling image "nginxx:latest"

3. 正しいイメージのタグと名前が存在することを確認します。

4. イメージレジストリに認証が必要な場合は、そのレジストリにアクセスする権限があることを確認してください。次のコマンドを実行し、ポッドで使用されているイメージが正しいことを確認します。

   $ kubectl get pods nginx-7cdbb5f49f-2p6p2  -o jsonpath="{.spec.containers[*].image}" | \sort
   nginx:latest

ポッドのステータス値について理解するには、Kubernetes ウェブサイトの「Pod phase」と「Amazon EKS のポッドステータスをトラブルシューティングする方法を教えてください」を参照してください。

プライベートレジストリをトラブルシューティングする

Amazon EKS のプライベートレジストリからイメージを取得する場合、追加の設定が必要になる場合があります。ワークロードマニフェストで imagePullSecrets を使用して認証情報を指定します。これらの認証情報はプライベートレジストリで認証されます。これにより、ポッドは指定されたプライベートリポジトリからイメージを取得できます。

次のコマンドを使用して、YAML にシークレットの内容を表示します。

kubectl get secret <secret_name> --output=yaml

次の例では、ポッドは regcred の Docker レジストリの認証情報にアクセスする必要があります。

apiVersion: v1
kind: Pod
metadata:
  name: private-reg
spec:
  containers:
  - name: private-reg-container
    image: your-private-image
  imagePullSecrets:
  - name: regcred

your-private-image は、次のようなプライベートレジストリ内のイメージへのパスに置き換えます。

your.private.registry.example.com/bob/bob-private:v1

プライベートレジストリからイメージを取得するには、Kubernetes に認証情報が必要です。設定ファイルの imagePullSecrets フィールドでは、Kubernetes が regcred という名前のシークレットから認証情報を取得するように指定されています。

詳細については、Kubernetes ウェブサイトの「Pull an Image from a Private Registry」を参照してください。

レジストリに関するその他の問題をトラブルシューティングする

Failed to pull image issue

「Failed to pull image...」エラーは、kubelet がプライベートレジストリのエンドポイントへの接続を試みたものの、接続タイムアウトによって失敗したことを示します。

次の例では、kubelet がプライベートレジストリのエンドポイントにアクセスできないため、レジストリにアクセスできません。

$ kubectl describe pods nginx-9cc69448d-vgm4m
...
Events:
  Type     Reason     Age                From               Message
  ----     ------     ----               ----               -------
  Normal   Scheduled  16m                default-scheduler  Successfully assigned default/nginx-9cc69448d-vgm4m to ip-192-168-149-143.us-east-2.compute.internal
  Normal   Pulling    15m (x3 over 16m)  kubelet            Pulling image "nginx:stable"
  Warning  Failed     15m (x3 over 16m)  kubelet            Failed to pull image "nginx:stable": rpc error: code = Unknown desc = Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)
  Warning  Failed     15m (x3 over 16m)  kubelet            Error: ErrImagePull
  Normal   BackOff    14m (x4 over 16m)  kubelet            Back-off pulling image "nginx:stable"
  Warning  Failed     14m (x4 over 16m)  kubelet            Error: ImagePullBackOff

このエラーをトラブルシューティングするには、レジストリエンドポイントとの通信を許可するサブネット、セキュリティグループ、ネットワーク ACL を確認します。

Registry rate limit exceeded

次の例では、レジストリのレート制限を超えています。

$ kubectl describe pod nginx-6bf9f7cf5d-22q48
...
Events:
  Type     Reason                  Age                   From               Message
  ----     ------                  ----                  ----               -------
  Normal   Scheduled               3m54s                 default-scheduler  Successfully assigned default/nginx-6bf9f7cf5d-22q48 to ip-192-168-153-54.us-east-2.compute.internal
  Warning  FailedCreatePodSandBox  3m33s                 kubelet            Failed to create pod sandbox: rpc error: code = Unknown desc = failed to set up sandbox container "82065dea585e8428eaf9df89936653b5ef12b53bef7f83baddb22edc59cd562a" network for pod "nginx-6bf9f7cf5d-22q48": networkPlugin cni failed to set up pod "nginx-6bf9f7cf5d-22q48_default" network: add cmd: failed to assign an IP address to container
  Warning  FailedCreatePodSandBox  2m53s                 kubelet            Failed to create pod sandbox: rpc error: code = Unknown desc = failed to set up sandbox container "20f2e27ba6d813ffc754a12a1444aa20d552cc9d665f4fe5506b02a4fb53db36" network for pod "nginx-6bf9f7cf5d-22q48": networkPlugin cni failed to set up pod "nginx-6bf9f7cf5d-22q48_default" network: add cmd: failed to assign an IP address to container
  Warning  FailedCreatePodSandBox  2m35s                 kubelet            Failed to create pod sandbox: rpc error: code = Unknown desc = failed to set up sandbox container "d9b7e98187e84fed907ff882279bf16223bf5ed0176b03dff3b860ca9a7d5e03" network for pod "nginx-6bf9f7cf5d-22q48": networkPlugin cni failed to set up pod "nginx-6bf9f7cf5d-22q48_default" network: add cmd: failed to assign an IP address to container
  Warning  FailedCreatePodSandBox  2m                    kubelet            Failed to create pod sandbox: rpc error: code = Unknown desc = failed to set up sandbox container "c02c8b65d7d49c94aadd396cb57031d6df5e718ab629237cdea63d2185dbbfb0" network for pod "nginx-6bf9f7cf5d-22q48": networkPlugin cni failed to set up pod "nginx-6bf9f7cf5d-22q48_default" network: add cmd: failed to assign an IP address to container
  Normal   SandboxChanged          119s (x4 over 3m13s)  kubelet            Pod sandbox changed, it will be killed and re-created.
  Normal   Pulling                 56s (x3 over 99s)     kubelet            Pulling image "httpd:latest"
  Warning  Failed                  56s (x3 over 99s)     kubelet            Failed to pull image "httpd:latest": rpc error: code = Unknown desc = Error response from daemon: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit
  Warning  Failed                  56s (x3 over 99s)     kubelet            Error: ErrImagePull
  Normal   BackOff                 43s (x4 over 98s)     kubelet            Back-off pulling image "httpd:latest"

プルレートの上限に達した後にパブリック Docker Hub リポジトリからイメージを取得しようとすると停止します。詳細については、Docker Hub ウェブサイトの「Docker Hub rate limit」を参照してください。