インフラ作業支援ラボInfra Support Lab ← ガイド一覧← 戻る
トップ > ガイド > トラブル解決 > ImagePullBackOffの原因
トラブル解決｜更新日：2026年10月26日

KubernetesのImagePullBackOff・ErrImagePullの原因｜認証・タグ・通信

ImagePullBackOff・ErrImagePullはイメージ取得段階の障害です。PodのEventsに出ている実際の失敗内容を起点に、名前・タグ・認証・通信の原因を分けます。

この記事の目的

アプリ起動後のクラッシュとは区別し、レジストリからのイメージ取得失敗を調べます。

最初にやること

kubectl describe podのEventsを確認し、設定したイメージの名前・タグ・認証を照合します。

注意：認証情報をコマンド結果やログへ露出させたり、セキュリティ検証のために認証を無効にしたりしないでください。app・APP・POD_NAME・CONTAINER_NAMEは例です。context・namespace・権限を実環境で確認してください。
Kubernetes

Kubernetes・kubectl基本操作

対象と原因を絞り、変更前後の確認手順へ進みます。

記事を読む →Kubernetes

CrashLoopBackOffの原因

対象と原因を絞り、変更前後の確認手順へ進みます。

記事を読む →Kubernetes

Deploymentの更新と切り戻し

rollout history・status・undoと変更前後の確認を行います。

記事を読む →

1. ErrImagePullとImagePullBackOffの違い

ErrImagePullはイメージ取得処理の失敗、ImagePullBackOffは失敗後の再試行待ちの表示です。まだアプリプロセスが起動できていない段階であり、CrashLoopBackOffとは切り分けの起点が異なります。

2. Eventsとimage指定を確認

kubectl config current-context kubectl get pods -n app kubectl describe pod POD_NAME -n app kubectl get pod POD_NAME -n app -o jsonpath='{.spec.containers[*].image}'

エラー行の理由（例：manifest unknown・unauthorized・no such host・x509）を記録します。イメージ名・タグ・digestはリポジトリ側の公開内容と一致する必要があります。

3. エラー別の次の確認

表示例確認先
manifest unknown / not foundイメージのリポジトリ名・タグ・digestと公開状況
unauthorized / deniedServiceAccount、imagePullSecrets、レジストリ認証
no such hostNodeからのDNS名前解決・レジストリ名
i/o timeout / connection refusedNode→レジストリの通信・Proxy・Firewall
x509証明書チェーン・CA設定・ノード時刻
Too Many Requestsレジストリのレート制限・認証と利用枠

4. imagePullSecretsとNamespace

kubectl get pod POD_NAME -n app -o jsonpath='{.spec.imagePullSecrets[*].name}' kubectl get pod POD_NAME -n app -o jsonpath='{.spec.serviceAccountName}' kubectl get secrets -n app

通常Podは同じNamespaceのpull Secretを参照します。ServiceAccountに設定されている場合もあるため、Podの実際の参照先を確認します。

危険：Secretの値をkubectl get secret -o yamlで取得して公開ログへ貼らないでください。base64は暗号化ではありません。

5. 実際にPullする場所を確認

Kubernetesでイメージを取得するのはNode側のコンテナランタイムです。作業端末でdocker pullが成功しても、NodeでのDNS・Proxy・証明書・認証が正しい証明にはなりません。

Nodeのネットワークが原因ならLinuxネットワークの確認手順も参考になります。

6. イベント別に修正して再確認する

以下は想定イベント例であり実機実測ではありません。 変更を行う前に対象のDeployment/Pod、Node、イメージのタグまたはdigest、Secret名、GitOps/CI等の管理元を記録します。

想定されたEvents表示具体的な修正条件・次の確認
manifest unknown / not found配布元レジストリで実在するdigest・タグを管理担当者が確認。指定ミスならマニフェストの管理元で修正し、旧イメージ参照を保持する
unauthorized / deniedPodで有効になったimagePullSecrets、同一NamespaceのSecret名・type、ServiceAccount、認証先と必要権限を照合。資格情報を出力・チャットへ貼らない
no such host / i/o timeout実際のPod配置Node・ノードのDNS/Proxy/Firewall/レジストリ疎通を管理担当へ調査依頼。作業端末のDocker pull成功だけでは復旧と判断しない
x509 / TLS検証エラーNodeの信頼CA、証明書の有効期限、ホスト名一致、時刻を調べ、正しい証明書を配布。TLS検証を無効化して通さない
Too Many Requestsレジストリ側の制限と認証状態を確認し、承認された取得頻度・キャッシュ・認証方式に変更。単なる再起動連打を避ける
# 参照のみ：Pod/ServiceAccountの認証参照先（Secret値は取得しない） kubectl get pod POD_NAME -n app -o jsonpath='{.spec.imagePullSecrets[*].name}' kubectl get pod POD_NAME -n app -o jsonpath='{.spec.serviceAccountName}' kubectl get serviceaccount SERVICEACCOUNT_NAME -n app kubectl describe pod POD_NAME -n app

SERVICEACCOUNT_NAMEはPodで実際に指定されているServiceAccount名に置き換えます。指定が省略されている場合は対象Namespaceのdefault ServiceAccountを確認します。SecretはPodと同じNamespaceに存在する必要があります。変更前にGitOps管理元・配布イメージの可用性・既存サービスへの影響を確認し、承認済みマニフェストの更新を優先してください。

完了条件：ImagePullのEventsが再発せず、コンテナが開始し、Pod Ready・アプリログ・業務通信まで正常であること。修正後も失敗する場合はNode側のコンテナランタイム・レジストリ運用者へ時刻・エラー種別・対象Nodeを渡します。実際に起動後クラッシュする場合はCrashLoopBackOffの調査に切り替えます。

7. 修正後の確認

kubectl get pods -n app -o wide kubectl describe pod POD_NAME -n app kubectl get events -n app --sort-by=.metadata.creationTimestamp

Pullが解消してもPodがReadyにならない場合があります。コンテナ起動後に落ちるならCrashLoopBackOffの原因確認へ切り替えます。

公式・一次資料

関連手順を確認する

参照操作・変更操作・削除操作を区別し、作業前後に対象と正常性を記録します。

関連ガイドへ