In the previous lesson we changed the image of web-store and observed something we deliberately left unexplained: a second ReplicaSet appeared, the old one dropped to zero replicas without being deleted, and for a few seconds pods from two versions coexisted. That mechanism is the Deployment's whole reason for being and the direct answer to the first of Rutas Norte's four goals: zero downtime on deployments, against the minute or two of outage that today forces deployments into the small hours of Tuesday. In this lesson we take control of that transfer. You will see the Deployment's two native strategies and when each one is required, you will calculate pod by pod what happens during an update of bookings-api, you will tune the pace with maxSurge and maxUnavailable, you will tell apart which changes generate a new revision and which do not, and you will handle the full kubectl rollout toolkit: status, history, undo, pause and resume. And you will finish by breaking a rollout on purpose with a non-existent image, diagnosing it and undoing it.

1. The two native strategies: RollingUpdate and Recreate
2. Why bookings-postgres cannot take RollingUpdate
3. maxSurge and maxUnavailable, step by step with bookings-api
4. Pace and tolerance: minReadySeconds, progressDeadlineSeconds, revisionHistoryLimit
5. What triggers a new revision and what does not
6. The full kubectl rollout toolkit
7. The kubernetes.io/change-cause annotation
8. Zero-downtime deployment: what it really takes
9. Diagnosing and rolling back a stalled deployment

spec.strategy.type accepts only two values. There are no other native strategies in Kubernetes: blue-green and canary, which you will see in 11-04, are built by combining these bricks with Services and Ingress.

It replaces the pods gradually: it brings up pods of the new version and retires the old ones little by little, always keeping a minimum number of pods serving.

It kills every old pod, waits for them to disappear, and only then creates the new ones. There is an interval, usually from seconds to a couple of minutes, with no pod serving at all.

How to declare it explicitly:

This is the key question of this section, and the answer teaches more than the strategy itself. Imagine bookings-postgres were a 1-replica Deployment with RollingUpdate and maxSurge: 1. During the update, this is what would happen:

1. Kubernetes creates the new pod before retiring the old one, because maxSurge: 1 allows it.
2. For a few seconds there are two simultaneous PostgreSQL processes.
3. Both try to mount and write to the same data directory.

Real consequences, in order of severity:

• Startup lock-out: PostgreSQL detects the live instance's postmaster.pid file and refuses to start. The rollout stalls (the benign case).
• Data corruption if the lock fails or the storage does not guarantee it: two processes writing to the same WAL files.
• Lost writes: bookings confirmed to the customer that are never recorded.

And there is a second reason, independent of the storage: schema migration. If the new version of bookings-api requires a column the old one knows nothing about, having both versions talking to the same database at once breaks one of them. With RollingUpdate that coexistence lasts minutes; with Recreate, it does not exist.

The honest conclusion: for bookings-postgres, the right answer is not Recreate, it is not to use a Deployment. Recreate is the appropriate strategy for single-replica workloads that cannot tolerate duplication but do not need a stable identity either, like our redis-cache.

Apply it to redis-cache, which you already deployed in the previous lesson:

Remember to carry that change into the manifest in Git as well.

These two parameters completely govern the pace of a rolling update.

Both accept an integer or a percentage. Percentages are rounded like this: maxSurge up and maxUnavailable down, so as to always err on the side of extra capacity. And there is one restriction: they cannot both be 0 at the same time, because then the rollout could not take a single step.

bookings-api with 4 replicas, maxSurge: 1 and maxUnavailable: 1. We update from version 2.4.0 to 2.5.0. The numbers that govern the whole process:

• Maximum simultaneous pods = replicas + maxSurge = 4 + 1 = 5
• Minimum available pods = replicas - maxUnavailable = 4 − 1 = 3

Set up the scenario:

The two important readings of that table:

• At no point are there fewer than 3 pods serving. Rutas Norte never loses total capacity, only 25 % for a few seconds.
• At no point are there more than 5 pods. The cluster needs room for one extra pod, not for eight.

In one terminal:

In another, launch the update:

And the replica count of each ReplicaSet during the process:

The Deployment is shifting replicas from one ReplicaSet to the other. That is, literally, all a rolling update does.

For Rutas Norte production, the recommended choice is maxSurge: 1 and maxUnavailable: 0: on a bank-holiday weekend with traffic multiplied by six, losing 25 % of capacity during a rollout is not acceptable.

Three fields that complete the control over a rollout.

minReadySeconds deserves a separate explanation because its effect is subtle but very valuable. With the default value of 0, as soon as a new pod says "I am ready", the controller retires another old one and carries on. If that pod crashes two seconds later, the damage is done: the rollout is advancing over a broken version. With minReadySeconds: 15, each new pod has to survive 15 seconds ready before counting. If it crashes sooner, the rollout stops.

progressDeadlineSeconds is the difference between a rollout that fails silently and one that raises the alarm. Without it, a rollout stalled by a non-existent image would keep trying forever without any alerting system noticing.

The bookings-api manifest with the three fields and the production strategy:

With this configuration, an update of bookings-api in rutas-norte-pro takes at least 4 × 15 = 60 seconds, and if something fails it is declared failed after 5 minutes instead of 10. Slowness in exchange for safety: on a component that handles ticket payments, that is an excellent trade.

This is the most important rule in the lesson and the most forgotten:

Only changes under spec.template trigger a new revision. Nothing else does.

The logic is transparent: a revision is a ReplicaSet, and one ReplicaSet is told apart from another by the hash of its pod template. If the template does not change, the hash does not change, and there is no new ReplicaSet to create.

Check it for yourself:

Same history: scaling is not deploying.

A practical consequence that surprises many people: changing a ConfigMap does not restart the pods that consume it, because the ConfigMap is not in the template, it is only referenced from it. The usual trick, which you will see in module 3, is to force a change in the template with a computed annotation, or to use directly:

rollout restart changes nothing functional: it writes a kubectl.kubernetes.io/restartedAt annotation inside the template, which alters the hash and triggers a gradual replacement of every pod. It is the correct, downtime-free way to "restart" a Deployment.

The syntax is <container-name>=<image>. The container name is the one in spec.template.spec.containers[].name, not the pod's. With several containers you can update them all at once by separating them with spaces.

A word on discipline: in a declarative project, the correct route is to edit the manifest and apply it. set image is for emergencies, and its change is lost on the next apply.

And the full detail of one particular revision:

That information comes entirely from the ReplicaSet at 0 replicas that was kept. That is why revisionHistoryLimit: 0 would leave you with no history and no rollback.

It goes back to the immediately previous revision. To go to a specific one:

Two important clarifications:

1. A rollback is just another deployment: it uses the same strategy, respects maxSurge and maxUnavailable, and therefore does not interrupt the service either.
2. Undoing does not delete the bad revision: it creates a new revision with the old one's content. If you were on 3 and you undo, you end up on 4, whose content is that of 2. The numbers never go backwards.

Notice that revision 2 has disappeared from the list: its ReplicaSet has been reused as revision 4.

With the Deployment paused, the changes you make are not applied. It is the tool for grouping several modifications into a single rollout:

Without pause, those three commands would have caused three chained rollouts, each one interrupting the previous. With pause, a single one and a single revision.

The other use of pause is for emergencies: if you see a rollout producing broken pods, kubectl rollout pause freezes it on the spot, leaving whatever old pods remain serving while you decide whether to fix or undo.

Summary table of the full toolkit:

You will have noticed the <none> entries in the CHANGE-CAUSE column. A revision history without reasons is nearly useless: three weeks later nobody remembers what revision 7 was.

kubernetes.io/change-cause is an annotation on the Deployment whose value is copied to that revision's ReplicaSet and shown in the history. Three ways to fill it in, from worst to best:

With kubectl annotate (quick, imperative):

In the manifest (the correct one according to the project conventions):

Automated in CI/CD, which is ideal:

A detail you already know from section 5, but worth repeating because it causes confusion: changing only this annotation does not trigger a new revision, because it lives in the Deployment's metadata and not in the template. Annotate it together with the real change, not afterwards.

Good practice for the text at Rutas Norte: image version, a plain-language summary of the change and the ticket reference. A real example from the project:

Here comes the most important warning of the lesson. You might think that with a well-configured RollingUpdate you already have zero-downtime deployments. You do not, and this is the number one cause of 502 errors during supposedly perfect rollouts.

The problem is that, with what we know so far, Kubernetes considers a pod "ready" as soon as the process starts. But a Node.js process takes a few seconds to load dependencies, connect to PostgreSQL and become operational. During that window:

1. The pod already counts as Ready.
2. The Deployment confidently retires an old pod.
3. The Service starts sending it real traffic.
4. The new pod still cannot respond: 502 errors.

The missing piece is called a readiness probe (readinessProbe): a check the kubelet runs against your application that decides whether the pod is genuinely ready to receive traffic. With it, step 1 of the diagram does not happen until the application truly responds.

The complete checklist for a genuinely downtime-free rollout at Rutas Norte:

In other words: RollingUpdate is necessary but not sufficient. Without probes, the rolling update advances blind. Until we get to module 7, minReadySeconds is a poor but useful substitute.

The final exercise and the most realistic of all. One Friday afternoon, somebody deploys a version to rutas-norte-dev that does not exist in the registry.

Reading: there are 5 ready and available pods —the service is still running on the previous version— but only 1 has the new version. The rollout took one step and stopped. This is the system working properly: maxUnavailable: 0 prevented any old pod being retired until the new one was ready, and since it never will be, none has been retired.

The new ReplicaSet has 1 pod that never reaches READY.

Root cause identified, using exactly the procedure from the Pods lesson.

Available: True (we are still serving) + Progressing: False with ProgressDeadlineExceeded (the rollout is dead) is the exact signature of a stalled deployment. In a monitored cluster, that combination should raise an alert.

Two options, depending on the moment:

An important warning: if the Deployment is paused, undo has no effect. You have to resume first.

The broken ReplicaSet stays at 0 replicas, consuming nothing, as a record of the incident. And the history tells the whole story to whoever reads it in six months' time.

The moral of the whole section: during those six steps, bookings-api did not miss a single booking. With the original Docker Compose setup, that same mistake would have left the platform down until somebody noticed. That is what a well-configured Deployment buys you.

Leave the cluster tidy before moving on:

• Believing that RollingUpdate guarantees zero downtime on its own. Without a readinessProbe, traffic reaches pods that cannot respond yet. It is the number one cause of 502s during rollouts.
• Setting maxSurge: 0 and maxUnavailable: 0. The API rejects it: the rollout could not advance.
• Using RollingUpdate with a workload that cannot tolerate two simultaneous versions. Single-replica databases, processes with an exclusive lock or incompatible schema migrations: those call for Recreate, or a StatefulSet outright.
• Setting revisionHistoryLimit: 0 to "save resources". ReplicaSets at 0 replicas consume neither CPU nor memory, just a few kilobytes in etcd. In exchange, you lose the ability to undo entirely.
• Expecting a change to spec.strategy or spec.replicas to trigger a rollout. They are not in the template. They only apply on the next real update.
• Expecting a change to a ConfigMap to restart the pods. It does not. Use kubectl rollout restart.
• Forgetting change-cause. A history full of <none> is no use at all when you have to decide which revision to go back to at three in the morning.
• Annotating the change-cause after the rollout. Since it does not trigger a revision, it stays attached to the Deployment but may not reflect what that revision did. Annotate it in the same apply.
• Running undo on a paused Deployment. Nothing happens until you resume. It is a classic of blind debugging.
• Trusting kubectl apply as verification. apply only says the API accepted the object. Always chain kubectl rollout status --timeout=... in your scripts.
• Tip: in production, maxSurge: 1 and maxUnavailable: 0. It costs one extra pod of capacity and guarantees you never drop below nominal capacity.
• Tip: kubectl rollout status returns a non-zero exit code if the rollout fails. That is what makes a CI/CD pipeline trustworthy: kubectl apply -f k8s/ && kubectl rollout status deploy/bookings-api --timeout=300s || kubectl rollout undo deploy/bookings-api.

web-store is in rutas-norte-pro with 6 replicas, maxSurge: 2 and maxUnavailable: 1.

1. What is the maximum number of simultaneous pods and the minimum number of available pods?
2. Build a table with the first five steps of the update, showing for each one: old pods, new pods, total and available.
3. If the platform team demands that the number of serving pods never drops below 6, what values would you set and what extra resources does the cluster need?
4. With the configuration from point 3 and minReadySeconds: 20, what is the theoretical minimum duration of the rollout if each pod takes 5 seconds to start?

On web-store in rutas-norte-dev:

1. Configure RollingUpdate with maxSurge: 1, maxUnavailable: 0, minReadySeconds: 10 and revisionHistoryLimit: 5, applying it from the manifest.
2. Update to nginx:1.27.1-alpine with its corresponding change-cause and wait for it to finish.
3. Update to nginx:1.26-alpine with another change-cause.
4. Show the history and the detail of revision 2.
5. Pretend 1.26 has a serious bug: go back to 1.27.1 and verify that all three replicas serve it.
6. Explain why the history does not show the numbering you would expect.

1. Break notifications-worker on purpose by deploying the image busybox:9.9.9-nonexistent, with a change-cause included.
2. With four commands, diagnose the problem following the correct order: Deployment state, ReplicaSets, guilty pod and conditions.
3. Answer: are the confirmation emails still being sent during the stall? Justify it with the commands' output.
4. Freeze the rollout, check that undo does nothing while it is paused, resume it and undo.
5. Document the rollback with an annotation and show the final history.

Solution 1

1. Maximum pods = replicas + maxSurge = 6 + 2 = 8. Minimum available = replicas - maxUnavailable = 6 − 1 = 5.

2. The first five steps:

3. To never drop below 6 serving: maxUnavailable: 0, and maxSurge at 1 or 2 depending on how fast you want to go. With maxSurge: 2, the cluster must have room for 8 web-store pods at once: with requests of 50m of CPU and 64Mi per pod, that is an extra 100m of CPU and 128Mi of memory free during the rollout. With maxUnavailable: 0 the cluster must have that capacity; if it does not, the new pods stay Pending and the rollout never advances.

4. With maxSurge: 2 and maxUnavailable: 0, pods are replaced in batches of 2. Each batch takes 5 s (startup) + 20 s (minReadySeconds) = 25 s. Six pods in batches of two make 3 batches: 75 seconds as a theoretical minimum, not counting image pulls or the old pods' termination time.

Solution 2

6. The numbering is surprising because revisions never go backwards. When you undo to revision 2, Kubernetes does not "return" to it: it reuses its ReplicaSet and renumbers it as revision 4, the most recent. That is why 2 disappears from the list and a 4 appears with the same change-cause. The revision number identifies the order in which the changes were applied, not the content: a rollback is just another change.

Solution 3

3. Yes, the emails are still going out. The proof is in three places: READY 2/2 and AVAILABLE 2 on the Deployment, the 2 pods of the previous revision in Running, and above all Available: True with MinimumReplicasAvailable in the conditions. Only UP-TO-DATE 1 gives away that a new version is trying to get in and failing. Direct confirmation:

The broken ReplicaSet still has 1 replica: the undo has been recorded but not executed, because the Deployment is paused.

You have closed the circle we opened in the previous lesson with that second ReplicaSet that appeared without explanation. You now know that the Deployment's two native strategies are RollingUpdate and Recreate, and why the choice is not a matter of taste but of the workload's nature: web-store, bookings-api and notifications-worker tolerate two versions coexisting and go with RollingUpdate; redis-cache does not, and goes with Recreate; and bookings-postgres takes neither, because a Deployment is not where it belongs: two PostgreSQL processes over the same data directory mean a lock-out in the best case and corruption in the worst.

You can work out a rollout on paper before running it: replicas + maxSurge is the ceiling of pods and replicas - maxUnavailable the floor of available ones, and with those two numbers you can reconstruct step by step what the controller will do with the 4 replicas of bookings-api. You know the useful combinations and the one recommended for production, maxSurge: 1 with maxUnavailable: 0, which protects nominal capacity on an August peak. You tune the pace with minReadySeconds, you detect stalls with progressDeadlineSeconds and you preserve your ability to undo with revisionHistoryLimit. You are clear on the rule that governs everything: only changes under spec.template create a revision, which is why scaling does not deploy, changing a ConfigMap restarts nothing and kubectl rollout restart exists. And you handle the full toolkit —status, history, undo, pause, resume— with change-cause documenting every step, including the rollback of a deployment stalled by a non-existent image, resolved without a single customer failing to buy their ticket.

One warning and one big gap remain. The warning: RollingUpdate is necessary but not sufficient for genuinely downtime-free deployments; without a readinessProbe, Kubernetes marks a pod whose process has just started as ready and sends it traffic before it can serve it. That piece arrives in Health Checks and Probes. And the gap: all the traffic we have spent two lessons talking about does not exist yet. Our pods have IPs that change on every rollout, and to talk to bookings-api we have had to look up a specific pod's IP by hand. In the next lesson, Services, we will give each Rutas Norte component a stable address that survives rollouts, load balancing across replicas included.