Kubernetes Image Pull Policy – imagePullPolicy in Detail

Kubernetes Image Pull Policy

Kubernetes is an open-source platform for managing, scaling, and deploying containerized applications. Containerized applications run in isolated runtime environments called containers. 

For a container to exist and run, there needs to be an image from which it will construct the runtime environment and run the application. An image is a file that contains the source code, dependencies, libraries, tools, and other files needed for the application to run.

This article will discuss how Kubernetes manages images in running containers. And how you can explicitly define how and when Kubernetes should pull an image from its container registry using its Image Pull Policy feature. 

Image Management in Kubernetes

In Kubernetes, a node’s Kubelet and container runtime manage the containerized workloads. The Kubelet ensures containers are running and communicates with the container runtime how those containers should run.

When you create a deployment, the Kubelet reads the PodSpec (a YAML or JSON object that describes a Pod) and then instructs the container runtime using the CRI (Container Runtime Interface) to spin up containers to satisfy that spec. 

The container runtime pulls the image from the specified container registry and runs it. If you don’t specify a container registry hostname, Kubernetes will assume the image is in the Default Docker Registry. 

In the next section, you will see how you can tell Kubernetes to pull an image from its container registry to practicalize the above. 

Running a Container From an Image in a Container Registry

To pull an image from a container registry in a Kubernetes cluster, you need to:

  1. Use kubectl to create a Kubernetes Secret that contains the login credentials you use to access the container registry.  When creating Secrets with kubectl, you should use the latest version of kubectl. See the kubectl documentation.
  2. Then, specify the image to pull from the container registry, including the repository location and the Secret you created for authentication, in the application’s manifest file.


Before you see how to perform the above two steps, ensure you have the following prerequisites:

  1. Access to a container registry.
  2. The kubectl command-line tool configured to communicate with your cluster using your cluster’s KUBECONFIG configuration file.

Note: The next instructions in this article assume you are storing Docker images in your container registry and using the Docker CLI.  

Creating the Secret

To create the Secret, in your terminal window, run the following command:

$ kubectl create secret docker-registry <secret_name> \
    --docker-server='<your_registry_url>' \
    --docker-username='<your_registry_username>' \
    --docker-password='<your_registry_auth_password>' \

 In the above command:

  • <secret_name> will be the Secret name of your choice, for example, registry-secret. You will use the name when referring to the Secret in your resource manifest file. 
  • <your_registry_url> will be the URL to your container Registry. In most cases, it will include the region it is hosted in. For example, if your container registry is Amazon ECR, your registry URL will take the following form: <aws_account_id>.dkr.ecr.<aws_region>.amazonaws.com.
  • <your_registry_username> will be your username when accessing the container registry. 
  • <your_registry_auth_password> will be the password to your username.
  • <your_email_address> will be your email address. 

After running the above command, confirm that your Secret was created with the kubectl get secrets command. You can now use it to authorize the image pulling from your container registry. 

Note: You can enable Kubernetes to use a Secret(s) for every new Pod that gets created; to do so, add the Secret to the default service account using the following command:

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

Specifying the Image to Pull From a Container Registry Along With the Secret to Use

To pull an image from a container registry in Kubernetes, you define the Pod specification similar to the below:

apiVersion: v1
kind: Pod
  name: <pod_name>
    - name: <container-name>
      image: <registry_url>/<repository_name>:<image_tag>
      - name: <port_name>
        containerPort: 8080
        protocol: TCP
    - name: <secret_name>

In the above PodSpec:

  • The containers section specifies the name choice and location (URL) of the image you want to pull from a Container Registry, along with the image tag and other deployment details. 
  • The imagePullSecrets section specifies the name of the Secret you created to access the container registry.

So far, you’ve learned how Kubernetes manages container images. Next, you will learn how to use the imagePullPolicy specification.

Image Pull Policy

The imagePullPolicy specification lets you specify how you want the Kubelet to pull an image if there’s any change (restart, update, etc.) to a Pod. When using the imagePullPolicy specification, you have three options:

  1. IfNotPresent: If you set the imagePullPolicy to IfNotPresent, Kubernetes will only pull the image when it doesn’t already exist on the node.
  2. Always: With your imagePullPolicy set to Always, Kubernetes will always pull the latest version of the image from the container registry. 
  3. Never: If you set the imagePullPolicy to Never, there will be no attempts to pull the image. 

Default image pull policy

You may ask what happens when the imagePullPolicy specification isn’t defined in a manifest file — just like in the above manifest file. Well, in that case:

  • If the image tag is :latest, the imagePullPolicy will be automatically set to Always. 
  • If the image tag isn’t :latest, the imagePullPolicy will be automatically set to IfNotPresent. 
  • And if you don’t set any image tag, the imagePullPolicy will be automatically set to latest image and Always value.


When a kubelet starts creating containers for a Pod, it might be possible a container gets stuck in its “Waiting” state because of the ImagePullBackOff error status

The  ImagePullBackOff error means that a container couldn’t start because Kubernetes could not pull the image for reasons such as:

  • An invalid image name, 
  • Pulling from a private registry without an imagePullSecret or using an incorrect imagePullSecret, etc. 

The BackOff part indicates that Kubernetes will keep attempting to pull the image, with an increasing “back-off“ delay.

Key Points

In this article, we learned how Kubernetes manages images and how to explicitly define how and when Kubernetes should pull an image from a container registry using the ImagePullPolicy specification. 

If you need more help managing the complexities and compliance challenges of using Kubernetes check out SpaceliftIt brings with it a GitOps flow, so your Kubernetes Deployments are synced with your Kubernetes Stacks, and pull requests show you a preview of what they’re planning to change.

It also has an extensive selection of policies, which lets you automate compliance checks and build complex multi-stack workflows. You can also use Spacelift to mix and match Terraform, Pulumi, AWS CloudFormation, and Kubernetes Stacks and have them talk to one another. Find out more about how Spacelift works with Kubernetes.

The Most Flexible CI/CD Automation Tool

Spacelift is an alternative to using homegrown solutions on top of a generic CI. It helps overcome common state management issues and adds several must-have capabilities for infrastructure management.

Start free trial