The previous lesson ended with a very specific gap: a ReplicaSet keeps N copies of a template alive, but it does not know how to change version. You changed the template's image and the existing pods carried on quite happily with the old one. The Deployment is the piece that closes that gap and, by a wide margin, the object you will write most in your professional life with Kubernetes. It governs ReplicaSets and, through them, pods: it gives you replicas, self-healing, scaling, controlled updates, revision history and a way back. In this lesson you will understand the Deployment → ReplicaSet → Pod chain and exactly what each link contributes, you will finally turn the bare web-store pod into a 3-replica Deployment, you will create the bookings-api one, you will learn to read the columns of kubectl get deploy and the status conditions precisely, you will scale in two different ways and you will observe what happens in the cluster when an image changes. You will also finish knowing when a Deployment is not the right workload.

1. The Deployment → ReplicaSet → Pod chain
2. From bare pod to Deployment: web-store
3. The complete manifest, annotated
4. The bookings-api Deployment
5. Reading kubectl get deploy: READY, UP-TO-DATE, AVAILABLE
6. status, conditions and kubectl rollout status
7. Scaling: kubectl scale and the manifest
8. Observation: what happens when the image changes
9. When a Deployment is not the right workload

Kubernetes could have crammed all the functionality into a single object. It did not, and the reason is a good one: each level has one responsibility and only one.

The division of labour, in a table:

The key to understanding Deployments is this sentence: a Deployment does not manage pods, it manages ReplicaSets. Every time you change something in the template, the Deployment creates a new ReplicaSet and moves replicas from the old one to the new one. One ReplicaSet per revision, and each one knows how to maintain its own number of pods. The Deployment orchestrates the transfer.

That hexadecimal suffix in the names (web-store-7d9f8c6b4) is not random: it is the pod-template-hash, a hash computed over the contents of the template. The Deployment adds it as a label to every pod and to every ReplicaSet's selector, and that is how it ensures two ReplicaSets of the same Deployment never fight over the same pods. It is exactly the kind of set-based selector that, as we saw, the old ReplicationController could not express.

At the end of module 1 we left web-store as a bare pod, and we saw that deleting it did not bring it back. The time has come to settle that debt.

We start from an empty namespace, just as it was left at the end of the previous lesson:

Converting a pod into a Deployment always follows the same mechanical pattern:

In other words: the whole pod sinks one level and becomes the template, and replicas and selector appear above it.

What is new compared with the previous lesson's ReplicaSet, field by field:

• kind: Deployment, same apps/v1 group.
• metadata.annotations with kubernetes.io/change-cause: free text that will be recorded in the revision history as the "reason" for this rollout. We will make full use of it in the next lesson.
• spec.replicas: 3: three replicas of web-store. The Deployment does not create them itself; it delegates that to its ReplicaSet.
• spec.revisionHistoryLimit: 5: how many old ReplicaSets (with 0 replicas) are kept so you can undo. The default is 10.
• spec.selector: mandatory and immutable, just as in the ReplicaSet. And with the same warning: make it precise, app + environment.
• spec.template: identical to the ReplicaSet's. Here lies the conceptual key: any change under template triggers a new revision; changes outside it (such as replicas) do not.

spec.strategy does not appear because the default value, RollingUpdate, is the one we want. That field and all its parameters are the entire content of the next lesson, Updates, Rollbacks and Deployment Strategies.

Apply it:

There is the complete chain, made real in three blocks of output. You created one object and three levels appeared. Check the genealogy:

And look at the label the Deployment has added to the pods on its own:

You did not write pod-template-hash. The Deployment added it, and it is what will let it tell one revision's pods from another's.

Verify that it does now heal itself:

The bare pod in module 1 never came back. This one comes back in two seconds, and what brings it back is not the Deployment but its ReplicaSet, exactly as you learned in the previous lesson.

Second component. Same scheme, with the API's particularities.

Deliberate details in this manifest:

• replicas: 2: two are enough in development. In production the number will be decided by the autoscaling of module 9.
• terminationGracePeriodSeconds: 30 inside template.spec: remember from the Pods lesson that this is what stops a booking in flight from being cut off during a rollout.
• The response includes the pod name (process.env.HOSTNAME, which inside a pod is its name). This will help us in the Services lesson to demonstrate load balancing: each request will answer with a different pod.

Check that the API responds, using an ephemeral pod like the ones from the Pods lesson:

It works, but note the awkwardness: we had to find out the IP of a specific pod in order to talk to it. That IP will change on the next rollout. The problem is teed up for the Services lesson.

These three columns carry the densest information in all of Kubernetes, and confusing them leads to wrong diagnoses. All three count pods, but they count different things.

The useful way to read them is to ask what each discrepancy means:

An example of a half-finished update, which you will see a lot:

That reads as follows: there are 4 ready pods and the desired number is 4, but only 2 have the new version, and only 3 have been up long enough to count as available. We are in the middle of a rolling update, and pods from two revisions still coexist.

To see more, -o wide adds images and selector:

Like every Kubernetes object, a Deployment has a spec (what you ask for) and a status (what there is). The full status:

Conditions are Kubernetes' standard mechanism for expressing partial states, and a Deployment has three types:

The combination Available: True + Progressing: True with reason NewReplicaSetAvailable is the signature of a healthy, finished Deployment.

Another field worth attention is observedGeneration. Every change to the spec increments metadata.generation; the controller copies that number into status.observedGeneration once it has processed the change. If you see generation: 5 and observedGeneration: 4, the controller has not yet reacted to your latest change.

Day to day you do not read the JSON: you use the command that interprets it for you.

kubectl rollout status blocks the terminal until the rollout finishes and returns exit code 0 if it goes well, non-zero if it fails. That is why it is the instruction placed in any CI/CD pipeline right after kubectl apply: it turns "I have sent the change" into "the change is working". It accepts --timeout:

Rutas Norte has a bank-holiday weekend coming up and bookings-api replicas need raising. Two routes, the same as with the ReplicaSet.

Imperative, to react right now:

Note a hugely important detail:

No new ReplicaSet has appeared. Scaling does not change the template, so it is not a new revision: the same ReplicaSet goes from 2 to 4. This distinction —changes that create a revision versus changes that do not— is the backbone of the next lesson.

Declarative, the correct one according to the project conventions: edit replicas: 4 in k8s/base/bookings-api-deployment.yaml, commit and apply.

And a very common practical warning: if you scale with kubectl scale and do not carry the change into the file, the next kubectl apply will take the replicas back to the manifest's value. You will lose the extra capacity at the worst possible moment. That is the reason for the project rule: the cluster reflects Git, not the other way round.

A third route, useful for automating without editing files by hand:

Let's go back to 2 before moving on:

This is the observation that motivates the whole next lesson. Change the nginx version of web-store and look at the structure that appears, without worrying about the mechanism yet.

There are two ReplicaSets. The new one (5f6d8b9c7) has the 3 replicas; the old one (7d9f8c6b4) has dropped to 0 but has not been deleted. And there lies the key to the history: that empty ReplicaSet keeps the complete definition of the previous version, so going back is simply a matter of giving it its replicas again.

Compare that with what happened in the previous lesson when running kubectl set image against a ReplicaSet: nothing, the pods kept the old image. Here, by contrast, the pods are new and have the new image:

And the history already has two entries:

For now, take away these four observations:

1. Changing the template creates a new ReplicaSet, with a different pod-template-hash.
2. The Deployment shifts replicas from the old one to the new one gradually, not all at once.
3. Old ReplicaSets are kept at 0 replicas as history (up to revisionHistoryLimit).
4. During the transfer pods from two versions coexist, and that is what makes deploying without downtime possible.

How that transfer is controlled step by step —maxSurge, maxUnavailable, Recreate, pause, undo— is exactly the content of Updates, Rollbacks and Deployment Strategies. And the advanced variants, blue-green and canary, are waiting in 11-04.

Take web-store back to the original image so you start the next lesson from a known point:

The Deployment is the default option, but not the only one. It is designed for stateless, interchangeable, long-running workloads: its pods are cattle, not pets. They are named with random suffixes, they are created and destroyed in any order and none of them has an identity of its own.

When that does not fit, there is another object:

Applied to the six components of Rutas Norte:

A warning that prevents a classic mistake: redis-cache as a Deployment is only acceptable with one replica. If you scaled it to 3, you would have three independent caches behind the same name, and each bookings-api request would go to a different cache with different contents. The result would be erratic cache hits that are impossible to diagnose. Scaling is not free: it only works if the component is genuinely stateless.

• Forgetting spec.selector. It is mandatory in apps/v1. Without it, the API rejects the manifest.
• Trying to change the selector of an existing Deployment. It is immutable. If you need to, you have to delete the Deployment (with --cascade=orphan if you do not want to interrupt the service) and create a new one.
• Putting the labels only in the top-level metadata. The ones that govern the pods are in spec.template.metadata.labels. It is the most repeated beginner's mistake.
• Scaling with kubectl scale and not touching the file. The next apply will revert the change, probably at a bad moment.
• Confusing READY with AVAILABLE. READY means "it can serve"; AVAILABLE means "it can serve and has been stable for the minimum required time".
• Believing that kubectl apply waits for the rollout to finish. It does not wait: it only sends the object. To wait for real, chain kubectl rollout status.
• Using a Deployment for PostgreSQL. With more than one replica, several instances would try to mount the same volume and write at once. Corruption guaranteed.
• Scaling redis-cache to several replicas with a Deployment. You will get N incoherent caches, not one replicated cache.
• Tip: generate the skeleton with kubectl create deployment bookings-api --image=node:20-alpine --replicas=2 --dry-run=client -o yaml > deploy.yaml and add labels, resources and annotations afterwards.
• Tip: to see a component's complete chain at a glance, kubectl get deploy,rs,pods -l app=web-store. Three levels in a single command.

notifications-worker is a background process that consumes a queue and sends emails. It receives no inbound traffic, so it carries no ports and no Service.

Write k8s/base/notifications-worker-deployment.yaml with 2 replicas in rutas-norte-dev, image busybox:1.36, a command that writes sending batch of confirmations from <pod name> every 10 seconds, the project's three labels, terminationGracePeriodSeconds: 45 and requests of 50m/64Mi. Then:

1. Apply it and wait using the command that blocks until the rollout finishes.
2. Show the Deployment → ReplicaSet → Pod chain with a single command.
3. Check in the logs that both pods are working.
4. Explain why this component has a longer grace period than web-store.

A colleague sends you this capture from a preproduction cluster and asks for a diagnosis:

Answer, justifying each answer:

1. How many pods should exist and how many are ready?
2. How many have the new version?
3. Is the service down?
4. What has happened to the rollout?
5. Which two commands would you run, in that order, to find the root cause?

1. Create a bare redis-cache pod by hand in rutas-norte-dev with redis:7.2-alpine and the project's three labels.
2. Convert it into a 1-replica Deployment called redis-cache, writing the manifest and deleting the bare pod. Verify that the cache responds to redis-cli ping.
3. Scale the Deployment to 3 replicas and explain why this is a design mistake for Rutas Norte, even though it technically works. Go back to 1.
4. For each of the six Rutas Norte components, state the correct object and one sentence of justification.

Solution 1

4. The grace period is longer because notifications-worker may be halfway through sending an email when it receives the SIGTERM. If the kubelet kills it before it finishes, a customer who has paid for their ticket is left with no receipt and the message can end up in an ambiguous state (consumed from the queue but not sent). web-store only serves static files: its requests last milliseconds and 30 seconds is more than enough.

Solution 2

1. There should be 5 pods (spec.replicas = 5, the denominator of READY) and 3 are ready. Two are missing.
2. Only 2 have the new version (UP-TO-DATE). The other ready pods belong to the previous revision.
3. It is not down. Available: True with reason MinimumReplicasAvailable indicates there are enough available replicas to serve traffic. It is degraded, though: it is serving with 3 pods instead of 5.
4. The rollout has stalled: Progressing: False with reason ProgressDeadlineExceeded means it exceeded progressDeadlineSeconds (600 s by default) without advancing. The 2 pods of the new version never become ready, so the Deployment cannot carry on retiring the old ones. Typical cause: a non-existent image, CrashLoopBackOff from configuration or a badly tuned probe.
5. The two commands, in this order:

Solution 3

Practical note: kubectl exec deploy/redis-cache automatically picks one of the Deployment's pods, so there is no need to copy the name with its random suffix.

It is a design mistake because the three replicas do not form a replicated cache: they are three independent, empty caches, each with its own memory. When in the next lesson we put a Service in front, each bookings-api query will land on a different replica, so the seat availability written to replica A will not be found when reading from B. The result would be a cache hit rate of around 33 %, extra queries to bookings-postgres and, worst of all, inconsistent responses depending on which replica the request lands on. Replicating Redis properly requires a StatefulSet with replica or cluster configuration, the subject of module 6.

4. The correct object per component:

You now have a command of the object that holds up most of any Kubernetes platform. You have seen the Deployment → ReplicaSet → Pod chain with a clear-cut responsibility at every link: the pod keeps its containers alive, the ReplicaSet keeps the quantity, and the Deployment manages the versions. You know that a Deployment commands ReplicaSets rather than pods, and that the pod-template-hash is the trick that lets two revisions coexist without fighting over the same pods.

You have settled the debt we had been carrying since module 1: web-store is no longer a fragile pod but a 3-replica Deployment that recovers on its own in two seconds, and bookings-api has its own with 2 replicas. You can read the three columns of kubectl get deploy without confusing them —READY is what is serving, UP-TO-DATE what has the current version, AVAILABLE what has also been stable for the minimum time— and interpret the Available and Progressing conditions, the ones that will tell you in production whether a rollout is going well, is degraded or has stalled. You scale with kubectl scale to put out fires and with the manifest so the change lasts, and you know the cluster reflects Git and not the other way round. On top of that, you have the judgement not to force the tool: PostgreSQL calls for a StatefulSet, an agent per node calls for a DaemonSet, the nightly report calls for a CronJob, and scaling redis-cache to three replicas would break the cache's coherence.

The most interesting thing you have seen is still unexplained: on changing the image a second ReplicaSet appeared, the old one dropped to 0 replicas without being deleted and for a few seconds pods from two versions coexisted. That is not a side effect, it is the mechanism with which Rutas Norte will finally achieve its goal of zero downtime on deployments, against the one or two minutes of outage in the small hours of Tuesday. In the next lesson, Updates, Rollbacks and Deployment Strategies, we will control that transfer pod by pod with maxSurge and maxUnavailable, we will see why bookings-postgres would not tolerate a rolling update, and we will learn to diagnose and undo a broken rollout with kubectl rollout undo.