Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Kubernetes Deployments: deploy, update, roll back

By updated

Improve this page

Logo Kubernetes

A Deployment declares the application you want (which image, how many Pods) and lets Kubernetes maintain and update it. In this lesson, you create a Deployment with a manifest and read its fields. You then follow a complete scenario: an update fails on a wrong image name, you read the history and you go back to the previous revision. Finally, you ship the right image with a change cause, and you check that the old ReplicaSet is kept at zero.

Prerequisites: the lesson Pods and the demo cluster from First cluster. You have already created a Deployment with kubectl create deployment in First deployment: here, you start from a manifest and look at the life of the Deployment after its first delivery.

What you will learn

  • Create a Deployment with a YAML manifest and read its fields
  • Update the image of a Deployment and follow the rollout
  • Read the history of a Deployment and go back to the previous revision
  • Ship the right image after a failure, with a change cause
  • Check that the old ReplicaSet is kept at zero replicas
  • Choose between RollingUpdate and Recreate, and tell a Deployment from a StatefulSet

Why use a Deployment rather than Pods?

A bare Pod is not replaced when it disappears and does not update cleanly. A Deployment solves both problems: it creates a ReplicaSet that maintains the desired number of Pods, and it replaces the Pods gradually when you change their template (the template). It also offers a return to a previous version with one command.

The Deployment suits stateless applications, whose Pods are interchangeable. A database or a message queue needs a stable identity and a stable disk, which is the job of a StatefulSet.

How do you create a Deployment?

Write the manifest and apply it. The web Deployment asks for three Nginx Pods, and keeps at most five old revisions:

Terminal window
kubectl config use-context kind-demo
kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 3
revisionHistoryLimit: 5
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
EOF
kubectl rollout status deployment/web --timeout=90s
kubectl get deployment web
Output
Switched to context "kind-demo".
deployment.apps/web created
Waiting for deployment "web" rollout to finish: 0 out of 3 new replicas have been updated...
Waiting for deployment "web" rollout to finish: 0 of 3 updated replicas are available...
Waiting for deployment "web" rollout to finish: 1 of 3 updated replicas are available...
Waiting for deployment "web" rollout to finish: 2 of 3 updated replicas are available...
deployment "web" successfully rolled out
NAME READY UP-TO-DATE AVAILABLE AGE
web 3/3 3 3 19s

The READY column counts the ready Pods out of the desired Pods, UP-TO-DATE the Pods that match the current template, and AVAILABLE the Pods available for traffic. All three equal 3 when everything is in order.

What does a Deployment create?

A Deployment does not manage the Pods itself: it creates a ReplicaSet, and the ReplicaSet creates the Pods. The kubectl get command reads the three objects at once, and the -l app=web filter keeps only those that carry this label:

Terminal window
kubectl get deployment,replicaset,pods -l app=web
kubectl get replicaset -l app=web -o wide
Output
NAME DESIRED CURRENT READY AGE
replicaset.apps/web-5f9ccb876d 3 3 3 19s
NAME READY STATUS RESTARTS AGE
pod/web-5f9ccb876d-mph9w 1/1 Running 0 19s
pod/web-5f9ccb876d-vpp26 1/1 Running 0 19s
pod/web-5f9ccb876d-w7l66 1/1 Running 0 19s
NAME DESIRED CURRENT READY AGE CONTAINERS IMAGES SELECTOR
web-5f9ccb876d 3 3 3 19s nginx nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb app=web,pod-template-hash=5f9ccb876d

The output shows only the ReplicaSet and the three Pods: the Deployment itself does not carry the app=web label, only the template of its Pods does.

The name of a Pod follows the format <deployment>-<ReplicaSet hash>-<5 random characters>: the hash comes from the Pod template, and the last five characters are drawn at random. The pod-template-hash label set by Kubernetes ties each Pod to its ReplicaSet.

Which fields should you read in a Deployment?

Two fields are mandatory, selector and template; replicas is 1 if you omit it. The last three in the table also have a reasonable default, but they decide the behavior during an update.

FieldRoleDefault
replicasNumber of desired Pods1
selectorLabels of the Pods the Deployment manages; must match those of the templatenone, mandatory
templateTemplate of the Pods created; changing it triggers a rolloutnone, mandatory
strategyHow to replace the Pods: RollingUpdate or RecreateRollingUpdate
revisionHistoryLimitNumber of old ReplicaSets kept to go back10
progressDeadlineSecondsTime before declaring a rollout stuck600

The rule to remember: only a change to the Pod template (template) creates a new rollout. Changing replicas adjusts the number of Pods without creating a ReplicaSet. The strategy settings are explained in Rolling updates and rollbacks.

How do you update a Deployment?

Change the image of the nginx container. To see what Kubernetes does when the update fails, first give it an image that does not exist (# ❌, non-existent tag, deliberate):

Terminal window
kubectl set image deployment/web nginx=nginx:1.30.999 # ❌ non-existent tag, deliberate
kubectl rollout status deployment/web --timeout=30s
Output
deployment.apps/web image updated
Waiting for deployment "web" rollout to finish: 0 out of 3 new replicas have been updated...
Waiting for deployment "web" rollout to finish: 1 out of 3 new replicas have been updated...
error: timed out waiting for the condition

The rollout status ends with an error after 30 seconds: the rollout does not finish. Look at the state of the ReplicaSets and the Pods:

Terminal window
kubectl get replicaset -l app=web
kubectl get pods -l app=web
Output
NAME DESIRED CURRENT READY AGE
web-5f9ccb876d 3 3 3 49s
web-6db96ccd45 1 1 0 30s
NAME READY STATUS RESTARTS AGE
web-5f9ccb876d-mph9w 1/1 Running 0 49s
web-5f9ccb876d-vpp26 1/1 Running 0 49s
web-5f9ccb876d-w7l66 1/1 Running 0 49s
web-6db96ccd45-99nrh 0/1 ErrImagePull 0 30s

The update created a new ReplicaSet, but its first Pod does not start for lack of an image. The rollout moves in small steps, and it stops as long as the new Pod is not ready.

Why does the application stay in service? With the default settings on 3 replicas, maxUnavailable (the number of Pods the update is allowed to make unavailable) is 25%, rounded down, so 0 Pods. Kubernetes therefore stops no old Pod before a new one is ready: the three old Pods keep serving, and your application is not interrupted. This is the protection of the rolling update.

How do you read the history and roll back?

Every change to the template is a revision. The history lists them:

Terminal window
kubectl rollout history deployment/web
Output
deployment.apps/web
REVISION CHANGE-CAUSE
1 <none>
2 <none>

The CHANGE-CAUSE column is empty: nothing said why the revisions exist. The section on the change cause fixes this further down. To undo the faulty update, go back to the previous revision:

Terminal window
kubectl rollout undo deployment/web
kubectl rollout status deployment/web --timeout=90s
kubectl get replicaset -l app=web
kubectl rollout history deployment/web
Output
Warning: resource deployments/web was previously managed with 'kubectl apply'. Rolling back will not update the kubectl.kubernetes.io/last-applied-configuration annotation, which may cause unexpected behavior on future 'kubectl apply' operations. Consider using 'kubectl apply' with your previous configuration file instead.
deployment.apps/web rolled back
Waiting for deployment spec update to be observed...
Waiting for deployment "web" rollout to finish: 1 old replicas are pending termination...
deployment "web" successfully rolled out
NAME DESIRED CURRENT READY AGE
web-5f9ccb876d 3 3 3 49s
web-6db96ccd45 0 0 0 30s
deployment.apps/web
REVISION CHANGE-CAUSE
2 <none>
3 <none>

Read the output: rollout undo brings the template of the Deployment back to the previous image. The ReplicaSet web-5f9ccb876d, the one for the image that worked, keeps its 3 Pods, and web-6db96ccd45, the one for the wrong image, drops to zero. The history now shows only revisions 2 and 3: revision 1 was taken over under number 3 (the renumbering is detailed in Rolling updates and rollbacks).

The Warning displayed by undo comes from the fact that the Deployment was created with kubectl apply: undo does not update the last-applied-configuration annotation, which does not matter here.

How do you ship the right image with a change cause?

Now ship the corrected image (the target version), then write the cause of the revision in the kubernetes.io/change-cause annotation, which feeds the CHANGE-CAUSE column. An annotation is a key-value note set on an object, which Kubernetes does not use for selection; the lesson Labels and annotations covers it in detail:

Terminal window
kubectl set image deployment/web nginx=nginx:1.30.6@sha256:42c68eab6f7e22611786a9fe1d1c019e275c50185bd54b8f75dc2b9184322703
kubectl annotate deployment/web kubernetes.io/change-cause="passage à nginx 1.30.6" --overwrite
kubectl rollout status deployment/web --timeout=90s
kubectl rollout history deployment/web
Output
deployment.apps/web image updated
deployment.apps/web annotated
Waiting for deployment "web" rollout to finish: 1 out of 3 new replicas have been updated...
[...]
Waiting for deployment "web" rollout to finish: 2 out of 3 new replicas have been updated...
[...]
Waiting for deployment "web" rollout to finish: 1 old replicas are pending termination...
[...]
deployment "web" successfully rolled out
deployment.apps/web
REVISION CHANGE-CAUSE
2 <none>
3 <none>
4 passage à nginx 1.30.6

The output shows revision 4 with its cause in the CHANGE-CAUSE column, while revisions 2 and 3 remain without a cause. Why the annotation must be rewritten at every delivery, and how to read the history, is explained in Rolling updates and rollbacks.

Finally, check that the old ReplicaSet is kept at zero, ready for a rollback:

Terminal window
kubectl get replicaset -l app=web -o wide
kubectl get pods -l app=web
Output
NAME DESIRED CURRENT READY AGE CONTAINERS IMAGES SELECTOR
web-5f9ccb876d 0 0 0 72s nginx nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb app=web,pod-template-hash=5f9ccb876d
web-6db96ccd45 0 0 0 53s nginx nginx:1.30.999 app=web,pod-template-hash=6db96ccd45
web-6fd8ff4b7c 3 3 3 23s nginx nginx:1.30.6@sha256:42c68eab6f7e22611786a9fe1d1c019e275c50185bd54b8f75dc2b9184322703 app=web,pod-template-hash=6fd8ff4b7c
NAME READY STATUS RESTARTS AGE
web-5f9ccb876d-w7l66 1/1 Terminating 0 73s
web-6fd8ff4b7c-g4bhm 1/1 Running 0 24s
web-6fd8ff4b7c-wmsnk 1/1 Running 0 8s
web-6fd8ff4b7c-xq6sl 1/1 Running 0 16s

The number of old ReplicaSets kept is limited by revisionHistoryLimit. A ReplicaSet at zero replicas runs no Pod and leaves only an object in the API: this is what makes the rollback fast.

How many Pods do you want?

To change the number of Pods without touching the template, change replicas: no new ReplicaSet is created.

Terminal window
kubectl scale deployment/web --replicas=5
kubectl rollout status deployment/web --timeout=90s
kubectl get deployment web
kubectl get replicaset -l app=web
Output
deployment.apps/web scaled
Waiting for deployment "web" rollout to finish: 3 out of 5 new replicas have been updated...
Waiting for deployment "web" rollout to finish: 3 of 5 updated replicas are available...
[...]
Waiting for deployment "web" rollout to finish: 4 of 5 updated replicas are available...
deployment "web" successfully rolled out
NAME READY UP-TO-DATE AVAILABLE AGE
web 5/5 5 5 74s
NAME DESIRED CURRENT READY AGE
web-5f9ccb876d 0 0 0 74s
web-6db96ccd45 0 0 0 55s
web-6fd8ff4b7c 5 5 5 25s

Automatically adjusting the number of Pods according to load is another subject, covered in the lesson on horizontal Pod autoscaling.

RollingUpdate or Recreate?

RollingUpdate, the default strategy, replaces the Pods in small groups: the old version still serves while the new one starts, so there is no downtime as long as the new Pods become ready.

Recreate deletes all the old Pods before creating the new ones: there is downtime, but never two versions at the same time. You choose it when two versions cannot coexist, for example because of a database schema. The fine settings are in Rolling updates and rollbacks. Blue-green and canary are compared in Deployment strategies.

What should you do when a Deployment does not progress?

Start from the symptom observed in kubectl get deployment, then go down one object at a time, from the Deployment to the ReplicaSet and then to the Pod.

What is displayedWhere to lookFrequent cause
READY stays below the desired numberkubectl describe deployment web (conditions) then kubectl get pods -l app=webA Pod does not start
rollout status times outkubectl get pods -l app=webImage not found, ImagePullBackOff
Pod in CrashLoopBackOffkubectl logs <name-of-a-web-pod> --previousThe application crashes at startup
Pods in Pendingkubectl describe pod <name-of-a-web-pod>No acceptable node

To read the events of a specific Pod, see the lesson Pods, and Debugging a Kubernetes application for the full method.

Clean up the cluster

Delete the Deployment to start again from a clean cluster: its Pods go to Terminating before disappearing.

Terminal window
kubectl delete deployment web
kubectl get pods -l app=web
Output
deployment.apps "web" deleted from default namespace
NAME READY STATUS RESTARTS AGE
web-6fd8ff4b7c-c8v8j 1/1 Terminating 0 1s
web-6fd8ff4b7c-g4bhm 1/1 Terminating 0 25s
web-6fd8ff4b7c-hqrlq 1/1 Terminating 0 1s
web-6fd8ff4b7c-wmsnk 1/1 Terminating 0 9s
web-6fd8ff4b7c-xq6sl 1/1 Terminating 0 17s

Put it into practice

The lab replays the scenario of the lesson on a cluster of virtual machines: it makes you go back to the revision that worked after a wrong image, then ship the right image. The validation reads the ReplicaSets and their revision numbers, which tell what happened, where a Deployment recreated from scratch tells nothing.

Adapting this Deployment to several environments without duplicating it is the job of Kustomize, which has its own lab.

Key takeaways

  1. A Deployment creates a ReplicaSet, which creates the Pods; only a change to the template triggers a new rollout.
  2. During an update that fails, the old Pods stay in service: the rolling update stops without cutting the application.
  3. kubectl rollout history lists the revisions, and kubectl rollout undo reactivates the previous revision.
  4. The old ReplicaSet is kept at zero replicas; revisionHistoryLimit sets how many are kept.
  5. kubectl annotate deployment/web kubernetes.io/change-cause="…" --overwrite fills the CHANGE-CAUSE column; the why is in the lesson Rolling updates and rollbacks.
  6. RollingUpdate avoids downtime as long as the new Pods become ready, Recreate guarantees that only one version runs at a time.
  7. For a stateful application, use a StatefulSet, not a Deployment.

Test your knowledge

This quiz covers the difference between RollingUpdate and Recreate, the role of the ReplicaSet and the behavior of the rollback. Answer without going back: what blocks you points to the passage to reread.

Knowledge check

Check what you have learned with this interactive quiz

7 questions
5 min
80% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer

FAQ: frequently asked questions about Deployments

These questions come up when you start with Deployments: difference with a Pod, update, rollback, number of replicas.