Mastering Kubernetes ImagePullPolicy: Always, IfNotPresent, Never

Previously in this course, we explored The Pod: The Smallest Unit of Execution and learned how to define these units in Creating Your First Pod Manifest. Now that you can define a Pod, you need to control how and when the cluster retrieves your application binaries from a Docker Registry.

Understanding ImagePullPolicy

When a Kubelet (the agent running on your worker node) receives a request to start a Pod, it checks if the required container images are already present on the local disk. If they aren't, it must reach out to the configured registry to download them. The imagePullPolicy field in your Pod manifest dictates the rules for this interaction.

Selecting the right policy is critical for two reasons: performance (avoiding unnecessary network traffic) and predictability (ensuring you are running the specific version of the code you intended).

The Three Policies Explained

You have three primary options for imagePullPolicy. Here is how they behave:

1. IfNotPresent (The Default)

If you don't explicitly set an imagePullPolicy, Kubernetes defaults to IfNotPresent (unless you are using the :latest tag, which we’ll cover in the pitfalls). The cluster checks the node's local cache; if the image exists, it starts the container immediately. This is the fastest way to spin up Pods.

2. Always

When set to Always, the Kubelet performs a registry check to see if the image digest has changed. If the image on the registry is different, it will pull the new version. This is helpful when you tag your images with a moving tag like :latest or :dev, ensuring that even if the tag name stays the same, the code is updated.

3. Never

This is a restrictive policy. If the image isn't already present on the node, the Pod will fail to start and enter an ErrImagePull state. This is useful in specialized infrastructure where you manually push images to nodes for security or network-restricted reasons.

Worked Example: Configuring the Policy

In your Pod manifest, the policy is nested under the containers specification. Here is a standard configuration using Always to ensure we get the freshest version of an application:

YAML
apiVersion: v1
kind: Pod
metadata:
  name: policy-demo
spec:
  containers:
  - name: my-app
    image: nginx:1.25
    imagePullPolicy: Always

If you apply this manifest, the Kubelet will verify the image with the registry every time the Pod is scheduled, even if nginx:1.25 is already cached on that specific node.

Hands-on Exercise

1. Create a new file named pull-test.yaml.
2. Set the imagePullPolicy to IfNotPresent.
3. Use a standard image like alpine:latest.
4. Apply the manifest with kubectl apply -f pull-test.yaml.
5. Run kubectl describe pod pull-test and look for the "Events" section to see if a "Pulling" event occurred.
6. Delete the pod and re-apply it; observe if the "Pulling" event happens the second time (it shouldn't, because the image is now cached).

Common Pitfalls

• The :latest Trap: If you use the :latest tag, Kubernetes automatically defaults imagePullPolicy to Always. This can lead to confusing behavior where your Pods intermittently fail if the registry is temporarily unreachable, even if you have an older version of "latest" cached locally. Best practice: Always use specific version tags (e.g., :v1.2.3) instead of :latest.
• Registry Authentication: If your registry is private, imagePullPolicy won't save you if you haven't configured a imagePullSecret. The Kubelet will fail to pull regardless of the policy setting.
• Over-reliance on Always: In a large cluster, setting Always on every single container can create a "thundering herd" problem where hundreds of nodes hit your registry simultaneously during a deployment, potentially rate-limiting your connection.

FAQ

Q: Can I change the policy on a running Pod? A: No. imagePullPolicy is an immutable field for existing Pods. You must delete the Pod and recreate it to apply a change to this setting.

Q: Does Always mean it re-downloads the entire image? A: Not necessarily. It checks the image digest. If the digest matches what is already on the disk, it skips the actual download to save bandwidth.

Recap

We’ve covered the three fundamental image pull policies: IfNotPresent, Always, and Never. By mastering these, you ensure that your production deployments remain stable and performant. You now know that IfNotPresent is your default friend, Always is for when you need to be absolutely sure you have the latest bits, and Never is for highly controlled, offline scenarios.

Up next: Running a Simple Web App — we’ll put these concepts to work by deploying a real Nginx server.