Introduction

When you push a new version of your container image but keep the same tag (such as latest), Kubernetes will not automatically pull the updated image. Existing Pods continue running the cached version from the node. To force Kubernetes to pull the latest image, you need to trigger a rolling update. This article explains how rolling updates work, how to configure your Deployment to always re-pull images, and the kubectl commands that make it happen.

How Rolling Updates Work

A rolling update replaces Pods in a Deployment incrementally. Instead of terminating all old Pods at once and starting new ones, Kubernetes creates a new Pod, waits for it to become ready, then terminates an old Pod. This cycle repeats until all Pods run the updated specification. The application stays available throughout the process because there are always running Pods serving traffic.

Two parameters control the pace of the rollout.

maxSurge defines how many extra Pods can exist above the desired replica count during the update. A value of 1 means Kubernetes can create one additional Pod before removing an old one.

maxUnavailable defines how many Pods can be unavailable at any point during the update. A value of 0 ensures that the full replica count is always maintained.

Configuring imagePullPolicy

Before triggering a rolling update, make sure your Deployment is configured to pull the image every time a new Pod starts. Set imagePullPolicy: Always in the container spec.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: my-app
5spec:
6  replicas: 3
7  selector:
8    matchLabels:
9      app: my-app
10  strategy:
11    type: RollingUpdate
12    rollingUpdate:
13      maxSurge: 1
14      maxUnavailable: 0
15  template:
16    metadata:
17      labels:
18        app: my-app
19    spec:
20      containers:
21        - name: my-app-container
22          image: my-registry/my-app:latest
23          imagePullPolicy: Always
24          ports:
25            - containerPort: 8080
26          readinessProbe:
27            httpGet:
28              path: /health
29              port: 8080
30            initialDelaySeconds: 5
31            periodSeconds: 10

Without imagePullPolicy: Always, Kubernetes uses the cached image on the node if it already exists. This is the default behavior when you use a named tag other than latest.

Triggering a Rolling Update

There are several ways to trigger a rolling update that forces Kubernetes to re-pull the image.

Method 1: Change the Image Tag

The cleanest approach is to use a new tag for every build (such as a git commit SHA or a semantic version). Update the image reference in the Deployment.

kubectl set image deployment/my-app my-app-container=my-registry/my-app:v1.2.3

Because the image reference changed, Kubernetes treats this as an update and creates new Pods that pull the new image.

Method 2: Restart the Deployment

If you pushed a new image with the same tag, you can restart the rollout without changing the manifest. This command triggers a rolling restart by adding a timestamp annotation to the Pod template.

kubectl rollout restart deployment/my-app

Each new Pod will pull the image fresh because of the imagePullPolicy: Always setting.

Method 3: Patch with an Annotation

You can also force a rollout by patching the Pod template with a dummy annotation.

kubectl patch deployment my-app -p \
  "{\"spec\":{\"template\":{\"metadata\":{\"annotations\":{\"restart-timestamp\":\"$(date +%s)\"}}}}}"

This changes the Pod template, which triggers the Deployment controller to start a rolling update.

Monitoring the Rollout

After triggering the update, watch its progress.

kubectl rollout status deployment/my-app

This command blocks until the rollout is complete and prints status updates along the way. You can also check individual Pod statuses.

kubectl get pods -l app=my-app -w

The -w flag watches for changes in real time, so you can see old Pods terminating and new Pods starting.

Rolling Back

If the new image causes problems, roll back to the previous version immediately.

kubectl rollout undo deployment/my-app

Kubernetes keeps a history of Deployment revisions. You can inspect the history and roll back to a specific revision.

kubectl rollout history deployment/my-app
kubectl rollout undo deployment/my-app --to-revision=2

Common Pitfalls

1. Forgetting imagePullPolicy: Always. Without this setting, Kubernetes uses the cached image when the tag has not changed. The rolling update will create new Pods, but they will run the same old image. This is the most frequent reason re-pulls do not work as expected.
2. Using the latest tag in production. While convenient during development, the latest tag makes it impossible to tell which version is running. Use explicit version tags and update the image reference in the Deployment manifest for each release.
3. No readiness probes. Without readiness probes, Kubernetes considers a Pod ready as soon as the container starts. If the application takes time to initialize, traffic is routed to unready Pods during the rollout. Always define a readiness probe.
4. Setting maxUnavailable too high. If maxUnavailable is set to a large number or percentage, too many Pods can be terminated at once, reducing your application's capacity during the update. Start with maxUnavailable: 0 and maxSurge: 1 for the safest rollout.
5. Image registry authentication. If your registry requires credentials, make sure an imagePullSecret is configured in the Pod spec or the service account. Otherwise, new Pods will fail to pull the updated image and the rollout will stall.

Summary

To re-pull a container image using a rolling update in Kubernetes, set imagePullPolicy: Always in your Deployment, then trigger the update with kubectl set image, kubectl rollout restart, or a template annotation patch. Monitor the rollout with kubectl rollout status and roll back with kubectl rollout undo if needed. The safest approach is to use explicit image tags for every build rather than relying on mutable tags like latest.