Kubernetesの「ImagePullBackOff」エラーをデバッグする方法

Kubernetesクラスタは、コンテナイメージをプルしようとした際にいくつかの問題に直面することがあります。エラーが発生すると、PodはImagePullBackOff状態に入ります。この一般的ですが解読が難しいメッセージをデバッグする方法を以下に示しますので、サービスをオンラインに戻すことができます。

イメージプルの仕組み

Kubernetesは、新しいデプロイメントを作成するか、異なるタグのリファレンスで既存のものを更新する際に、イメージを取得する必要があります。イメージをプルする責任は、各ワーカーノードのKubeletプロセスにあります。Podのマニフェストによって参照されるすべてのイメージは、クラスター内のすべてのノードがアクセスできる必要があるため、いずれのノードもコンテナスケジューリングリクエストを満たすことができます。

画像パスが間違っている場合、認証が不適切な場合、またはネットワークがダウンしている場合、ダウンロードが失敗する可能性があります。この場合、Kubernetesは「取り消し」を行い、別のダウンロード試行をスケジュールします。次のプルの前の遅延は、試行が失敗するたびに指数関数的に増加し、最大で5分の制限があります。

もしあなたのポッドがImagePullBackOffの状態を示している場合、Kubernetesは複数回のイメージプル失敗があり、再試行する前に待機しています。イメージが利用可能になるまで、コンテナは起動できません。

ネットワークの状態や他の一時的なエラーが原因であることを知っている場合は、Podをこの状態のまま放置しても構いません。Kubernetesは最終的にもう一度再試行を行い、画像を正常に取得します。それが当てはまらない場合、Podを稼働させるためのデバッグの始め方を以下に示します。

基本を確認する

まず第一に、基本を確認する価値があります。リソースマニフェストは、実際に存在する有効な画像を参照していますか？レジストリのパスと画像のタグに簡単なタイプミスがないか確認してください。

内部のKubernetes状態を検査することができます。

describe pod

Kubectlのコマンド。これにより、より多くの情報が得られます。

get pod

およびKubernetesダッシュボードを提供します。

kubectl describe pod my-pod --namespace my-namespace

ポッドのライフサイクルの変更は「イベント」見出しの下に表示されます。最初のイベントはScheduledになります。その後、最初のプル試行に対してPullingイベントが続きます。その後、プルが成功しなかった場合はFailedまたはBackOffイベントが表示されます。Kubernetesがバックオフと再試行のサイクルにある場合、これらはリストの後でも繰り返し表示されます。

これらのイベントに関連する Message を読むことで、問題の根本原因がわかることがよくあります。manifest for image:tag not found というメッセージは、イメージは有効であるが、無効なタグが指定されていることを意味します。does not exist or no pull access というメッセージが表示された場合は、レジストリとイメージのパスが正しいか確認してください。正しいことを確認したら、問題は不正な認証に関連しているでしょう。

レジストリログインの管理

プライベート画像を取得する前にログインする必要があります。Kubernetesでは、これは二段階のメカニズムです：認証情報を含むシークレットを作成し、次にそのシークレットをPod定義で参照します。

PodフィールドはimagePullSecretsと呼ばれています。これは、レジストリのログイントークンを提供するKubernetesシークレットを示す必要があります。このシークレットは、Docker互換のJSON値を格納するべきです。

apiVersion: v1





kind: Secret

type: kubernetes.io/dockerconfigjson

metadata:

 name: image-pull-secret

data:

 .dockerconfigjson: {{ "{"auths": {"registry.example.com": {"username": "demo-user", "password": "my-password"}}}" | b64enc }}

apiVersion: v1

kind: Pod

metadata:

 name: my-pod



spec:

 containers:

 - name: my-container

 image: registry.example.com/my-image:latest

 imagePullSecrets:

 - name: image-pull-secret

このマニフェストは、registry.example.com に demo-user として、パスワード my-password でログインするためのシークレットを作成する方法を示しています。Pod は名前でシークレットを参照します。クラスターのノード上の Kubelet プロセスは、レジストリからイメージをプルする際に Docker config.json スニペットを含めます。

このスニペットは、有効なKubernetesシークレット値であるためにBase64エンコードされる必要があります。事前にエンコードされた値を使用するか、プレーンテキストをYAMLのb64encを通してパイプすることができます。上記のマニフェストに示されています。

使用する資格情報の種類は、レジストリに依存します。多くの場合、passwordは実際には個人用アクセストークンまたはAPIキーになります。Docker Hubでは、アカウントに二要素認証が有効になっている場合、アカウント設定で生成されたアクセストークンが必要です。

レジストリのレート制限

レジストリのURL、イメージタグ名、ログイン資格情報を確認した場合、レジストリのレート制限のためにImagePullBackOffが表示されることがあります。Docker Hubは、6時間ごとに100回のコンテナプルに制限しています。ログイン資格情報を提供すると、この制限は6時間ごとに200回のプルに増加します。この制限は、頻繁にデプロイされるPodが多数あるアクティブなクラスターではすぐに達成される可能性があります。

レート制限によるプル失敗は、認証の問題と同じように現れます。上限の期限が切れるまで、しばらく待つ必要があります。その後、Kubernetesは画像を正常にプルし、ポッドを立ち上げます。

長期的な緩和策として、自分自身のクラスター内レジストリやプロキシを実行して、画像をキャッシュすることを検討してください。これにより、Dockerのサーバーにアクセスする頻度を大幅に減らし、レート制限内に収まるのに役立ちます。

要約

Kubernetesのポッドは、ノードがイメージをプルできない場合にImagePullBackOff状態になります。Kubeletは、間欠的なエラーが手動での介入を必要としないように、定期的にプルを再試行します。

一時的なエラーではないと確信したら、まずPodのイメージパスが有効であることを確認してください。それが確認できたら、間違ったログイン資格情報や制限の枠を使い切ったことを疑ってください。kubectl describeを使用すると、失敗に至るまでの一連のイベントが明らかになります。

最終手段として、別のマシンから画像を自分で取得して、リモートレジストリサーバーが実際に稼働しているかどうか確認することができます。画像を取得できるがクラスターができない場合、ノードがレジストリに到達するのを妨げる一般的なネットワークの問題があるかもしれません。