Introduction

ImagePullBackOff with an unauthorized error means Kubernetes reached the registry but could not authenticate to pull the image. The pod keeps retrying with increasing delay, so deployments stall until credentials or permissions are fixed. This guide walks through diagnosis and a reliable fix path.

Core Topic Sections

Confirm the exact failure reason

Start with pod events, not assumptions. ImagePullBackOff is the state, while the event message reveals the root cause.

kubectl describe pod my-app-pod -n production
kubectl get events -n production --sort-by=.metadata.creationTimestamp | tail -n 20

Look for messages like unauthorized: authentication required, denied, or pull access denied. If the event mentions not found, the problem is likely a bad image name instead of auth.

Validate image reference format

Many auth incidents are actually reference mistakes:

1. Wrong registry host.
2. Wrong repository path.
3. Missing namespace.
4. Wrong tag.

A safe check is to test pull locally with the same full image string used in the manifest.

docker pull registry.example.com/team/my-app:1.4.2

If this fails with unauthorized, fix credentials first. If it fails with not found, fix image naming.

Create and attach an image pull secret

For private registries, create a docker-registry secret and attach it to the workload.

1kubectl create secret docker-registry regcred \
2  --docker-server=registry.example.com \
3  --docker-username=myuser \
4  --docker-password='mypassword' \
5  --docker-email=[email protected] \
6  -n production

Then reference it from the pod template:

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: my-app
5  namespace: production
6spec:
7  replicas: 2
8  selector:
9    matchLabels:
10      app: my-app
11  template:
12    metadata:
13      labels:
14        app: my-app
15    spec:
16      imagePullSecrets:
17        - name: regcred
18      containers:
19        - name: app
20          image: registry.example.com/team/my-app:1.4.2

Apply and watch rollout:

kubectl apply -f deployment.yaml
kubectl rollout status deployment/my-app -n production

Attach secret to a service account for reuse

If many workloads in one namespace use the same registry, bind the secret once on a service account.

1apiVersion: v1
2kind: ServiceAccount
3metadata:
4  name: app-sa
5  namespace: production
6imagePullSecrets:
7  - name: regcred

Then use that service account in deployments. This removes repeated secret blocks and reduces copy-paste drift.

Handle cloud registry specifics

Managed registries often use short-lived tokens:

1. Amazon ECR tokens expire and must be rotated.
2. Google Artifact Registry relies on IAM plus helper auth.
3. Azure Container Registry may use managed identity or admin credentials.

When tokens rotate, regenerate Kubernetes secret and restart affected workloads.

kubectl delete secret regcred -n production
# recreate secret with fresh token
kubectl rollout restart deployment/my-app -n production

Verify RBAC and network policy

Even valid credentials can fail if nodes or runtime cannot reach the registry endpoint. Confirm:

1. Egress rules allow registry host and port.
2. Cluster DNS resolves registry host.
3. Node runtime trusts required certificates.

Auth and connectivity issues often appear together during infrastructure changes.

Operational hardening

Treat pull credentials like application secrets:

1. Store source credentials in a secret manager.
2. Automate periodic rotation.
3. Use least privilege repository access.
4. Alert on repeated pull failures.

This keeps deployments resilient during key rollover and environment rebuilds.

Common Pitfalls

• Creating the secret in one namespace and deploying the pod in another namespace.
• Using a valid secret name but forgetting to reference it in the pod spec.
• Rotating registry credentials without updating Kubernetes secrets.
• Troubleshooting auth before validating image name and tag correctness.
• Assuming the issue is credentials when egress or DNS blocks registry access.

Summary

• ImagePullBackOff with unauthorized means registry auth failed during pull.
• Diagnose from pod events first to separate auth from name errors.
• Create correct image pull secrets and attach them to workloads or service accounts.
• Account for cloud registry token expiration and automate secret rotation.
• Validate network reachability and DNS so auth fixes can actually succeed.