How to Use Image Pull Secret in Kubernetes

In Kubernetes, use imagePullSecrets in your Pod spec to provide credentials for pulling images from private registries. First, create a secret with kubectl create secret docker-registry, then reference it under spec.imagePullSecrets in your Pod or Deployment manifest.

Syntax

The imagePullSecrets field is used inside the Pod specification to tell Kubernetes which secret to use when pulling container images from private registries.

It looks like this:

• spec.imagePullSecrets: A list of secret names.
• Each secret contains credentials for the container registry.

yaml

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  containers:
  - name: example-container
    image: private.registry.com/myimage:tag
  imagePullSecrets:
  - name: myregistrykey

Example

This example shows how to create a Docker registry secret and use it in a Pod to pull an image from a private registry.

bash and yaml

kubectl create secret docker-registry myregistrykey \
  --docker-server=private.registry.com \
  --docker-username=myuser \
  --docker-password=mypassword \
  --docker-email=[e-mail]

---

apiVersion: v1
kind: Pod
metadata:
  name: private-image-pod
spec:
  containers:
  - name: private-container
    image: private.registry.com/myimage:latest
  imagePullSecrets:
  - name: myregistrykey

Output

secret/myregistrykey created
pod/private-image-pod created

Common Pitfalls

• Not creating the secret before referencing it in the Pod spec causes image pull failures.
• Using the wrong secret name in imagePullSecrets leads to authentication errors.
• Forgetting to specify imagePullSecrets when pulling from private registries results in "ImagePullBackOff" errors.
• Secrets must be in the same namespace as the Pod.

yaml

Wrong example (secret name typo):

apiVersion: v1
kind: Pod
metadata:
  name: wrong-secret-pod
spec:
  containers:
  - name: container
    image: private.registry.com/myimage:latest
  imagePullSecrets:
  - name: wrongname

Correct example:

apiVersion: v1
kind: Pod
metadata:
  name: correct-secret-pod
spec:
  containers:
  - name: container
    image: private.registry.com/myimage:latest
  imagePullSecrets:
  - name: myregistrykey

Quick Reference

Step	Command or Field	Description
1	kubectl create secret docker-registry	Create secret with registry credentials
2	spec.imagePullSecrets	Reference secret name in Pod spec
3	Secret and Pod in same namespace	Ensure secret is accessible to Pod
4	Check pod status	Use kubectl get pods to verify image pull success

Key Takeaways

Create a docker-registry secret with your private registry credentials before use.

Reference the secret name under spec.imagePullSecrets in your Pod or Deployment manifest.

Secrets must be in the same namespace as the Pod to be used.

Incorrect secret names or missing secrets cause image pull failures.

Use kubectl get pods to check if the image was pulled successfully.