Kubernetes image pull policies control when Kubelet should fetch an updated image version. Pull policies are used when a new Pod is starting up. Kubelet will take the appropriate action indicated by the Pod’s policy.
The Default Behaviour
You don’t have to specify an image pull policy. When a Pod lacks a policy, Kubernetes will infer your intentions from the image’s tag. If you’ve supplied a specific tag (such as my-image:my-release), the image will only be pulled if the tag doesn’t already exist on the Kubelet node. This policy is called IfNotPresent.
When no tag is specified, or you’re using the latest tag, the image will always be pulled. Kubernetes will fetch the image’s manifest every time a new Pod starts. If the manifest indicates a change, the updated image will be pulled before the containers are created.
Kubernetes will never modify imagePullPolicy as a consequence of another action. Editing a Pod’s image will not trigger Kubernetes to re-evaluate the default pull policy. That means that if you start with my-image:latest but later update the Pod to my-image:my-release, the image pull policy will still be IfNotPresent. You should manually specify a new policy if one is desired.
Making Kubelet Always Pull
You’ll need to apply an image pull policy to force Kubelet to always attempt a pull. Set imagePullPolicy: Always on a Pod to enable this behaviour.
New image versions will be pulled whenever a Pod starts and the image’s manifest digest has changed. A locally cached version of the image will still be reused if the digest hasn’t changed. This avoids unnecessary downloads over the network. Docker digests are immutable references that uniquely identify images without a name or tag.
Forced pulls are useful when you want to distribute new versions of your image using the same tag. This might be the case when you tag images using the branch name they’ve been built from. Without the Always policy, Kubernetes would never pull your new image releases if the tag was already available locally.
Banning Automatic Pulls
All the policies which permit image pulls will fetch new versions of your locally cached tags. Use an image digest as your Pod’s image field if you want a container to stick with an exact image version each time it starts.
There are scenarios where you might not want to Kubernetes to pull images at all. Setting the Never policy will prevent Kubelet’s automatic pulls. This policy won’t check for updates at all – the registry’s manifest version will not be fetched.
You’ll need an alternative way of getting images to your nodes if you use Never. Each image will need to exist locally before you try to start your Pods. Otherwise, Kubernetes won’t be able to run the Pod’s containers.
This acts as a protection mechanism when you’re using a standalone image pull mechanism. You won’t want Kubernetes to inadvertently attempt an automatic fetch in the event a pull fails. It could lead to the loss of images that are already locally cached.
Pull Policies and Caching
Your selected pull policy shouldn’t significantly impact performance. As long as your image provider supports layer caching, Kubelet will only need to pull the genuinely new layers in each image.
The Always policy does add a network call each time you start a new Pod. It only needs to check the image digest so this should be practically instantaneous. If the digest doesn’t match the locally cached version, then the new image layers will be pulled from the registry. The most significant performance overhead is the actual network transfer of those layers, followed by their subsequent decompression.
Summary
Kubernetes supports several behaviour models for image pulls. Images are handled by Kubelet and will be fetched whenever a Pod starts. The default policy will pull the image if the tag doesn’t already exist locally. If the image is untagged, or has latest as its tag, the Always policy will be used instead.
Setting the imagePullPolicy in your Pod specs makes the selected policy explicit. This helps all contributors to understand the chosen behaviour, even if they’re unfamiliar with the Kubernetes defaults. It’s particularly important if you’re using latest or untagged images, where Kubernetes applies special handling that could be confusing.
Remember that image pull policies are always set per-Pod by default. If you want to use one policy for your entire cluster, you’ll need to use a configuration validation tool to scan your Pod manifests. kube-score is a static analysis tool for Kubernetes object manifests that includes an imagePullPolicy check in its default ruleset. Run kube-score score my-manifest.yaml as part of a CI pipeline to prevent the use of manifests that lack a defined policy.
