X
Popular Searches

Understanding Kubernetes Image Pull Policies

Graphic showing the Kubernetes logo

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.

spec:
  containers:
      - name: my-container
        image: my-image:my-release
        imagePullPolicy: Always
Advertisement

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.

Advertisement

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.

James Walker James Walker
James Walker is a contributor to CloudSavvy IT. He is the founder of Heron Web, a UK-based digital agency providing bespoke software development services to SMEs. He has experience managing complete end-to-end web development workflows, using technologies including Linux, GitLab, Docker, and Kubernetes. Read Full Bio »

The above article may contain affiliate links, which help support CloudSavvy IT.