Before you start
Linux-node Kubernetes clusters; Bash examples. Registry authentication and runtime trust are provider-specific. Documentation-reviewed on 2026-09-07; no image pulls or cluster changes performed.
Commands are examples, not actions run by this page. Replace the sample names and paths. Run related blocks in the same shell. Read the explanations before copying. Logs and configuration can contain private data; keep credentials and unredacted evidence out of public posts.
Validation: documentation-reviewed guidance, not a tested live-cluster repair.
Replace the placeholders and confirm the context before inspecting. A successful pull from your laptop does not validate the node's route, registry identity, architecture, or runtime trust store. Keep registry tokens out of terminals, tickets, screenshots, and copied commands.
1. Identify the exact image and failure
Inspect regular and init containers separately. A missing init image can prevent application startup. Capture the error time, requested image, and affected node. Separate a repeated BackOff message from the original registry or runtime error that explains it.
HELP_NS='REPLACE_NAMESPACE'
HELP_POD='REPLACE_POD'
kubectl config current-context
kubectl -n "$HELP_NS" get pod "$HELP_POD" -o wide
kubectl -n "$HELP_NS" get pod "$HELP_POD" -o jsonpath='{range .spec.initContainers[*]}{.name}{"\t"}{.image}{"\t"}{.imagePullPolicy}{"\n"}{end}{range .spec.containers[*]}{.name}{"\t"}{.image}{"\t"}{.imagePullPolicy}{"\n"}{end}'
kubectl -n "$HELP_NS" describe pod "$HELP_POD"This reads the effective Pod specification and events without triggering a new pull or replacing the workload.
kubectl -n "$HELP_NS" get pod "$HELP_POD" -o jsonpath='{.spec.serviceAccountName}{"\n"}{.spec.imagePullSecrets[*].name}{"\n"}'
HELP_PULL_SECRET='REPLACE_WITH_A_REFERENCED_SECRET_NAME'
kubectl -n "$HELP_NS" get secret "$HELP_PULL_SECRET" -o jsonpath='{.metadata.name}{"\t"}{.type}{"\n"}'Run the second query only for an actual referenced secret and only if authorized. Name and type are useful metadata; no data field is printed. Some clusters use node credential providers instead of Pod pull secrets.
2. Follow the specific error
A pull secret must exist in the Pod's namespace. A missing-secret event is different from credentials that exist but lack repository access. Likewise, changing the tag does not automatically change an already-defaulted imagePullPolicy; inspect the actual policy rather than relying on the spelling of latest.
| What you observe | What it suggests | Next step |
|---|---|---|
| The registry reports a missing manifest, unknown tag, or incompatible platform. | The reference may not identify a published artifact for this node. | Have the release owner verify repository, tag or digest, and target platform in the registry. Correct the managed workload to a reviewed compatible artifact, preferably a recorded digest. |
| Events report FailedToRetrieveImagePullSecret, unauthorized, or denied. | The reference, credential validity, or repository authorization needs investigation. | Correct the namespace-local reference or rotate the scoped credential through the approved secret manager. Confirm repository access; do not paste passwords into a kubectl command. |
| Events show timeout, name resolution, TLS, or rate-limit errors. | The node-to-registry path or registry policy may be the failing layer. | Ask the platform owner to check the affected node's resolver, egress, proxy, trust configuration, and registry quota. Do not disable certificate verification or assume Pod DNS is the pull path. |
| Unpacking fails with a no-space error. | An image may have downloaded but local runtime storage cannot complete preparation. | Correlate node filesystem evidence and follow the DiskPressure guide; do not delete runtime directories. |
3. Restore delivery without creating a restart storm
Make one approved change at its source of truth: release manifest, credential reference, registry permission, or node configuration. If a registry incident is external, repeated Pod deletion adds churn without restoring service. Preserve functioning replicas and the last approved artifact while the owner resolves the dependency.
Record the previous digest and configuration, then observe the existing retry or controlled rollout. A rollback is appropriate only to an available, compatible artifact and authorized configuration. Reverting to an expired credential is not recovery. Document which nodes were affected so a warm image cache on one node does not conceal an unresolved delivery path elsewhere.
Verify the fix
- Confirm the new container starts, the observed imageID corresponds to the intended artifact, and new pull errors stop.
- Verify readiness and the application's expected behavior; a successful download alone is not service recovery.
- Use a planned rollout or scheduled validation to confirm the required node population can obtain the image. Do not create test Pods or force pulls without approval.
Record the evidence, approved change, result, and rollback plan so the next administrator can follow your reasoning.
Avoid these shortcuts
- Do not expose dockerconfigjson data or put registry passwords in shell history.
- Do not switch indiscriminately to Always, latest, privileged mode, or insecure registries.
- Do not delete healthy replicas or assume a cached image proves registry access is fixed.
Primary sources and version checks
Check the documentation for your installed release. Provider, runtime, CNI, storage-driver, and distribution details can differ.