Introduction

Kubernetes secrets are namespace-scoped. A private registry secret can exist and look valid while pods still fail with ImagePullBackOff because the deployment runs in another namespace or the service account does not reference the secret at all.

Symptoms

  • Pods fail with ErrImagePull or ImagePullBackOff for a private image
  • kubectl get secret shows the registry secret, but only in another namespace
  • The same image works in one namespace and fails in another
  • The issue begins after moving workloads between namespaces or Helm releases

Common Causes

  • The docker-registry secret exists in the wrong namespace
  • The deployment or service account does not reference imagePullSecrets
  • A Helm chart creates the secret in one namespace and deploys workloads into another
  • The registry credentials inside the secret are stale or malformed

Step-by-Step Fix

  1. 1.Verify the failing pod events and namespace
  2. 2.Start with the exact namespace and event messages before recreating secrets.
bash
kubectl describe pod <pod-name> -n app
kubectl get events -n app --sort-by=.lastTimestamp
  1. 1.Check whether the secret exists in the same namespace
  2. 2.A valid secret in default does not help a pod running in app.
bash
kubectl get secret regcred -n app
kubectl get secret regcred -n default
  1. 1.Create or copy the secret into the workload namespace
  2. 2.The secret must live alongside the pod or its service account.
bash
kubectl create secret docker-registry regcred -n app --docker-server=registry.example.com --docker-username=user --docker-password=token --docker-email=ops@example.com
  1. 1.Attach the secret to the deployment or service account and restart the pod
  2. 2.After fixing the namespace issue, trigger a new pull so the kubelet uses the right credentials.
yaml
spec:
  imagePullSecrets:
    - name: regcred

Prevention

  • Create registry secrets per namespace, not only once per cluster
  • Template imagePullSecrets into the workload or service account explicitly
  • Verify namespace assumptions in Helm values and CI manifests
  • Rotate and test private registry credentials before they expire