docker/k8s『Image Pull BackOff』の原因と対処法

# Podの概要と直近イベント
kubectl get pods -n <ns>
kubectl describe pod <pod> -n <ns> | sed -n '/Events/,$p'

# イメージ別のpullログ（失敗理由のHTTPコードやメッセージ）
kubectl logs <pod> -n <ns> --previous --all-containers=true 2>/dev/null || true

# ノードで直接pull（権限・タグ・ネットワーク検証）
crictl pull <image:tag>              # containerd/CRI-O
# or
sudo nerdctl -n k8s.io pull <image:tag>
# or (Dockerホストなら)
docker pull <image:tag>

# NG: あいまいなlatest
image: ghcr.io/org/app:latest

# OK: 明示タグ or ダイジェスト固定
image: ghcr.io/org/app:v1.2.3
image: ghcr.io/org/app@sha256:...  # 再現性重視

# docker login 相当のSecretを作成
kubectl create secret docker-registry regcred \
  --docker-server=ghcr.io \
  --docker-username=YOUR_USER \
  --docker-password=YOUR_TOKEN \
  --docker-email=dev@example.com -n <ns>

# Pod/ServiceAccountへ紐付け
kubectl patch serviceaccount default -n <ns> \
  -p '{"imagePullSecrets":[{"name":"regcred"}]}'

# 直接Podマニフェストへ指定する例
apiVersion: v1
kind: Pod
metadata: { name: app, namespace: default }
spec:
  imagePullSecrets:
    - name: regcred
  containers:
    - name: app
      image: ghcr.io/org/app:v1.2.3

# ノード内でレジストリFQDNを解決・到達確認
nsenter -t $(pgrep -f kubelet | head -n1) -m -n -- sh -lc "
  getent hosts ghcr.io && \
  nc -vz ghcr.io 443 || true"

# Podからも確認（BusyBox等）
kubectl run dnstest --rm -it --image=busybox --restart=Never -- sh -c "
  nslookup ghcr.io && wget -qO- https://ghcr.io || true"

# ダウンロード重複を抑える（同一ノードでのWarm-upなど）
crictl images | grep <image> || crictl pull <image:tag>

# containerd の hosts.toml 例（TLS/ミラーを定義）
sudo mkdir -p /etc/containerd/certs.d/registry.intra.local
sudo tee /etc/containerd/certs.d/registry.intra.local/hosts.toml <<'EOF'
server = "https://registry.intra.local"
[host."https://registry.intra.local"]
  capabilities = ["pull", "resolve"]
  ca = "/etc/ssl/certs/intra-ca.pem"
EOF
sudo systemctl restart containerd

# GitHub Container Registry 例：可視性・権限を確認
# 1) リポジトリの"packages"が公開か、PATにread:packagesが含まれるか
# 2) 該当タグ/ダイジェストが存在するか（UI/gh apiで確認）

# CLIでダイジェストを固定確認（Docker）
docker pull ghcr.io/org/app:v1.2.3
docker inspect ghcr.io/org/app:v1.2.3 --format '{{.RepoDigests}}'

# Deployment のイメージ差し替え
kubectl set image deploy/app app=ghcr.io/org/app:v1.2.4 -n <ns>
kubectl rollout status deploy/app -n <ns>

# ロールアウトが止まる場合のイベント確認
kubectl describe deploy/app -n <ns> | sed -n '/Events/,$p'

# containerdのコンフィグ（/etc/containerd/config.toml）を作成/編集
containerd config default | sudo tee /etc/containerd/config.toml >/dev/null
# 必要に応じて timeout や registry 設定、mirrors を記述
sudo systemctl restart containerd

# まずは確実にpullできる公式イメージでノード健全性を確認
kubectl run pull-test --image=busybox:1.36 --restart=Never --command -- sh -c "echo ok && sleep 5"
kubectl get pod pull-test -w
kubectl logs pull-test || true
kubectl delete pod pull-test