Before learning the tool, it helps to feel the problem that the tool removes.

Software never stops changing

A living application changes all the time. Developers fix bugs, add features, patch security holes and update libraries. In a modern team, a new version may be released many times a week, or even many times a day. Each release means that the copies of your application running in the cluster must be replaced by copies of the new version.

The naive way: stop everything, then start everything

The simplest method is to stop all the old copies and start all the new ones. This is easy to understand, but it has a serious cost: for the period between the last old copy stopping and the first new copy becoming ready, nobody is serving your users. For a hobby project, a few seconds of silence may not matter. For an online shop, a hospital system or a bank, even a short outage is unacceptable, and a long one can be very expensive.

The second problem: releases go wrong

Even carefully tested code can misbehave in the real world. A new version may crash under real traffic, run out of memory, or fail to connect to a database. If all copies were replaced at once, the mistake would hit every user instantly. A gradual replacement limits the damage: if the first new copies look unhealthy, the release can be paused or reversed while most users are still being served by the old, working version.

A rolling update is the default way Kubernetes replaces old Pods with new ones, gradually and safely.

The plain definition

A rolling update is an update strategy in which Kubernetes creates Pods of the new version and removes Pods of the old version in small steps, until all Pods run the new version. During the process, the application stays available, because at every moment a sufficient number of Pods is ready to serve requests.

You state what you want, for example “run this new image version”, and Kubernetes works out the careful sequence of steps by itself. You do not have to tell it which Pod to remove first or when to start the next one.

Where it is used

Rolling updates are the default for Deployments, which are the most common way to run stateless applications in Kubernetes. Similar gradual behaviour is available for StatefulSets and DaemonSets, with rules suited to their own needs. Nearly every team that runs a web service, an interface for other programs or a background worker on Kubernetes uses rolling updates every day.

What it needs from you

A rolling update is one of several ways to release software. Knowing the others shows when each fits.

To understand the process, you need a quick picture of the cluster around it.

The main players

A rolling update involves several parts of Kubernetes working together. None of them controls the whole process. Each reacts to what it sees, and the result is a smooth rollout.

flowchart TD
  U["Operator changes the image version"] --> D["Deployment"]
  D --> C["Deployment controller"]
  C --> N["New ReplicaSet for new version"]
  C --> O["Old ReplicaSet for old version"]
  N -->|"scale up gradually"| PN["New Pods"]
  O -->|"scale down gradually"| PO["Old Pods"]
  PN --> S["Service"]
  PO --> S
  S --> USERS["Users keep being served"]
        

Read the picture from the top. You change the Deployment. The controller creates a second ReplicaSet for the new version and then slowly grows it while shrinking the old one. The Service sits in front of both, sending users only to Pods that are ready. From the users’ point of view, nothing happens. From the cluster’s point of view, a careful hand-over is in progress.

Not every change causes a rollout. Knowing exactly what does saves both surprise and confusion.

The rule: the Pod template changed

A Deployment contains a blueprint for its Pods, called the Pod template. A rolling update starts when, and only when, this template changes. The template includes the container image, its version tag, environment settings, resource requests and limits, health check settings, labels and notes on the Pod, the start command and the list of attached volumes.

Two classic traps

Two simple settings decide how fast and how carefully a rolling update moves.

Max surge

Max surge is how many extra Pods, beyond the desired number, may exist during the update. It lets Kubernetes start new copies before it removes old ones. A larger surge means faster updates, but needs more spare room in the cluster.

Max unavailable

Max unavailable is how many Pods may be missing from the desired number during the update. It lets Kubernetes remove old copies before every new one is ready. A larger value means faster updates, but leaves fewer Pods to serve users at any moment.

The defaults and how the numbers work

By default, both settings are twenty-five percent. Each may be given as a whole number or as a percentage of the desired replica count. Percentages are rounded: the surge is rounded up and the unavailable count is rounded down. The two may not both be zero, because then the update could never move.

A worked example with four copies

Suppose the Deployment wants four copies, and both settings use the default twenty-five percent. A quarter of four is one, so at most one extra Pod may exist and at most one may be missing. That means the total number of Pods never exceeds five, and at least three are always available. The table below shows a typical, simplified sequence. Real updates move in small overlapping steps depending on how quickly Pods become ready.

Now let us follow one release from the moment you change the version to the moment the last old Pod disappears.

sequenceDiagram
  participant Op as Operator
  participant API as API Server
  participant DC as Deployment controller
  participant New as New ReplicaSet
  participant Old as Old ReplicaSet
  participant Svc as Service
  Op->>API: Change image version
  API->>DC: Template changed
  DC->>New: Create with zero Pods
  DC->>New: Scale up within surge limit
  New-->>Svc: New Pod becomes ready
  DC->>Old: Scale down within unavailable limit
  Old-->>Svc: Old Pod removed from targets
  DC->>New: Scale up again
  DC->>Old: Scale down again
  Note over New,Old: Repeat until the old version has no Pods
        

The most important ingredient of a safe update is a truthful readiness check.

What readiness means

A readiness check is a small test that Kubernetes runs against a container to ask, “are you ready to serve users right now?” The test may ask a program to answer a simple request, open a network connection or run a small command. Until it passes, the Pod receives no traffic, and, crucially for updates, the Pod does not count as available.

What goes wrong without it

Minimum ready time

The Deployment also has a setting called the minimum ready time. It says how many seconds a new Pod must stay ready, without crashing, before it counts as available. The default is zero. A small value, such as ten to thirty seconds, catches copies that pass the first check but crash a moment later, before the rollout moves on and removes more old Pods.

Starting new Pods is only half the story. Old Pods must leave without dropping the requests they are serving.

What happens to an old Pod

When the controller removes an old Pod, Kubernetes marks it as terminating and begins to take it out of the Service’s list of targets. In parallel, the kubelet on its machine runs any pre-stop step, then sends a polite stop signal to the program, and waits for a grace period, thirty seconds by default. If the program is still running after that time, it is stopped by force.

The hidden race

Steps two and four happen at almost the same time. If the program stops instantly on receiving the signal, a few requests that were already on their way may still reach it and fail. This is a well-known cause of small bursts of errors during otherwise smooth updates. The cure is a short pause before shutdown, achieved with a pre-stop step or by having the program keep serving for a few seconds after the signal arrives.

You are not a passenger. You can watch, pause, resume and reverse a rollout while it happens.

Recording why a change happened

The history lists revisions, but not the reasons behind them. You can attach a short note, called a change cause, to each revision. It might say “upgrade to version three point two” or “fix login bug”. Six months later, when someone asks why the version changed, the note is worth its weight in gold.

Rollback is a rollout too

When you undo a release, Kubernetes does not rewind time. It simply makes the old version’s template the desired state again and performs another rolling update, growing the old ReplicaSet and shrinking the new one with the same careful rules. This is why keeping old ReplicaSets matters, and why deleting them by hand removes your ability to go back.

A rollout that cannot make progress is not a disaster. It is the safety system doing its job.

What a stuck rollout looks like

If new Pods never become ready, the controller stops removing old ones. The result is a half-finished update: some copies at the old version, some at the new, and the rollout status waiting. Your users are still being served by the old copies, which is exactly the protection you wanted.

The progress deadline

The Deployment has a setting called the progress deadline, ten minutes by default. If no progress is made within that time, Kubernetes marks the Deployment as not progressing and records the reason. It is important to understand that Kubernetes does not undo the release on its own. It reports the situation, and leaves the decision to you or to your automation.

flowchart TD
  R["Rollout is not finishing"] --> Q{"New Pods created?"}
  Q -->|"No"| A1["Check quota and Deployment events"]
  Q -->|"Yes but Pending"| A2["Not enough room or unmet placement rules"]
  Q -->|"Yes but image error"| A3["Check image name, tag and credentials"]
  Q -->|"Yes but crashing"| A4["Check logs and last exit reason"]
  Q -->|"Yes but not ready"| A5["Check readiness check and dependencies"]
  A1 --> F["Fix the cause or undo the release"]
  A2 --> F
  A3 --> F
  A4 --> F
  A5 --> F
        

The hardest part of rolling updates is not Kubernetes. It is your own application.

During a rolling update, the old and the new versions of your application serve users at the same time, sometimes for minutes. They read and write the same database, call the same services and may handle successive requests from the same user. If the two versions cannot coexist, users will see errors even though Kubernetes did everything right.

Where clashes appear

The safe habit: change in two steps

Other kinds of workloads update gradually too, but with rules that fit their nature.

StatefulSets: one at a time, in reverse order

A StatefulSet runs programs that remember things, such as databases, and gives each Pod a fixed number and its own storage. Its rolling update replaces one Pod at a time, starting from the highest number and working down. It waits for each new Pod to be running and ready before touching the next. This careful order protects clustered programs and their data.

A StatefulSet also has a partition setting. It tells the update to change only the Pods whose numbers are at or above a chosen value, leaving the lower ones alone. This makes it easy to try a new version on a few Pods first, in the style of a canary, before finishing the rest.

DaemonSets: one Pod per machine

A DaemonSet runs one Pod on each machine, for example a log collector. Its rolling update replaces Pods machine by machine, by default one machine at a time. A surge option, in newer versions, lets a new Pod start before the old one on the same machine stops, reducing gaps for services such as log collection or networking.

The manual alternative

Both kinds also offer an option where Kubernetes does not replace Pods on its own. Instead, a new version is applied to a Pod only when someone deletes that Pod by hand. This gives complete control for delicate systems, at the cost of doing the work manually.

Zero downtime is not a switch. It is the result of several small decisions working together.

A release is the moment when new code enters your system. It deserves careful protection.

Who may release

Changing a Deployment’s Pod template is a powerful act: it decides which code runs in production. Kubernetes access control lets you decide who may update Deployments, and in which namespaces. Give release rights only to trusted people and automation, and prefer a reviewed pipeline over hand-typed commands.

What enters the cluster

A rollout is not finished when the last Pod starts. It is finished when you know the new version is healthy.

The counts a Deployment reports

Signals of user experience

The counts tell you about Pods, not about people. Alongside them, watch what users feel: error rates, response times, the number of restarts, and any business signals such as completed orders. Compare the numbers before, during and after the release. A rollout that completes cleanly but doubles the error rate is a failed release, and the counts alone would never tell you.

These mistakes appear again and again in real teams. Learn to recognise them early.

A short checklist of good habits, in the order you are likely to need them.

See how ordinary teams use rolling updates every day.

Every strategy has strengths and limits. Knowing both keeps your expectations realistic.

Quick answers to the questions beginners ask most often.

It is the default way a Deployment replaces old Pods with new ones gradually, keeping enough healthy Pods in service so that users are still served during the release.

A change to the Pod template, such as a new image version, new environment settings, or a restart request. Changing only the replica count does not start one.

Max surge is how many extra Pods may exist during the update. Max unavailable is how many Pods may be missing. Together they set the pace and the safety margin.

The Pod template did not change, so no rollout began. Restart the Deployment, or give the bundle a new name or content fingerprint so that the template changes.

Run several copies, set max unavailable to zero with a small surge, use truthful readiness checks, shut down gracefully and keep old and new versions compatible.

No. It stops making progress and reports that the Deployment is not progressing after the progress deadline. You, or your pipeline, must decide to fix or undo.

Use the rollout undo action, optionally naming a revision. It performs another rolling update back to the earlier Pod template.

New Pods are probably Pending, failing to pull their image, crashing or not becoming ready. Describe the Deployment and new Pods and read the events to find the cause.

No. They protect against voluntary disruptions such as draining machines. A Deployment’s rolling update follows its own surge and unavailable settings.

Yes. Pausing freezes the rollout partway, letting you inspect the new copies. Resuming continues it. It also lets you batch several changes into one rollout.

Not for production. It hides which version is running, can differ between machines, and makes rollbacks unreliable. Use unique, immutable tags or digests.

One Pod at a time, from the highest number down, waiting for each to be ready. A partition setting lets you update only some Pods first.

You began this guide in a restaurant, where a wise manager retrains her waiters one at a time so the doors never close. A rolling update does the same for your application. Kubernetes creates a new ReplicaSet for the new version and gradually shifts Pods from the old one to the new, guided by two dials, max surge and max unavailable, and by the readiness checks that decide when a new copy truly counts. You learned what triggers a rollout, how old Pods leave gracefully, how to watch, pause and undo a release, how to diagnose a stalled rollout, and how to design your application and your settings for zero downtime. Above all, you learned that the strategy protects you only as far as your health checks, your compatible versions and your habits allow. Get those right, and releases become gloriously boring.