Resources

Kubernetes Image Pull Policy: A Definitive Guide

October 15, 2021

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": "pull-images-from-registry@darwin-imagepull-project.iam.gserviceaccount.com",
"client_id": "1234567",
"auth_uri": "https://accounts.google.com/o/oauth3/auth",
"token_uri": "https://accounts.google.com/o/oauth3/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth3/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/pull-images-from-registry%40darwin-imagepull-project.iam.gserviceaccount.com"
}

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) --docker-server=eu.gcr.io \
(out) --docker-username=darwin_key \
(out) --docker-password="$(cat ~/darwin.json)" \
(out) --docker-email=user@valid.email.provider.com

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
metadata:
 name: darwin
spec:
 containers:
 - name: app-container1
  image: eu.gcr.io/darwin-imagepull-project/app-container1
  imagePullPolicy: Always
 imagePullSecrets:
 - name: darwin-secret

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. 

Article by

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.

Read More