Kubernetes: ImagePullBackOff の原因と解決策

概要

コンテナイメージの取得に失敗し、Kubernetesが再試行間隔を延長している状態です。

エラーメッセージ

NAME                    READY   STATUS             RESTARTS   AGE
myapp-xxx-yyy           0/1     ImagePullBackOff   0          5m

原因

イメージ名の誤り: タグやリポジトリ名が間違い
認証エラー: プライベートレジストリへの認証失敗
イメージ不存在: 指定されたイメージがない
ネットワーク問題: レジストリへの接続失敗

解決策

1. イメージ名確認

1
2
3
4
5
# ローカルで確認
docker pull myregistry.com/myimage:v1.0

# Podの詳細確認
kubectl describe pod myapp-xxx-yyy

2. ImagePullSecret作成

1
2
3
4
5
kubectl create secret docker-registry regcred \
  --docker-server=myregistry.com \
  --docker-username=user \
  --docker-password=password \
  --docker-email=user@example.com

3. Pod/Deploymentで使用

1
2
3
4
5
6
spec:
  containers:
  - name: myapp
    image: myregistry.com/myimage:v1.0
  imagePullSecrets:
  - name: regcred

4. ServiceAccountにSecret紐付け

1
2
kubectl patch serviceaccount default \
  -p '{"imagePullSecrets": [{"name": "regcred"}]}'

よくある間違い

タグのlatest指定で更新されない
imagePullPolicyがIfNotPresentでキャッシュ使用

概要

エラーメッセージ

原因

解決策

1. イメージ名確認

2. ImagePullSecret作成

3. Pod/Deploymentで使用

4. ServiceAccountにSecret紐付け

よくある間違い

Kubernetes の他のエラー