Image Pull Policies

What Is an Image Pull Policy?

When Kubernetes starts a container, the kubelet on the node must obtain the container image. The imagePullPolicy field controls when and whether the image is downloaded from the registry.

Pull Policy Options

Policy	Behavior	When to Use
Always	Pull the image every time the container starts	When using latest or mutable tags
IfNotPresent	Pull only if the image is not already on the node	Default for versioned tags — best for most cases
Never	Never pull — fail if the image is not already local	Pre-loaded images, air-gapped environments

Setting imagePullPolicy

apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
  - name: app
    image: my-app:v2
    imagePullPolicy: Always

Example with IfNotPresent

apiVersion: v1
kind: Pod
metadata:
  name: cached-app
spec:
  containers:
  - name: app
    image: nginx:1.27-alpine
    imagePullPolicy: IfNotPresent

Example with Never

apiVersion: v1
kind: Pod
metadata:
  name: local-only
spec:
  containers:
  - name: app
    image: my-local-image:dev
    imagePullPolicy: Never

Note: With Never, if the image doesn’t exist on the node, the Pod will fail with ErrImageNeverPull.

Default Behavior

Kubernetes applies defaults based on the image tag:

Image Tag	Default imagePullPolicy
latest (explicit or no tag)	Always
Specific tag (v1.2, sha-abc)	IfNotPresent

# No tag → treated as :latest → Always
- image: nginx
  # imagePullPolicy: Always (default)

# Explicit :latest → Always
- image: nginx:latest
  # imagePullPolicy: Always (default)

# Specific version tag → IfNotPresent
- image: nginx:1.27
  # imagePullPolicy: IfNotPresent (default)

Exam tip: This default behavior is frequently tested. Remember: no tag or latest = Always. Specific tag = IfNotPresent.

Why This Matters

Always

• Pros: Guarantees the latest version of the tag is used; catches tag updates
• Cons: Slower Pod startup (always contacts registry); fails if registry is unavailable
• Use case: Development, when latest tag is updated frequently

IfNotPresent

• Pros: Fast Pod startup if image is cached; works offline after first pull
• Cons: Won’t pick up new content pushed to the same tag
• Use case: Production with immutable versioned tags (recommended)

Never

• Pros: No registry dependency at all; fastest startup
• Cons: Image must be pre-loaded on every node
• Use case: Air-gapped environments, testing with locally-built images

Common Troubleshooting

ErrImagePull / ImagePullBackOff

# Check Pod status
kubectl get pod my-pod

# NAME      READY   STATUS             RESTARTS   AGE
# my-pod    0/1     ImagePullBackOff   0          2m

Common causes:

Error	Cause	Fix
ErrImagePull	Image not found in registry	Check image name and tag
ImagePullBackOff	Repeated pull failures	Check credentials, network, image name
ErrImageNeverPull	imagePullPolicy: Never and image not local	Pull image to node or change policy

# Diagnose the issue
kubectl describe pod my-pod | grep -A 10 "Events:"

# Example output:
# Failed to pull image "myapp:v99": rpc error: code = NotFound
#   desc = failed to pull and unpack image: not found

Debugging Steps

1. Check the image name and tag — Is the image in the registry?
2. Check imagePullPolicy — Is it set to Never when it shouldn’t be?
3. Check imagePullSecrets — Does the Pod have credentials for private registries?
4. Check node network — Can the node reach the registry?

# Verify image exists in registry
docker pull registry.example.com/team/my-app:v1

# Check Pod events for pull errors
kubectl describe pod my-pod

# Check if the image is on the node (if using Docker)
docker images | grep my-app

Image Pull Policy in Deployments

When you update a Deployment’s image tag, the pull policy determines whether the new image is actually pulled:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    spec:
      containers:
      - name: web
        image: my-app:v2
        imagePullPolicy: Always  # Ensures v2 is pulled fresh

Scenario: You push a fix to my-app:v2 in the registry (same tag, new content).

• Always — New Pods will pull the updated image ✅
• IfNotPresent — New Pods use the cached (old) image ❌
• Never — New Pods fail unless image is pre-loaded ❌

Best practice: Use immutable tags (like v2.0.1 or sha-abc123) with IfNotPresent instead of pushing new content to the same tag.

Quick Reference

Situation	Recommended Policy
Production with versioned tags	IfNotPresent (default)
Development with latest tag	Always (default)
CI/CD pipeline images	Always
Air-gapped / offline cluster	Never
Pre-loaded node images	Never