Start your free 14-day ContainIQ trial

Kubernetes Image Pull Policy: A Definitive Guide

In this article, we introduce image management, provide an example of building a container from an image, compare three different image pull policy options, and explain how to use each.

July 12, 2022
Sudip Sengupta
Solutions Architect

Introduction to Image Management in Kubernetes

In a Kubernetes ecosystem, for a container to stay alive, it needs to run an image. These images are a snapshot of a system or application’s entire state saved up in a non-volatile file format. An image represents how an application and its dependencies are packaged in binary format. When administering a Kubernetes application, it is necessary to create one or more images and have them stored in a repository where they can be pulled when they need to be referred into a POD. 

This article explores how Kubernetes images are managed and pulled, and the various applications of different image pull policies.

Container Registry

A registry is an images repository for development, testing, and access control.  With a container registry, software teams can perform security and vulnerability analysis on container images, improve functionality then deploy them to Kubernetes clusters. To use an image in a cluster, its name and registry are specified in the POD or Deployment configuration file. If a registry hostname is not provided, Kubernetes assumes the Default Docker Registry. 

Different versions of the same image may be needed for different use cases. Tags are added to image names to identify various versions and help isolate the different usage environments. If a tag is not specified in the manifest file, Kubernetes will automatically use the image tagged <terminal inline>latest<terminal inline>. 

Building a Container from an Image (Example)

To pull an image from a container registry, the following two steps are required:

  1. Creating a Secret that contains the login credentials used to access the registry. PODs with this secret specified can pull images from the specified registry.
  2. The image is pulled from the cloud registry by specifying the image name and location in a POD Spec or Deployment YAML file.

For this demo, the article uses Google Cloud’s Container Registry (GCR), but the procedure remains generally similar for other container registries. Let us explore the steps in detail.

Creating the Secret 

Quick Note: The article assumes that a GCR repository is set up and the cluster’s KUBECONFIG configuration file has been properly set up. 

To create the Secrets file, one needs to create GCR credentials, and the process is outlined here. These keys can be downloaded in P12 or JSON format and could look similar to: 

"type": "service_account",
"project_id": "darwin-imagepull-project",
"private_key_id": "abcd1234efgh",
"private_key": "-----BEGIN PRIVATE KEY-----\nPRIVATEKEY\n-----END PRIVATE KEY-----\n",
"client_email": "",
"client_id": "1234567",
"auth_uri": "",
"token_uri": "",
"auth_provider_x509_cert_url": "",
"client_x509_cert_url": ""

Kubernetes can use this JSON key to access the GCR repository when pulling application images. To enable this, we create a secret named <terminal inline>darwin-secret<terminal inline>. This is performed by running the command:

$ kubectl create secret docker-registry darwin-secret \
(out) \
(out) --docker-username=darwin_key \
(out) --docker-password="$(cat ~/darwin.json)" \

To enable Kubernetes to use this Secret for every new Pod, the secret is added to the default service account using <terminal inline>imagePullSecrets<terminal inline> as shown:

$ kubectl patch serviceaccount default \
(out) -p '{"imagePullSecrets": [{"name": "darwin-secret"}]}'

POD Configuration

Administrators may prefer to use the secret for one POD instead of an entire service account. In this case the secret is specified in the pod spec file. The spec file will look something like this:

apiVersion: v1
kind: Pod
 name: darwin
 - name: app-container1
  imagePullPolicy: Always
 - name: darwin-secret
Monitor Kubernetes Events in Real-Time
Monitor the health of your cluster and troubleshoot issues faster with pre-built dashboards that just work.
Learn More Book a Demo

Image Pull Policy Options

When creating the POD, one can specify the <terminal inline>imagePullPolicy<terminal inline>specification, which guides the Kubelet service on how to pull the specified image during an update. In the above example, it has been set to <terminal inline>Always<terminal inline>, which means Kubernetes should always pull the image from the registry when updating the container. 

There are three image policy pull options for Kubernetes. 

  1. If <terminal inline>imagePullPolicy<terminal inline> is set to <terminal inline>Always<terminal inline>, Kubernetes will always pull the image from the Repository. 
  2. With <terminal inline>IfNotPresent<terminal inline>, Kubernetes will only pull the image when it does not already exist on the node. 
  3. While with <terminal inline>imagePullPolicy<terminal inline> set to <terminal inline>Never<terminal inline>, Kubernetes will never pull the image. 

In case the specification is not stated on the manifest file, Kubernetes will set the policy depending on the image’s tag. If the image is tagged <terminal inline>latest<terminal inline>, then Kubernetes will assume the <terminal inline>imagePullPolicy<terminal inline>to be <terminal inline>Always<terminal inline>. An image with no tag is assumed to be <terminal inline>latest<terminal inline>, and so its policy is set to <terminal inline>Always<terminal inline>. Otherwise, the orchestrator will default the <terminal inline>imagePullPolicy<terminal inline> to <terminal inline>IfNotPresent<terminal inline>. 

Closing Thoughts

This article has been a high-level guide for image management in Kubernetes. Some concepts studied include container registry and deploying a Docker container using images from a repository. The article also covers Image Pull Policies in-depth, including the various options available. The Kubernetes Image Pull Policy is crucial for running both public images hosted on Docker, Private Repositories and clusters running on legacy images. 

Start your free 14-day ContainIQ trial
Start Free TrialBook a Demo
No card required
Sudip Sengupta
Solutions Architect

Sudip Sengupta is a TOGAF Certified Solutions Architect with more than 15 years of experience working for global majors such as CSC, Hewlett Packard Enterprise, and DXC Technology. Sudip now works as a full-time tech writer, focusing on Cloud, DevOps, SaaS, and Cybersecurity. When not writing or reading, he’s likely on the squash court or playing Chess.