Kubernetes の ImagePullBackOff エラー:原因と解決策

冒頭まとめ ImagePullBackOff は、イメージの取得に失敗した理由の名前ではありません。失敗したあと、次に取得を試みるまで待たせている状態の名前です。理由は別の名前で表されます。 kubelet のソースには、取得に関する状態名が5つ定義されています。待たせている状態、一般的な取得の失敗、イメージを調べられない場合、手元に無いのに取得しない方針になっている場合、そして名前を解釈できない場合です。この5つのどれが出ているかで、原因の範囲がほぼ決まります。最初に見るべきはここです。 待ち時間の決まり方は、コンテナの再起動と同じ形です。初回は10秒で倍々に増え、上限は300秒です。値は同じですが、記録は別に管理されています。 そして、この状態には決定的な性質が1つあります。諦めません。何度失敗しても、対象は待機中の扱いのまま残り続け、割り当てられた資源を確保し続けます。失敗を重ねたら異常として扱う、という仕組みが標準では用意されていません。人が気付いて手を入れるまで、そのままです。 最後に、取得の方針の既定値も押さえておきます。ソースの規則は単純で、タグが latest なら毎回取得し、それ以外なら手元にあるものを使います。タグを書かない場合はタグを latest とみなす処理が入るため、結果として毎回取得になります。一方、ダイジェストで指定した場合はタグが空のままなので、手元にあるものを使う方針になります。 エラーの概要 一覧では待機中の理由として表示されます。再起動の回数は増えません。コンテナが一度も起動していないためです。 NAME READY STATUS RESTARTS AGE my-app-6c4d8f9b5-2xq7w 0/1 ImagePullBackOff 0 4m12s 詳細を見ると、最初の失敗と、その後の待機が別々に記録されています。 Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Pulling 4m (x4 over 5m) kubelet Pulling image "example/my-app:1.0" Warning Failed 3m (x4 over 5m) kubelet Failed to pull image "example/my-app:1.0": ... Warning Failed 3m (x4 over 5m) kubelet Error: ErrImagePull Normal BackOff 30s (x12 over 4m) kubelet Back-off pulling image "example/my-app:1.0" Warning Failed 30s (x12 over 4m) kubelet Error: ImagePullBackOff 読むべきは、上から2行目の末尾です。ここに、取得を担う仕組みが返した文言がそのまま入ります。名前が見つからない、資格が無い、回数の上限に達した、といった内容が、その置き場の言葉で書かれています。ImagePullBackOff という表示だけを見ていても、この文言には辿り着きません。 ...

2026年7月29日 · ErrorLog